1.1 --- a/en/examples/tour	Thu Oct 12 14:46:54 2006 -0700
     1.2 +++ b/en/examples/tour	Thu Oct 12 16:01:40 2006 -0700
     1.3 @@ -35,3 +35,73 @@
     1.4  #$ name: log.range
     1.5  
     1.6  hg log -r 2:4
     1.7 +
     1.8 +#$ name: log-v
     1.9 +
    1.10 +hg log -v -r 3
    1.11 +
    1.12 +#$ name: log-vp
    1.13 +
    1.14 +hg log -v -p -r 2
    1.15 +
    1.16 +#$ name: reclone
    1.17 +
    1.18 +cd ..
    1.19 +hg clone hello my-hello
    1.20 +cd my-hello
    1.21 +
    1.22 +#$ name: sed
    1.23 +
    1.24 +sed -i '/printf/a\\tprintf("hello again!\\n");' hello.c
    1.25 +
    1.26 +#$ name: status
    1.27 +
    1.28 +ls
    1.29 +hg status
    1.30 +
    1.31 +#$ name: diff
    1.32 +
    1.33 +hg diff
    1.34 +
    1.35 +#$ name:
    1.36 +
    1.37 +export HGEDITOR='echo Added an extra line of output >'
    1.38 +
    1.39 +#$ name: commit
    1.40 +
    1.41 +hg commit
    1.42 +
    1.43 +#$ name: tip
    1.44 +
    1.45 +hg tip -vp
    1.46 +
    1.47 +#$ name: clone-pull
    1.48 +
    1.49 +cd ..
    1.50 +hg clone hello hello-pull
    1.51 +
    1.52 +#$ name: incoming
    1.53 +
    1.54 +cd hello-pull
    1.55 +hg incoming ../my-hello
    1.56 +
    1.57 +#$ name: pull
    1.58 +
    1.59 +hg tip
    1.60 +hg pull ../my-hello
    1.61 +hg tip
    1.62 +
    1.63 +#$ name: update
    1.64 +
    1.65 +grep printf hello.c
    1.66 +hg update tip
    1.67 +grep printf hello.c
    1.68 +
    1.69 +#$ name: parents
    1.70 +
    1.71 +hg parents
    1.72 +
    1.73 +#$ name: older
    1.74 +
    1.75 +hg update 2
    1.76 +hg parents

     2.1 --- a/en/tour.tex	Thu Oct 12 14:46:54 2006 -0700
     2.2 +++ b/en/tour.tex	Thu Oct 12 16:01:40 2006 -0700
     2.3 @@ -145,8 +145,8 @@
     2.4  
     2.5  To introduce a little terminology, the \dirname{.hg} directory is the
     2.6  ``real'' repository, and all of the files and directories that coexist
     2.7 -with it are said to live in the ``working directory''.  An easy way to
     2.8 -remember the distinction is that the \emph{repository} contains the
     2.9 +with it are said to live in the \emph{working directory}.  An easy way
    2.10 +to remember the distinction is that the \emph{repository} contains the
    2.11  \emph{history} of your project, while the \emph{working directory}
    2.12  contains a \emph{snapshot} of your project at a particular point in
    2.13  history.
    2.14 @@ -217,10 +217,9 @@
    2.15  \subsection{Viewing specific revisions}
    2.16  
    2.17  To narrow the output of \hgcmd{log} down to a single revision, use the
    2.18 -\hgopt{log}{-r} option.  You can use either a revision number or a
    2.19 -long-form changeset identifier, and you can provide as many revisions
    2.20 -as you want.
    2.21 -\interaction{tour.log-r}
    2.22 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
    2.23 +revision number or a long-form changeset identifier, and you can
    2.24 +provide as many revisions as you want.  \interaction{tour.log-r}
    2.25  
    2.26  If you want to see the history of several revisions without having to
    2.27  list each one, you can use \emph{range notation}; this lets you
    2.28 @@ -231,6 +230,248 @@
    2.29  \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
    2.30  prints $4,3,2$.
    2.31  
    2.32 +\subsection{More detailed information}
    2.33 +
    2.34 +While the summary information printed by \hgcmd{log} is useful if you
    2.35 +already know what you're looking for, you may need to see a complete
    2.36 +description of the change, or a list of the files changed, if you're
    2.37 +trying to decide whether a changeset is the one you're looking for.
    2.38 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
    2.39 +option gives you this extra detail.
    2.40 +\interaction{tour.log-v}
    2.41 +
    2.42 +If you want to see both the description and content of a change, add
    2.43 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
    2.44 +the content of a change as a \emph{unified diff} (if you've never seen
    2.45 +a unified diff before, see section~\ref{sec:mq:patch} for an overview).
    2.46 +\interaction{tour.log-vp}
    2.47 +
    2.48 +\section{All about command options}
    2.49 +
    2.50 +Let's take a brief break from exploring Mercurial commands to discuss
    2.51 +a pattern in the way that they work; you may find this useful to keep
    2.52 +in mind as we continiue our tour.
    2.53 +
    2.54 +Mercurial has a consistent and straightforward approach to dealing
    2.55 +with the options that you can pass to commands.  It follows the
    2.56 +conventions for options that are common to modern Linux and Unix
    2.57 +systems.
    2.58 +\begin{itemize}
    2.59 +\item Every option has a long name.  For example, as we've already
    2.60 +  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
    2.61 +\item Most options have short names, too.  Instead of
    2.62 +  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
    2.63 +  some options don't have short names is that the options in question
    2.64 +  are rarely used.)
    2.65 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
    2.66 +  while short options start with one (e.g.~\hgopt{log}{-r}).
    2.67 +\item Option naming and usage is consistent across commands.  For
    2.68 +  example, every command that lets you specify a changeset~ID or
    2.69 +  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
    2.70 +  arguments.
    2.71 +\end{itemize}
    2.72 +In the examples throughout this book, I use short options instead of
    2.73 +long.  This just reflects my own preference, so don't read anything
    2.74 +significant into it.
    2.75 +
    2.76 +Most commands that print output of some kind will print more output
    2.77 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
    2.78 +when passed \hggopt{-q} (or \hggopt{--quiet}).
    2.79 +
    2.80 +\section{Making and reviewing changes}
    2.81 +
    2.82 +Now that we have a grasp of viewing history in Mercurial, let's take a
    2.83 +look at making some changes and examining them.
    2.84 +
    2.85 +The first thing we'll do is isolate our experiment in a repository of
    2.86 +its own.  We use the \hgcmd{clone} command, but we don't need to
    2.87 +clone a copy of the remote repository.  Since we already have a copy
    2.88 +of it locally, we can just clone that instead.  This is much faster
    2.89 +than cloning over the network, and cloning a local repository uses
    2.90 +less disk space in most cases, too.
    2.91 +\interaction{tour.reclone}
    2.92 +As an aside, it's often good practice to keep a ``pristine'' copy of a
    2.93 +remote repository around, which you can then make temporary clones of
    2.94 +to create sandboxes for each task you want to work on.  This lets you
    2.95 +work on multiple tasks in parallel, each isolated from the others
    2.96 +until it's complete and you're ready to integrate it back.  Because
    2.97 +local clones are so cheap, there's almost no overhead to cloning and
    2.98 +destroying repositories whenever you want.
    2.99 +
   2.100 +In our \dirname{my-hello} repository, we have a file
   2.101 +\filename{hello.c} that contains the classic ``hello, world'' program.
   2.102 +Let's use the ancient and venerable \command{sed} command to edit this
   2.103 +file so that it prints a second line of output.  (I'm only using
   2.104 +\command{sed} to do this because it's easy to write a scripted example
   2.105 +this way.  Since you're not under the same constraint, you probably
   2.106 +won't want to use \command{sed}; simply use your preferred text editor to
   2.107 +do the same thing.)
   2.108 +\interaction{tour.sed}
   2.109 +
   2.110 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   2.111 +about the files in the repository.
   2.112 +\interaction{tour.status}
   2.113 +The \hgcmd{status} command prints no output for some files, but a line
   2.114 +starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   2.115 +it to, \hgcmd{status} will not print any output for files that have
   2.116 +not been modified.  
   2.117 +
   2.118 +The ``\texttt{M}'' indicates that Mercurial has noticed that we
   2.119 +modified \filename{hello.c}.  Notice that we didn't need to
   2.120 +\emph{inform} Mercurial that we were going to modify the file before
   2.121 +we started, or that we had modified the file after we were done; it
   2.122 +was able to figure this out itself.
   2.123 +
   2.124 +It's a little bit helpful to know that we've modified
   2.125 +\filename{hello.c}, but we might prefer to know exactly \emph{what}
   2.126 +changes we've made to it.  To do this, we use the \hgcmd{diff}
   2.127 +command.
   2.128 +\interaction{tour.diff}
   2.129 +
   2.130 +\section{Recording changes in a new changeset}
   2.131 +
   2.132 +We can modify files, build and test our changes, and use
   2.133 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   2.134 +satisfied with what we've done and arrive at a natural stopping point
   2.135 +where we want to record our work in a new changeset.
   2.136 +
   2.137 +The \hgcmd{commit} command lets us create a new changeset; we'll
   2.138 +usually refer to this as ``making a commit'' or ``committing''.  
   2.139 +
   2.140 +\subsection{Writing a commit message}
   2.141 +
   2.142 +When we commit a change, Mercurial drops us into a text editor, to
   2.143 +enter a message that will describe the modifications we've made in
   2.144 +this changeset.  This is called the \emph{commit message}.  It will be
   2.145 +a record for readers of what we did and why, and it will be printed by
   2.146 +\hgcmd{log} after we've finished committing.
   2.147 +\interaction{tour.commit}
   2.148 +
   2.149 +The editor that the \hgcmd{commit} command drops us into will contain
   2.150 +an empty line, followed by a number of lines starting with
   2.151 +``\texttt{HG:}''.
   2.152 +\begin{codesample2}
   2.153 +  \emph{empty line}
   2.154 +  HG: changed hello.c
   2.155 +\end{codesample2}
   2.156 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   2.157 +them only to tell us which files it's recording changes to.  Modifying
   2.158 +or deleting these lines has no effect.
   2.159 +
   2.160 +\subsection{Writing a good commit message}
   2.161 +
   2.162 +Since \hgcmd{log} only prints the first line of a commit message by
   2.163 +default, it's best to write a commit message whose first line stands
   2.164 +alone.  Here's a real example of a commit message that \emph{doesn't}
   2.165 +follow this guideline, and hence has a summary that is not readable.
   2.166 +\begin{codesample2}
   2.167 +  changeset:   73:584af0e231be
   2.168 +  user:        Censored Person <censored.person@example.org>
   2.169 +  date:        Tue Sep 26 21:37:07 2006 -0700
   2.170 +  summary:     include buildmeister/commondefs.   Add an exports and install
   2.171 +\end{codesample2}
   2.172 +
   2.173 +As far as the remainder of the contents of the commit message are
   2.174 +concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   2.175 +interpret or care about the contents of the commit message, though
   2.176 +your project may have policies that dictate a certain kind of
   2.177 +formatting.
   2.178 +
   2.179 +My personal preference is for short, but informative, commit messages
   2.180 +that tell me something that I can't figure out with a quick glance at
   2.181 +the output of \hgcmdargs{log}{--patch}.
   2.182 +
   2.183 +\subsection{Aborting a commit}
   2.184 +
   2.185 +If you decide that you don't want to commit while in the middle of
   2.186 +editing a commit message, simply exit from your editor without saving
   2.187 +the file that it's editing.  This will cause nothing to happen to
   2.188 +either the repository or the working directory.
   2.189 +
   2.190 +If we run the \hgcmd{commit} command without any arguments, it records
   2.191 +all of the changes we've made, as reported by \hgcmd{status} and
   2.192 +\hgcmd{diff}.
   2.193 +
   2.194 +\subsection{Admiring our new handywork}
   2.195 +
   2.196 +Once we've finished the commit, we can use the \hgcmd{tip} command to
   2.197 +display the changeset we just created.  This command produces output
   2.198 +that is identical to \hgcmd{log}, but it only displays the newest
   2.199 +revision in the repository.
   2.200 +\interaction{tour.tip}
   2.201 +We refer to the newest revision in the repository as the tip revision,
   2.202 +or simply the tip.
   2.203 +
   2.204 +\section{Sharing changes}
   2.205 +
   2.206 +We mentioned earlier that repositories in Mercurial are
   2.207 +self-contained.  This means that the changeset we just created exists
   2.208 +only in our \dirname{my-hello} repository.  Let's look at a few ways
   2.209 +that we can propagate this change into other repositories.
   2.210 +
   2.211 +\subsection{Pulling changes from another repository}
   2.212 +\label{sec:tour:pull}
   2.213 +
   2.214 +To get started, let's clone our original \dirname{hello} repository,
   2.215 +which does not contain the change we just committed.  We'll call our
   2.216 +temporary repository \dirname{hello-pull}.
   2.217 +\interaction{tour.clone-pull}
   2.218 +
   2.219 +We'll use the \hgcmd{pull} command to bring changes from
   2.220 +\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   2.221 +pulling unknown changes into a repository is a somewhat scary
   2.222 +prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   2.223 +what changes the \hgcmd{pull} command \emph{would} pull into the
   2.224 +repository, without actually pulling the changes in.
   2.225 +\interaction{tour.incoming}
   2.226 +(Of course, someone could cause more changesets to appear in the
   2.227 +repository that we ran \hgcmd{incoming} in, before we get a chance to
   2.228 +\hgcmd{pull} the changes, so that we could end up pulling changes that we
   2.229 +didn't expect.)
   2.230 +
   2.231 +Bringing changes into a repository is a simple matter of running the
   2.232 +\hgcmd{pull} command, and telling it which repository to pull from.
   2.233 +\interaction{tour.pull}
   2.234 +As you can see from the before-and-after output of \hgcmd{tip}, we
   2.235 +have successfully pulled changes into our repository.  There remains
   2.236 +one step before we can work with those changes.
   2.237 +
   2.238 +\section{Updating the working directory}
   2.239 +
   2.240 +We have so far glossed over the relatioship between a repository and
   2.241 +its working directory.  The \hgcmd{pull} command that we ran in
   2.242 +section~\ref{sec:tour:pull} brought changes into the repository, but
   2.243 +if we check, there's no sign of those changes in the working
   2.244 +directory.  This is because \hgcmd{pull} does not (by default) touch
   2.245 +the working directory.  Instead, we use the \hgcmd{update} command to
   2.246 +do this.
   2.247 +\interaction{tour.update}
   2.248 +
   2.249 +It might seem a bit strange that \hgcmd{pull} doesn't update the
   2.250 +working directory automatically.  There's actually a good reason for
   2.251 +this: you can use \hgcmd{update} to update the working directory to
   2.252 +the state it was in at \emph{any revision} in the history of the
   2.253 +repository.  If you had the working directory updated to an old
   2.254 +revision---to hunt down the origin of a bug, say---and ran a
   2.255 +\hgcmd{pull} which automatically updated the working directory to a
   2.256 +new revision, you might not be terribly happy.
   2.257 +
   2.258 +However, since pull-then-update is such a common thing to do,
   2.259 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   2.260 +option to \hgcmd{pull}.
   2.261 +\begin{codesample2}
   2.262 +  hg pull -u
   2.263 +\end{codesample2}
   2.264 +
   2.265 +To find out what revision the working directory is at, use the
   2.266 +\hgcmd{parents} command.
   2.267 +\interaction{tour.parents}
   2.268 +To update the working directory to a particular revision, give a
   2.269 +revision number or changeset~ID to the \hgcmd{update} command.
   2.270 +\interaction{tour.older}
   2.271 +If you omit an explicit revision, \hgcmd{update} will update to the
   2.272 +tip revision.
   2.273 +
   2.274  %%% Local Variables: 
   2.275  %%% mode: latex
   2.276  %%% TeX-master: "00book"