1.1 --- a/en/examples/tour	Wed Oct 04 17:11:53 2006 -0700
     1.2 +++ b/en/examples/tour	Thu Oct 12 10:33:03 2006 -0700
     1.3 @@ -16,3 +16,22 @@
     1.4  
     1.5  ls -l
     1.6  ls hello
     1.7 +
     1.8 +#$ name: ls-a
     1.9 +
    1.10 +cd hello
    1.11 +ls -a
    1.12 +
    1.13 +#$ name: log
    1.14 +
    1.15 +hg log
    1.16 +
    1.17 +#$ name: log-r
    1.18 +
    1.19 +hg log -r 3
    1.20 +hg log -r ff5d7b70a2a9
    1.21 +hg log -r 1 -r 4
    1.22 +
    1.23 +#$ name: log.range
    1.24 +
    1.25 +hg log -r 2:4

     2.1 --- a/en/tour.tex	Wed Oct 04 17:11:53 2006 -0700
     2.2 +++ b/en/tour.tex	Thu Oct 12 10:33:03 2006 -0700
     2.3 @@ -108,7 +108,7 @@
     2.4  You can rename delete a repository any time you like, using either the
     2.5  command line or your file browser.
     2.6  
     2.7 -\subsection{Making a copy of a repository}
     2.8 +\subsection{Making a local copy of a repository}
     2.9  
    2.10  \emph{Copying} a repository is just a little bit special.  While you
    2.11  could use a normal file copying command to make a copy of a
    2.12 @@ -132,6 +132,105 @@
    2.13  repository, safe in the knowledge that it's a private ``sandbox'' that
    2.14  won't affect anyone else.
    2.15  
    2.16 +\subsection{What's in a repository?}
    2.17 +
    2.18 +When we take a more detailed look inside a repository, we can see that
    2.19 +it contains a directory named \dirname{.hg}.  This is where Mercurial
    2.20 +keeps all of its metadata for the repository.
    2.21 +\interaction{tour.ls-a}
    2.22 +
    2.23 +The contents of the \dirname{.hg} directory and its subdirectories are
    2.24 +private to Mercurial.  Every other file and directory in the
    2.25 +repository is yours to do with as you please.
    2.26 +
    2.27 +To introduce a little terminology, the \dirname{.hg} directory is the
    2.28 +``real'' repository, and all of the files and directories that coexist
    2.29 +with it are said to live in the ``working directory''.  An easy way to
    2.30 +remember the distinction is that the \emph{repository} contains the
    2.31 +\emph{history} of your project, while the \emph{working directory}
    2.32 +contains a \emph{snapshot} of your project at a particular point in
    2.33 +history.
    2.34 +
    2.35 +\section{A tour through history}
    2.36 +
    2.37 +One of the first things we might want to do with a new, unfamiliar
    2.38 +repository is understand its history.  The \hgcmd{log} command gives
    2.39 +us a view of history.
    2.40 +\interaction{tour.log}
    2.41 +By default, this command prints a brief paragraph of output for each
    2.42 +change to the project that was recorded.  In Mercurial terminology, we
    2.43 +call each of these recorded events a \emph{changeset}, because it can
    2.44 +contain a record of changes to several files.
    2.45 +
    2.46 +The fields in a record of output from \hgcmd{log} are as follows.
    2.47 +\begin{itemize}
    2.48 +\item[\texttt{changeset}] This field has the format of a number,
    2.49 +  followed by a colon, followed by a hexadecimal string.  These are
    2.50 +  \emph{identifiers} for the changeset.  There are two identifiers
    2.51 +  because the number is shorter and easier to type than the hex
    2.52 +  string.
    2.53 +\item[\texttt{user}] The identity of the person who created the
    2.54 +  changeset.  This is a free-form field, but it most often contains a
    2.55 +  person's name and email address.
    2.56 +\item[\texttt{date}] The date and time on which the changeset was
    2.57 +  created, and the timezone in which it was created.  (Thef date and
    2.58 +  time are local to that timezone; they display what time and date it
    2.59 +  was for the person who created the changeset.)
    2.60 +\item[\texttt{summary}] The first line of the text message that the
    2.61 +  creator of the changeset entered to describe the changeset.
    2.62 +\end{itemize}
    2.63 +The default output printed by \hgcmd{log} is purely a summary; it is
    2.64 +missing a lot of detail.
    2.65 +
    2.66 +\subsection{Changesets, revisions, and identification}
    2.67 +
    2.68 +English being a notoriously sloppy language, we have a variety of
    2.69 +terms that have the same meaning.  If you are talking about Mercurial
    2.70 +history with other people, you will find that the word ``changeset''
    2.71 +is often compressed to ``change'' or ``cset'', and sometimes a
    2.72 +changeset is referred to as a ``revision'' or a ``rev''.
    2.73 +
    2.74 +While it doesn't matter what \emph{word} you use to refer to the
    2.75 +concept of ``a~changeset'', the \emph{identifier} that you use to
    2.76 +refer to ``a~\emph{specific} changeset'' is of great importance.
    2.77 +Recall that the \texttt{changeset} field in the output from
    2.78 +\hgcmd{log} identifies a changeset using both a number and a
    2.79 +hexadecimal string.  The number is \emph{only valid in that
    2.80 +  repository}, while the hex string is the \emph{permanent, unchanging
    2.81 +  identifier} that will always identify that changeset in every copy
    2.82 +of the repository.
    2.83 +
    2.84 +This distinction is important.  If you send someone an email talking
    2.85 +about ``revision~33'', there's a high likelihood that their
    2.86 +revision~33 will \emph{not be the same} as yours.  The reason for this
    2.87 +is that a revision number depends on the order in which changes
    2.88 +arrived in a repository, and there is no guarantee that the same
    2.89 +changes will happen in the same order in different repositories.
    2.90 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
    2.91 +while in another as $1,0,2$.
    2.92 +
    2.93 +Mercurial uses revision numbers purely as a convenient shorthand.  If
    2.94 +you need to discuss a changeset with someone, or make a record of a
    2.95 +changeset for some other reason (for example, in a bug report), use
    2.96 +the hexadecimal identifier.
    2.97 +
    2.98 +\subsection{Viewing specific revisions}
    2.99 +
   2.100 +To narrow the output of \hgcmd{log} down to a single revision, use the
   2.101 +\hgopt{log}{-r} option.  You can use either a revision number or a
   2.102 +long-form changeset identifier, and you can provide as many revisions
   2.103 +as you want.
   2.104 +\interaction{tour.log-r}
   2.105 +
   2.106 +If you want to see the history of several revisions without having to
   2.107 +list each one, you can use \emph{range notation}; this lets you
   2.108 +express the idea ``I want all revisions between $a$ and $b$,
   2.109 +inclusive''.
   2.110 +\interaction{tour.log.range}
   2.111 +Mercurial also honours the order in which you specify revisions, so
   2.112 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   2.113 +prints $4,3,2$.
   2.114 +
   2.115  %%% Local Variables: 
   2.116  %%% mode: latex
   2.117  %%% TeX-master: "00book"