1.1 --- a/en/tour.tex	Wed Oct 04 17:11:53 2006 -0700
     1.2 +++ b/en/tour.tex	Thu Oct 12 10:33:03 2006 -0700
     1.3 @@ -108,7 +108,7 @@
     1.4  You can rename delete a repository any time you like, using either the
     1.5  command line or your file browser.
     1.6  
     1.7 -\subsection{Making a copy of a repository}
     1.8 +\subsection{Making a local copy of a repository}
     1.9  
    1.10  \emph{Copying} a repository is just a little bit special.  While you
    1.11  could use a normal file copying command to make a copy of a
    1.12 @@ -132,6 +132,105 @@
    1.13  repository, safe in the knowledge that it's a private ``sandbox'' that
    1.14  won't affect anyone else.
    1.15  
    1.16 +\subsection{What's in a repository?}
    1.17 +
    1.18 +When we take a more detailed look inside a repository, we can see that
    1.19 +it contains a directory named \dirname{.hg}.  This is where Mercurial
    1.20 +keeps all of its metadata for the repository.
    1.21 +\interaction{tour.ls-a}
    1.22 +
    1.23 +The contents of the \dirname{.hg} directory and its subdirectories are
    1.24 +private to Mercurial.  Every other file and directory in the
    1.25 +repository is yours to do with as you please.
    1.26 +
    1.27 +To introduce a little terminology, the \dirname{.hg} directory is the
    1.28 +``real'' repository, and all of the files and directories that coexist
    1.29 +with it are said to live in the ``working directory''.  An easy way to
    1.30 +remember the distinction is that the \emph{repository} contains the
    1.31 +\emph{history} of your project, while the \emph{working directory}
    1.32 +contains a \emph{snapshot} of your project at a particular point in
    1.33 +history.
    1.34 +
    1.35 +\section{A tour through history}
    1.36 +
    1.37 +One of the first things we might want to do with a new, unfamiliar
    1.38 +repository is understand its history.  The \hgcmd{log} command gives
    1.39 +us a view of history.
    1.40 +\interaction{tour.log}
    1.41 +By default, this command prints a brief paragraph of output for each
    1.42 +change to the project that was recorded.  In Mercurial terminology, we
    1.43 +call each of these recorded events a \emph{changeset}, because it can
    1.44 +contain a record of changes to several files.
    1.45 +
    1.46 +The fields in a record of output from \hgcmd{log} are as follows.
    1.47 +\begin{itemize}
    1.48 +\item[\texttt{changeset}] This field has the format of a number,
    1.49 +  followed by a colon, followed by a hexadecimal string.  These are
    1.50 +  \emph{identifiers} for the changeset.  There are two identifiers
    1.51 +  because the number is shorter and easier to type than the hex
    1.52 +  string.
    1.53 +\item[\texttt{user}] The identity of the person who created the
    1.54 +  changeset.  This is a free-form field, but it most often contains a
    1.55 +  person's name and email address.
    1.56 +\item[\texttt{date}] The date and time on which the changeset was
    1.57 +  created, and the timezone in which it was created.  (Thef date and
    1.58 +  time are local to that timezone; they display what time and date it
    1.59 +  was for the person who created the changeset.)
    1.60 +\item[\texttt{summary}] The first line of the text message that the
    1.61 +  creator of the changeset entered to describe the changeset.
    1.62 +\end{itemize}
    1.63 +The default output printed by \hgcmd{log} is purely a summary; it is
    1.64 +missing a lot of detail.
    1.65 +
    1.66 +\subsection{Changesets, revisions, and identification}
    1.67 +
    1.68 +English being a notoriously sloppy language, we have a variety of
    1.69 +terms that have the same meaning.  If you are talking about Mercurial
    1.70 +history with other people, you will find that the word ``changeset''
    1.71 +is often compressed to ``change'' or ``cset'', and sometimes a
    1.72 +changeset is referred to as a ``revision'' or a ``rev''.
    1.73 +
    1.74 +While it doesn't matter what \emph{word} you use to refer to the
    1.75 +concept of ``a~changeset'', the \emph{identifier} that you use to
    1.76 +refer to ``a~\emph{specific} changeset'' is of great importance.
    1.77 +Recall that the \texttt{changeset} field in the output from
    1.78 +\hgcmd{log} identifies a changeset using both a number and a
    1.79 +hexadecimal string.  The number is \emph{only valid in that
    1.80 +  repository}, while the hex string is the \emph{permanent, unchanging
    1.81 +  identifier} that will always identify that changeset in every copy
    1.82 +of the repository.
    1.83 +
    1.84 +This distinction is important.  If you send someone an email talking
    1.85 +about ``revision~33'', there's a high likelihood that their
    1.86 +revision~33 will \emph{not be the same} as yours.  The reason for this
    1.87 +is that a revision number depends on the order in which changes
    1.88 +arrived in a repository, and there is no guarantee that the same
    1.89 +changes will happen in the same order in different repositories.
    1.90 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
    1.91 +while in another as $1,0,2$.
    1.92 +
    1.93 +Mercurial uses revision numbers purely as a convenient shorthand.  If
    1.94 +you need to discuss a changeset with someone, or make a record of a
    1.95 +changeset for some other reason (for example, in a bug report), use
    1.96 +the hexadecimal identifier.
    1.97 +
    1.98 +\subsection{Viewing specific revisions}
    1.99 +
   1.100 +To narrow the output of \hgcmd{log} down to a single revision, use the
   1.101 +\hgopt{log}{-r} option.  You can use either a revision number or a
   1.102 +long-form changeset identifier, and you can provide as many revisions
   1.103 +as you want.
   1.104 +\interaction{tour.log-r}
   1.105 +
   1.106 +If you want to see the history of several revisions without having to
   1.107 +list each one, you can use \emph{range notation}; this lets you
   1.108 +express the idea ``I want all revisions between $a$ and $b$,
   1.109 +inclusive''.
   1.110 +\interaction{tour.log.range}
   1.111 +Mercurial also honours the order in which you specify revisions, so
   1.112 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   1.113 +prints $4,3,2$.
   1.114 +
   1.115  %%% Local Variables: 
   1.116  %%% mode: latex
   1.117  %%% TeX-master: "00book"