hgbook

changeset 95:47ea206351d5

Split tour into two sections.
author Bryan O'Sullivan <bos@serpentine.com>
date Fri Oct 13 14:00:06 2006 -0700 (2006-10-13)
parents 0b97b0bdc830
children 7d7ddc3a57af
files en/00book.tex en/Makefile en/tour-basic.tex en/tour-merge.tex en/tour.tex
line diff
     1.1 --- a/en/00book.tex	Fri Oct 13 13:55:06 2006 -0700
     1.2 +++ b/en/00book.tex	Fri Oct 13 14:00:06 2006 -0700
     1.3 @@ -38,7 +38,8 @@
     1.4  \include{preface}
     1.5  \include{intro}
     1.6  %\include{concepts}
     1.7 -\include{tour}
     1.8 +\include{tour-basic}
     1.9 +\include{tour-merge}
    1.10  \include{daily}
    1.11  \include{hook}
    1.12  \include{template}
     2.1 --- a/en/Makefile	Fri Oct 13 13:55:06 2006 -0700
     2.2 +++ b/en/Makefile	Fri Oct 13 14:00:06 2006 -0700
     2.3 @@ -15,7 +15,8 @@
     2.4  	preface.tex \
     2.5  	srcinstall.tex \
     2.6  	template.tex \
     2.7 -	tour.tex
     2.8 +	tour-basic.tex \
     2.9 +	tour-merge.tex
    2.10  
    2.11  image-sources := \
    2.12  	mq-stack.svg
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/en/tour-basic.tex	Fri Oct 13 14:00:06 2006 -0700
     3.3 @@ -0,0 +1,519 @@
     3.4 +\chapter{A tour of Mercurial: the basics}
     3.5 +\label{chap:tour-basic}
     3.6 +
     3.7 +\section{Installing Mercurial on your system}
     3.8 +\label{sec:tour:install}
     3.9 +
    3.10 +Prebuilt binary packages of Mercurial are available for every popular
    3.11 +operating system.  These make it easy to start using Mercurial on your
    3.12 +computer immediately.
    3.13 +
    3.14 +\subsection{Linux}
    3.15 +
    3.16 +Because each Linux distribution has its own packaging tools, policies,
    3.17 +and rate of development, it's difficult to give a comprehensive set of
    3.18 +instructions on how to install Mercurial binaries.  The version of
    3.19 +Mercurial that you will end up with can vary depending on how active
    3.20 +the person is who maintains the package for your distribution.
    3.21 +
    3.22 +To keep things simple, I will focus on installing Mercurial from the
    3.23 +command line under the most popular Linux distributions.  Most of
    3.24 +these distributions provide graphical package managers that will let
    3.25 +you install Mercurial with a single click; the package name to look
    3.26 +for is \texttt{mercurial}.
    3.27 +
    3.28 +\begin{itemize}
    3.29 +\item[Debian]
    3.30 +  \begin{codesample4}
    3.31 +    apt-get install mercurial
    3.32 +  \end{codesample4}
    3.33 +
    3.34 +\item[Fedora Core]
    3.35 +  \begin{codesample4}
    3.36 +    yum install mercurial
    3.37 +  \end{codesample4}
    3.38 +
    3.39 +\item[Gentoo]
    3.40 +  \begin{codesample4}
    3.41 +    emerge mercurial
    3.42 +  \end{codesample4}
    3.43 +
    3.44 +\item[OpenSUSE]
    3.45 +  \begin{codesample4}
    3.46 +    yum install mercurial
    3.47 +  \end{codesample4}
    3.48 +
    3.49 +\item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
    3.50 +  should not use it.  If you know how, you can rebuild and install the
    3.51 +  Debian package.  It's probably easier to build Mercurial from source
    3.52 +  and simply run that; see section~\ref{sec:srcinstall:unixlike} for
    3.53 +  details.
    3.54 +\end{itemize}
    3.55 +
    3.56 +\subsection{Mac OS X}
    3.57 +
    3.58 +Lee Cantey publishes an installer of Mercurial for Mac OS~X at
    3.59 +\url{http://mercurial.berkwood.com}.  This package works on both
    3.60 +Intel-~and Power-based Macs.  Before you can use it, you must install
    3.61 +a compatible version of Universal MacPython~\cite{web:macpython}.  This
    3.62 +is easy to do; simply follow the instructions on Lee's site.
    3.63 +
    3.64 +\subsection{Solaris}
    3.65 +
    3.66 +XXX.
    3.67 +
    3.68 +\subsection{Windows}
    3.69 +
    3.70 +Lee Cantey publishes an installer of Mercurial for Windows at
    3.71 +\url{http://mercurial.berkwood.com}.  This package has no external
    3.72 +dependencies; it ``just works''.
    3.73 +
    3.74 +\begin{note}
    3.75 +  The Windows version of Mercurial does not automatically convert line
    3.76 +  endings between Windows and Unix styles.  If you want to share work
    3.77 +  with Unix users, you must do a little additional configuration
    3.78 +  work. XXX Flesh this out.
    3.79 +\end{note}
    3.80 +
    3.81 +\section{Getting started}
    3.82 +
    3.83 +To begin, we'll use the \hgcmd{version} command to find out whether
    3.84 +Mercurial is actually installed properly.  The actual version
    3.85 +information that it prints isn't so important; it's whether it prints
    3.86 +anything at all that we care about.
    3.87 +\interaction{tour.version}
    3.88 +
    3.89 +\subsection{Built-in help}
    3.90 +
    3.91 +Mercurial provides a built-in help system.  This invaluable for those
    3.92 +times when you find yourself stuck trying to remember how to run a
    3.93 +command.  If you are completely stuck, simply run \hgcmd{help}; it
    3.94 +will print a brief list of commands, along with a description of what
    3.95 +each does.  If you ask for help on a specific command (as below), it
    3.96 +prints more detailed information.
    3.97 +\interaction{tour.help}
    3.98 +For a more impressive level of detail (which you won't usually need)
    3.99 +run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
   3.100 +for \hggopt{--verbose}, and tells Mercurial to print more information
   3.101 +than it usually would.
   3.102 +
   3.103 +\section{Working with a repository}
   3.104 +
   3.105 +In Mercurial, everything happens inside a \emph{repository}.  The
   3.106 +repository for a project contains all of the files that ``belong to''
   3.107 +that project, along with a historical record of the project's files.
   3.108 +
   3.109 +There's nothing particularly magical about a repository; it is simply
   3.110 +a directory tree in your filesystem that Mercurial treats as special.
   3.111 +You can rename delete a repository any time you like, using either the
   3.112 +command line or your file browser.
   3.113 +
   3.114 +\subsection{Making a local copy of a repository}
   3.115 +
   3.116 +\emph{Copying} a repository is just a little bit special.  While you
   3.117 +could use a normal file copying command to make a copy of a
   3.118 +repository, it's best to use a built-in command that Mercurial
   3.119 +provides.  This command is called \hgcmd{clone}, because it creates an
   3.120 +identical copy of an existing repository.
   3.121 +\interaction{tour.clone}
   3.122 +If our clone succeeded, we should now have a local directory called
   3.123 +\dirname{hello}.  This directory will contain some files.
   3.124 +\interaction{tour.ls}
   3.125 +These files have the same contents and history in our repository as
   3.126 +they do in the repository we cloned.
   3.127 +
   3.128 +Every Mercurial repository is complete, self-contained, and
   3.129 +independent.  It contains its own private copy of a project's files
   3.130 +and history.  A cloned repository remembers the location of the
   3.131 +repository it was cloned from, but it does not communicate with that
   3.132 +repository, or any other, unless you tell it to.
   3.133 +
   3.134 +What this means for now is that we're free to experiment with our
   3.135 +repository, safe in the knowledge that it's a private ``sandbox'' that
   3.136 +won't affect anyone else.
   3.137 +
   3.138 +\subsection{What's in a repository?}
   3.139 +
   3.140 +When we take a more detailed look inside a repository, we can see that
   3.141 +it contains a directory named \dirname{.hg}.  This is where Mercurial
   3.142 +keeps all of its metadata for the repository.
   3.143 +\interaction{tour.ls-a}
   3.144 +
   3.145 +The contents of the \dirname{.hg} directory and its subdirectories are
   3.146 +private to Mercurial.  Every other file and directory in the
   3.147 +repository is yours to do with as you please.
   3.148 +
   3.149 +To introduce a little terminology, the \dirname{.hg} directory is the
   3.150 +``real'' repository, and all of the files and directories that coexist
   3.151 +with it are said to live in the \emph{working directory}.  An easy way
   3.152 +to remember the distinction is that the \emph{repository} contains the
   3.153 +\emph{history} of your project, while the \emph{working directory}
   3.154 +contains a \emph{snapshot} of your project at a particular point in
   3.155 +history.
   3.156 +
   3.157 +\section{A tour through history}
   3.158 +
   3.159 +One of the first things we might want to do with a new, unfamiliar
   3.160 +repository is understand its history.  The \hgcmd{log} command gives
   3.161 +us a view of history.
   3.162 +\interaction{tour.log}
   3.163 +By default, this command prints a brief paragraph of output for each
   3.164 +change to the project that was recorded.  In Mercurial terminology, we
   3.165 +call each of these recorded events a \emph{changeset}, because it can
   3.166 +contain a record of changes to several files.
   3.167 +
   3.168 +The fields in a record of output from \hgcmd{log} are as follows.
   3.169 +\begin{itemize}
   3.170 +\item[\texttt{changeset}] This field has the format of a number,
   3.171 +  followed by a colon, followed by a hexadecimal string.  These are
   3.172 +  \emph{identifiers} for the changeset.  There are two identifiers
   3.173 +  because the number is shorter and easier to type than the hex
   3.174 +  string.
   3.175 +\item[\texttt{user}] The identity of the person who created the
   3.176 +  changeset.  This is a free-form field, but it most often contains a
   3.177 +  person's name and email address.
   3.178 +\item[\texttt{date}] The date and time on which the changeset was
   3.179 +  created, and the timezone in which it was created.  (Thef date and
   3.180 +  time are local to that timezone; they display what time and date it
   3.181 +  was for the person who created the changeset.)
   3.182 +\item[\texttt{summary}] The first line of the text message that the
   3.183 +  creator of the changeset entered to describe the changeset.
   3.184 +\end{itemize}
   3.185 +The default output printed by \hgcmd{log} is purely a summary; it is
   3.186 +missing a lot of detail.
   3.187 +
   3.188 +\subsection{Changesets, revisions, and identification}
   3.189 +
   3.190 +English being a notoriously sloppy language, we have a variety of
   3.191 +terms that have the same meaning.  If you are talking about Mercurial
   3.192 +history with other people, you will find that the word ``changeset''
   3.193 +is often compressed to ``change'' or ``cset'', and sometimes a
   3.194 +changeset is referred to as a ``revision'' or a ``rev''.
   3.195 +
   3.196 +While it doesn't matter what \emph{word} you use to refer to the
   3.197 +concept of ``a~changeset'', the \emph{identifier} that you use to
   3.198 +refer to ``a~\emph{specific} changeset'' is of great importance.
   3.199 +Recall that the \texttt{changeset} field in the output from
   3.200 +\hgcmd{log} identifies a changeset using both a number and a
   3.201 +hexadecimal string.  The number is \emph{only valid in that
   3.202 +  repository}, while the hex string is the \emph{permanent, unchanging
   3.203 +  identifier} that will always identify that changeset in every copy
   3.204 +of the repository.
   3.205 +
   3.206 +This distinction is important.  If you send someone an email talking
   3.207 +about ``revision~33'', there's a high likelihood that their
   3.208 +revision~33 will \emph{not be the same} as yours.  The reason for this
   3.209 +is that a revision number depends on the order in which changes
   3.210 +arrived in a repository, and there is no guarantee that the same
   3.211 +changes will happen in the same order in different repositories.
   3.212 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
   3.213 +while in another as $1,0,2$.
   3.214 +
   3.215 +Mercurial uses revision numbers purely as a convenient shorthand.  If
   3.216 +you need to discuss a changeset with someone, or make a record of a
   3.217 +changeset for some other reason (for example, in a bug report), use
   3.218 +the hexadecimal identifier.
   3.219 +
   3.220 +\subsection{Viewing specific revisions}
   3.221 +
   3.222 +To narrow the output of \hgcmd{log} down to a single revision, use the
   3.223 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
   3.224 +revision number or a long-form changeset identifier, and you can
   3.225 +provide as many revisions as you want.  \interaction{tour.log-r}
   3.226 +
   3.227 +If you want to see the history of several revisions without having to
   3.228 +list each one, you can use \emph{range notation}; this lets you
   3.229 +express the idea ``I want all revisions between $a$ and $b$,
   3.230 +inclusive''.
   3.231 +\interaction{tour.log.range}
   3.232 +Mercurial also honours the order in which you specify revisions, so
   3.233 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   3.234 +prints $4,3,2$.
   3.235 +
   3.236 +\subsection{More detailed information}
   3.237 +
   3.238 +While the summary information printed by \hgcmd{log} is useful if you
   3.239 +already know what you're looking for, you may need to see a complete
   3.240 +description of the change, or a list of the files changed, if you're
   3.241 +trying to decide whether a changeset is the one you're looking for.
   3.242 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
   3.243 +option gives you this extra detail.
   3.244 +\interaction{tour.log-v}
   3.245 +
   3.246 +If you want to see both the description and content of a change, add
   3.247 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
   3.248 +the content of a change as a \emph{unified diff} (if you've never seen
   3.249 +a unified diff before, see section~\ref{sec:mq:patch} for an overview).
   3.250 +\interaction{tour.log-vp}
   3.251 +
   3.252 +\section{All about command options}
   3.253 +
   3.254 +Let's take a brief break from exploring Mercurial commands to discuss
   3.255 +a pattern in the way that they work; you may find this useful to keep
   3.256 +in mind as we continiue our tour.
   3.257 +
   3.258 +Mercurial has a consistent and straightforward approach to dealing
   3.259 +with the options that you can pass to commands.  It follows the
   3.260 +conventions for options that are common to modern Linux and Unix
   3.261 +systems.
   3.262 +\begin{itemize}
   3.263 +\item Every option has a long name.  For example, as we've already
   3.264 +  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
   3.265 +\item Most options have short names, too.  Instead of
   3.266 +  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
   3.267 +  some options don't have short names is that the options in question
   3.268 +  are rarely used.)
   3.269 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
   3.270 +  while short options start with one (e.g.~\hgopt{log}{-r}).
   3.271 +\item Option naming and usage is consistent across commands.  For
   3.272 +  example, every command that lets you specify a changeset~ID or
   3.273 +  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
   3.274 +  arguments.
   3.275 +\end{itemize}
   3.276 +In the examples throughout this book, I use short options instead of
   3.277 +long.  This just reflects my own preference, so don't read anything
   3.278 +significant into it.
   3.279 +
   3.280 +Most commands that print output of some kind will print more output
   3.281 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
   3.282 +when passed \hggopt{-q} (or \hggopt{--quiet}).
   3.283 +
   3.284 +\section{Making and reviewing changes}
   3.285 +
   3.286 +Now that we have a grasp of viewing history in Mercurial, let's take a
   3.287 +look at making some changes and examining them.
   3.288 +
   3.289 +The first thing we'll do is isolate our experiment in a repository of
   3.290 +its own.  We use the \hgcmd{clone} command, but we don't need to
   3.291 +clone a copy of the remote repository.  Since we already have a copy
   3.292 +of it locally, we can just clone that instead.  This is much faster
   3.293 +than cloning over the network, and cloning a local repository uses
   3.294 +less disk space in most cases, too.
   3.295 +\interaction{tour.reclone}
   3.296 +As an aside, it's often good practice to keep a ``pristine'' copy of a
   3.297 +remote repository around, which you can then make temporary clones of
   3.298 +to create sandboxes for each task you want to work on.  This lets you
   3.299 +work on multiple tasks in parallel, each isolated from the others
   3.300 +until it's complete and you're ready to integrate it back.  Because
   3.301 +local clones are so cheap, there's almost no overhead to cloning and
   3.302 +destroying repositories whenever you want.
   3.303 +
   3.304 +In our \dirname{my-hello} repository, we have a file
   3.305 +\filename{hello.c} that contains the classic ``hello, world'' program.
   3.306 +Let's use the ancient and venerable \command{sed} command to edit this
   3.307 +file so that it prints a second line of output.  (I'm only using
   3.308 +\command{sed} to do this because it's easy to write a scripted example
   3.309 +this way.  Since you're not under the same constraint, you probably
   3.310 +won't want to use \command{sed}; simply use your preferred text editor to
   3.311 +do the same thing.)
   3.312 +\interaction{tour.sed}
   3.313 +
   3.314 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   3.315 +about the files in the repository.
   3.316 +\interaction{tour.status}
   3.317 +The \hgcmd{status} command prints no output for some files, but a line
   3.318 +starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   3.319 +it to, \hgcmd{status} will not print any output for files that have
   3.320 +not been modified.  
   3.321 +
   3.322 +The ``\texttt{M}'' indicates that Mercurial has noticed that we
   3.323 +modified \filename{hello.c}.  Notice that we didn't need to
   3.324 +\emph{inform} Mercurial that we were going to modify the file before
   3.325 +we started, or that we had modified the file after we were done; it
   3.326 +was able to figure this out itself.
   3.327 +
   3.328 +It's a little bit helpful to know that we've modified
   3.329 +\filename{hello.c}, but we might prefer to know exactly \emph{what}
   3.330 +changes we've made to it.  To do this, we use the \hgcmd{diff}
   3.331 +command.
   3.332 +\interaction{tour.diff}
   3.333 +
   3.334 +\section{Recording changes in a new changeset}
   3.335 +
   3.336 +We can modify files, build and test our changes, and use
   3.337 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   3.338 +satisfied with what we've done and arrive at a natural stopping point
   3.339 +where we want to record our work in a new changeset.
   3.340 +
   3.341 +The \hgcmd{commit} command lets us create a new changeset; we'll
   3.342 +usually refer to this as ``making a commit'' or ``committing''.  
   3.343 +
   3.344 +\subsection{Writing a commit message}
   3.345 +
   3.346 +When we commit a change, Mercurial drops us into a text editor, to
   3.347 +enter a message that will describe the modifications we've made in
   3.348 +this changeset.  This is called the \emph{commit message}.  It will be
   3.349 +a record for readers of what we did and why, and it will be printed by
   3.350 +\hgcmd{log} after we've finished committing.
   3.351 +\interaction{tour.commit}
   3.352 +
   3.353 +The editor that the \hgcmd{commit} command drops us into will contain
   3.354 +an empty line, followed by a number of lines starting with
   3.355 +``\texttt{HG:}''.
   3.356 +\begin{codesample2}
   3.357 +  \emph{empty line}
   3.358 +  HG: changed hello.c
   3.359 +\end{codesample2}
   3.360 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   3.361 +them only to tell us which files it's recording changes to.  Modifying
   3.362 +or deleting these lines has no effect.
   3.363 +
   3.364 +\subsection{Writing a good commit message}
   3.365 +
   3.366 +Since \hgcmd{log} only prints the first line of a commit message by
   3.367 +default, it's best to write a commit message whose first line stands
   3.368 +alone.  Here's a real example of a commit message that \emph{doesn't}
   3.369 +follow this guideline, and hence has a summary that is not readable.
   3.370 +\begin{codesample2}
   3.371 +  changeset:   73:584af0e231be
   3.372 +  user:        Censored Person <censored.person@example.org>
   3.373 +  date:        Tue Sep 26 21:37:07 2006 -0700
   3.374 +  summary:     include buildmeister/commondefs.   Add an exports and install
   3.375 +\end{codesample2}
   3.376 +
   3.377 +As far as the remainder of the contents of the commit message are
   3.378 +concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   3.379 +interpret or care about the contents of the commit message, though
   3.380 +your project may have policies that dictate a certain kind of
   3.381 +formatting.
   3.382 +
   3.383 +My personal preference is for short, but informative, commit messages
   3.384 +that tell me something that I can't figure out with a quick glance at
   3.385 +the output of \hgcmdargs{log}{--patch}.
   3.386 +
   3.387 +\subsection{Aborting a commit}
   3.388 +
   3.389 +If you decide that you don't want to commit while in the middle of
   3.390 +editing a commit message, simply exit from your editor without saving
   3.391 +the file that it's editing.  This will cause nothing to happen to
   3.392 +either the repository or the working directory.
   3.393 +
   3.394 +If we run the \hgcmd{commit} command without any arguments, it records
   3.395 +all of the changes we've made, as reported by \hgcmd{status} and
   3.396 +\hgcmd{diff}.
   3.397 +
   3.398 +\subsection{Admiring our new handywork}
   3.399 +
   3.400 +Once we've finished the commit, we can use the \hgcmd{tip} command to
   3.401 +display the changeset we just created.  This command produces output
   3.402 +that is identical to \hgcmd{log}, but it only displays the newest
   3.403 +revision in the repository.
   3.404 +\interaction{tour.tip}
   3.405 +We refer to the newest revision in the repository as the tip revision,
   3.406 +or simply the tip.
   3.407 +
   3.408 +\section{Sharing changes}
   3.409 +
   3.410 +We mentioned earlier that repositories in Mercurial are
   3.411 +self-contained.  This means that the changeset we just created exists
   3.412 +only in our \dirname{my-hello} repository.  Let's look at a few ways
   3.413 +that we can propagate this change into other repositories.
   3.414 +
   3.415 +\subsection{Pulling changes from another repository}
   3.416 +\label{sec:tour:pull}
   3.417 +
   3.418 +To get started, let's clone our original \dirname{hello} repository,
   3.419 +which does not contain the change we just committed.  We'll call our
   3.420 +temporary repository \dirname{hello-pull}.
   3.421 +\interaction{tour.clone-pull}
   3.422 +
   3.423 +We'll use the \hgcmd{pull} command to bring changes from
   3.424 +\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   3.425 +pulling unknown changes into a repository is a somewhat scary
   3.426 +prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   3.427 +what changes the \hgcmd{pull} command \emph{would} pull into the
   3.428 +repository, without actually pulling the changes in.
   3.429 +\interaction{tour.incoming}
   3.430 +(Of course, someone could cause more changesets to appear in the
   3.431 +repository that we ran \hgcmd{incoming} in, before we get a chance to
   3.432 +\hgcmd{pull} the changes, so that we could end up pulling changes that we
   3.433 +didn't expect.)
   3.434 +
   3.435 +Bringing changes into a repository is a simple matter of running the
   3.436 +\hgcmd{pull} command, and telling it which repository to pull from.
   3.437 +\interaction{tour.pull}
   3.438 +As you can see from the before-and-after output of \hgcmd{tip}, we
   3.439 +have successfully pulled changes into our repository.  There remains
   3.440 +one step before we can see these changes in the working directory.
   3.441 +
   3.442 +\subsection{Updating the working directory}
   3.443 +
   3.444 +We have so far glossed over the relationship between a repository and
   3.445 +its working directory.  The \hgcmd{pull} command that we ran in
   3.446 +section~\ref{sec:tour:pull} brought changes into the repository, but
   3.447 +if we check, there's no sign of those changes in the working
   3.448 +directory.  This is because \hgcmd{pull} does not (by default) touch
   3.449 +the working directory.  Instead, we use the \hgcmd{update} command to
   3.450 +do this.
   3.451 +\interaction{tour.update}
   3.452 +
   3.453 +It might seem a bit strange that \hgcmd{pull} doesn't update the
   3.454 +working directory automatically.  There's actually a good reason for
   3.455 +this: you can use \hgcmd{update} to update the working directory to
   3.456 +the state it was in at \emph{any revision} in the history of the
   3.457 +repository.  If you had the working directory updated to an old
   3.458 +revision---to hunt down the origin of a bug, say---and ran a
   3.459 +\hgcmd{pull} which automatically updated the working directory to a
   3.460 +new revision, you might not be terribly happy.
   3.461 +
   3.462 +However, since pull-then-update is such a common thing to do,
   3.463 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   3.464 +option to \hgcmd{pull}.
   3.465 +\begin{codesample2}
   3.466 +  hg pull -u
   3.467 +\end{codesample2}
   3.468 +If you look back at the output of \hgcmd{pull} in
   3.469 +section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
   3.470 +you can see that it printed a helpful reminder that we'd have to take
   3.471 +an explicit step to update the working directory:
   3.472 +\begin{codesample2}
   3.473 +  (run 'hg update' to get a working copy)
   3.474 +\end{codesample2}
   3.475 +
   3.476 +To find out what revision the working directory is at, use the
   3.477 +\hgcmd{parents} command.
   3.478 +\interaction{tour.parents}
   3.479 +To update the working directory to a particular revision, give a
   3.480 +revision number or changeset~ID to the \hgcmd{update} command.
   3.481 +\interaction{tour.older}
   3.482 +If you omit an explicit revision, \hgcmd{update} will update to the
   3.483 +tip revision, as shown by the second call to \hgcmd{update} in the
   3.484 +example above.
   3.485 +
   3.486 +\subsection{Pushing changes to another repository}
   3.487 +
   3.488 +Mercurial lets us push changes to another repository, from the
   3.489 +repository we're currently visiting.  As with the example of
   3.490 +\hgcmd{pull} above, we'll create a temporary repository to push our
   3.491 +changes into.
   3.492 +\interaction{tour.clone-push}
   3.493 +The \hgcmd{outgoing} command tells us what changes would be pushed
   3.494 +into another repository.
   3.495 +\interaction{tour.outgoing}
   3.496 +And the \hgcmd{push} command does the actual push.
   3.497 +\interaction{tour.push}
   3.498 +As with \hgcmd{pull}, the \hgcmd{push} command does not update the
   3.499 +working directory in the repository that it's pushing changes into.
   3.500 +(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
   3.501 +option that updates the other repository's working directory.)
   3.502 +
   3.503 +What happens if we try to pull or push changes and the receiving
   3.504 +repository already has those changes?  Nothing too exciting.
   3.505 +\interaction{tour.push.nothing}
   3.506 +
   3.507 +\subsection{Sharing changes over a network}
   3.508 +
   3.509 +The commands we have covered in the previous few sections are not
   3.510 +limited to working with local repositories.  Each works in exactly the
   3.511 +same fashion over a network connection; simply pass in a URL instead
   3.512 +of a local path.
   3.513 +\interaction{tour.outgoing.net}
   3.514 +In this example, we can see what changes we could push to the remote
   3.515 +repository, but the repository is understandably not set up to let
   3.516 +anonymous users push to it.
   3.517 +\interaction{tour.push.net}
   3.518 +
   3.519 +%%% Local Variables: 
   3.520 +%%% mode: latex
   3.521 +%%% TeX-master: "00book"
   3.522 +%%% End: 
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/en/tour-merge.tex	Fri Oct 13 14:00:06 2006 -0700
     4.3 @@ -0,0 +1,64 @@
     4.4 +\chapter{A tour of Mercurial: merging work}
     4.5 +\label{chap:tour-merge}
     4.6 +
     4.7 +We've now covered cloning a repository, making changes in a
     4.8 +repository, and pulling or pushing changes from one repository into
     4.9 +another.  Our next step is \emph{merging} changes from separate
    4.10 +repositories.
    4.11 +
    4.12 +\section{Merging streams of work}
    4.13 +
    4.14 +Merging is a fundamental part of working with a distributed revision
    4.15 +control tool.
    4.16 +\begin{itemize}
    4.17 +\item Alice and Bob each have a personal copy of a repository for a
    4.18 +  project they're collaborating on.  Alice fixes a bug in her
    4.19 +  repository; Bob adds a new feature in his.  They want the shared
    4.20 +  repository to contain both the bug fix and the new feature.
    4.21 +\item I frequently work on several different tasks for a single
    4.22 +  project at once, each safely isolated in its own repository.
    4.23 +  Working this way means that I often need to merge one piece of my
    4.24 +  own work with another.
    4.25 +\end{itemize}
    4.26 +
    4.27 +Because merging is such a common thing to need to do, Mercurial makes
    4.28 +it easy.  Let's walk through the process.  We'll begin by cloning yet
    4.29 +another repository (see how often they spring up?) and making a change
    4.30 +in it.
    4.31 +\interaction{tour.merge.clone}
    4.32 +We should now have two copies of \filename{hello.c} with different
    4.33 +contents.
    4.34 +\interaction{tour.merge.cat}
    4.35 +
    4.36 +We already know that pulling changes from our \dirname{my-hello}
    4.37 +repository will have no effect on the working directory.
    4.38 +\interaction{tour.merge.pull}
    4.39 +However, the \hgcmd{pull} command says something about ``heads''.  
    4.40 +
    4.41 +A head is a change that has no descendants.  The tip revision is thus
    4.42 +a head, but a repository can contain more than one head.  We can view
    4.43 +them using the \hgcmd{heads} command.
    4.44 +\interaction{tour.merge.heads}
    4.45 +What happens if we try to use the normal \hgcmd{update} command to
    4.46 +update to the new tip?
    4.47 +\interaction{tour.merge.update}
    4.48 +Mercurial is telling us that the \hgcmd{update} command won't do a
    4.49 +merge.  Instead, we use the \hgcmd{merge} command to merge the two
    4.50 +heads.
    4.51 +\interaction{tour.merge.merge}
    4.52 +This updates the working directory so that it contains changes from
    4.53 +both heads, which is reflected in both the output of \hgcmd{parents}
    4.54 +and the contents of \filename{hello.c}.
    4.55 +\interaction{tour.merge.parents}
    4.56 +Whenever we've done a merge, \hgcmd{parents} will display two parents
    4.57 +until we \hgcmd{commit} the results of the merge.
    4.58 +\interaction{tour.merge.commit}
    4.59 +We now have a new tip revision; notice that it has \emph{both} of
    4.60 +our former heads as its parents.  These are the same revisions that
    4.61 +were previously displayed by \hgcmd{parents}.
    4.62 +\interaction{tour.merge.tip}
    4.63 +
    4.64 +%%% Local Variables: 
    4.65 +%%% mode: latex
    4.66 +%%% TeX-master: "00book"
    4.67 +%%% End: 
     5.1 --- a/en/tour.tex	Fri Oct 13 13:55:06 2006 -0700
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,576 +0,0 @@
     5.4 -\chapter{A lightning tour of Mercurial}
     5.5 -\label{chap:tour}
     5.6 -
     5.7 -\section{Installing Mercurial on your system}
     5.8 -\label{sec:tour:install}
     5.9 -
    5.10 -Prebuilt binary packages of Mercurial are available for every popular
    5.11 -operating system.  These make it easy to start using Mercurial on your
    5.12 -computer immediately.
    5.13 -
    5.14 -\subsection{Linux}
    5.15 -
    5.16 -Because each Linux distribution has its own packaging tools, policies,
    5.17 -and rate of development, it's difficult to give a comprehensive set of
    5.18 -instructions on how to install Mercurial binaries.  The version of
    5.19 -Mercurial that you will end up with can vary depending on how active
    5.20 -the person is who maintains the package for your distribution.
    5.21 -
    5.22 -To keep things simple, I will focus on installing Mercurial from the
    5.23 -command line under the most popular Linux distributions.  Most of
    5.24 -these distributions provide graphical package managers that will let
    5.25 -you install Mercurial with a single click; the package name to look
    5.26 -for is \texttt{mercurial}.
    5.27 -
    5.28 -\begin{itemize}
    5.29 -\item[Debian]
    5.30 -  \begin{codesample4}
    5.31 -    apt-get install mercurial
    5.32 -  \end{codesample4}
    5.33 -
    5.34 -\item[Fedora Core]
    5.35 -  \begin{codesample4}
    5.36 -    yum install mercurial
    5.37 -  \end{codesample4}
    5.38 -
    5.39 -\item[Gentoo]
    5.40 -  \begin{codesample4}
    5.41 -    emerge mercurial
    5.42 -  \end{codesample4}
    5.43 -
    5.44 -\item[OpenSUSE]
    5.45 -  \begin{codesample4}
    5.46 -    yum install mercurial
    5.47 -  \end{codesample4}
    5.48 -
    5.49 -\item[Ubuntu] Ubuntu's Mercurial package is particularly old, and you
    5.50 -  should not use it.  If you know how, you can rebuild and install the
    5.51 -  Debian package.  It's probably easier to build Mercurial from source
    5.52 -  and simply run that; see section~\ref{sec:srcinstall:unixlike} for
    5.53 -  details.
    5.54 -\end{itemize}
    5.55 -
    5.56 -\subsection{Mac OS X}
    5.57 -
    5.58 -Lee Cantey publishes an installer of Mercurial for Mac OS~X at
    5.59 -\url{http://mercurial.berkwood.com}.  This package works on both
    5.60 -Intel-~and Power-based Macs.  Before you can use it, you must install
    5.61 -a compatible version of Universal MacPython~\cite{web:macpython}.  This
    5.62 -is easy to do; simply follow the instructions on Lee's site.
    5.63 -
    5.64 -\subsection{Solaris}
    5.65 -
    5.66 -XXX.
    5.67 -
    5.68 -\subsection{Windows}
    5.69 -
    5.70 -Lee Cantey publishes an installer of Mercurial for Windows at
    5.71 -\url{http://mercurial.berkwood.com}.  This package has no external
    5.72 -dependencies; it ``just works''.
    5.73 -
    5.74 -\begin{note}
    5.75 -  The Windows version of Mercurial does not automatically convert line
    5.76 -  endings between Windows and Unix styles.  If you want to share work
    5.77 -  with Unix users, you must do a little additional configuration
    5.78 -  work. XXX Flesh this out.
    5.79 -\end{note}
    5.80 -
    5.81 -\section{Getting started}
    5.82 -
    5.83 -To begin, we'll use the \hgcmd{version} command to find out whether
    5.84 -Mercurial is actually installed properly.  The actual version
    5.85 -information that it prints isn't so important; it's whether it prints
    5.86 -anything at all that we care about.
    5.87 -\interaction{tour.version}
    5.88 -
    5.89 -\subsection{Built-in help}
    5.90 -
    5.91 -Mercurial provides a built-in help system.  This invaluable for those
    5.92 -times when you find yourself stuck trying to remember how to run a
    5.93 -command.  If you are completely stuck, simply run \hgcmd{help}; it
    5.94 -will print a brief list of commands, along with a description of what
    5.95 -each does.  If you ask for help on a specific command (as below), it
    5.96 -prints more detailed information.
    5.97 -\interaction{tour.help}
    5.98 -For a more impressive level of detail (which you won't usually need)
    5.99 -run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
   5.100 -for \hggopt{--verbose}, and tells Mercurial to print more information
   5.101 -than it usually would.
   5.102 -
   5.103 -\section{Working with a repository}
   5.104 -
   5.105 -In Mercurial, everything happens inside a \emph{repository}.  The
   5.106 -repository for a project contains all of the files that ``belong to''
   5.107 -that project, along with a historical record of the project's files.
   5.108 -
   5.109 -There's nothing particularly magical about a repository; it is simply
   5.110 -a directory tree in your filesystem that Mercurial treats as special.
   5.111 -You can rename delete a repository any time you like, using either the
   5.112 -command line or your file browser.
   5.113 -
   5.114 -\subsection{Making a local copy of a repository}
   5.115 -
   5.116 -\emph{Copying} a repository is just a little bit special.  While you
   5.117 -could use a normal file copying command to make a copy of a
   5.118 -repository, it's best to use a built-in command that Mercurial
   5.119 -provides.  This command is called \hgcmd{clone}, because it creates an
   5.120 -identical copy of an existing repository.
   5.121 -\interaction{tour.clone}
   5.122 -If our clone succeeded, we should now have a local directory called
   5.123 -\dirname{hello}.  This directory will contain some files.
   5.124 -\interaction{tour.ls}
   5.125 -These files have the same contents and history in our repository as
   5.126 -they do in the repository we cloned.
   5.127 -
   5.128 -Every Mercurial repository is complete, self-contained, and
   5.129 -independent.  It contains its own private copy of a project's files
   5.130 -and history.  A cloned repository remembers the location of the
   5.131 -repository it was cloned from, but it does not communicate with that
   5.132 -repository, or any other, unless you tell it to.
   5.133 -
   5.134 -What this means for now is that we're free to experiment with our
   5.135 -repository, safe in the knowledge that it's a private ``sandbox'' that
   5.136 -won't affect anyone else.
   5.137 -
   5.138 -\subsection{What's in a repository?}
   5.139 -
   5.140 -When we take a more detailed look inside a repository, we can see that
   5.141 -it contains a directory named \dirname{.hg}.  This is where Mercurial
   5.142 -keeps all of its metadata for the repository.
   5.143 -\interaction{tour.ls-a}
   5.144 -
   5.145 -The contents of the \dirname{.hg} directory and its subdirectories are
   5.146 -private to Mercurial.  Every other file and directory in the
   5.147 -repository is yours to do with as you please.
   5.148 -
   5.149 -To introduce a little terminology, the \dirname{.hg} directory is the
   5.150 -``real'' repository, and all of the files and directories that coexist
   5.151 -with it are said to live in the \emph{working directory}.  An easy way
   5.152 -to remember the distinction is that the \emph{repository} contains the
   5.153 -\emph{history} of your project, while the \emph{working directory}
   5.154 -contains a \emph{snapshot} of your project at a particular point in
   5.155 -history.
   5.156 -
   5.157 -\section{A tour through history}
   5.158 -
   5.159 -One of the first things we might want to do with a new, unfamiliar
   5.160 -repository is understand its history.  The \hgcmd{log} command gives
   5.161 -us a view of history.
   5.162 -\interaction{tour.log}
   5.163 -By default, this command prints a brief paragraph of output for each
   5.164 -change to the project that was recorded.  In Mercurial terminology, we
   5.165 -call each of these recorded events a \emph{changeset}, because it can
   5.166 -contain a record of changes to several files.
   5.167 -
   5.168 -The fields in a record of output from \hgcmd{log} are as follows.
   5.169 -\begin{itemize}
   5.170 -\item[\texttt{changeset}] This field has the format of a number,
   5.171 -  followed by a colon, followed by a hexadecimal string.  These are
   5.172 -  \emph{identifiers} for the changeset.  There are two identifiers
   5.173 -  because the number is shorter and easier to type than the hex
   5.174 -  string.
   5.175 -\item[\texttt{user}] The identity of the person who created the
   5.176 -  changeset.  This is a free-form field, but it most often contains a
   5.177 -  person's name and email address.
   5.178 -\item[\texttt{date}] The date and time on which the changeset was
   5.179 -  created, and the timezone in which it was created.  (Thef date and
   5.180 -  time are local to that timezone; they display what time and date it
   5.181 -  was for the person who created the changeset.)
   5.182 -\item[\texttt{summary}] The first line of the text message that the
   5.183 -  creator of the changeset entered to describe the changeset.
   5.184 -\end{itemize}
   5.185 -The default output printed by \hgcmd{log} is purely a summary; it is
   5.186 -missing a lot of detail.
   5.187 -
   5.188 -\subsection{Changesets, revisions, and identification}
   5.189 -
   5.190 -English being a notoriously sloppy language, we have a variety of
   5.191 -terms that have the same meaning.  If you are talking about Mercurial
   5.192 -history with other people, you will find that the word ``changeset''
   5.193 -is often compressed to ``change'' or ``cset'', and sometimes a
   5.194 -changeset is referred to as a ``revision'' or a ``rev''.
   5.195 -
   5.196 -While it doesn't matter what \emph{word} you use to refer to the
   5.197 -concept of ``a~changeset'', the \emph{identifier} that you use to
   5.198 -refer to ``a~\emph{specific} changeset'' is of great importance.
   5.199 -Recall that the \texttt{changeset} field in the output from
   5.200 -\hgcmd{log} identifies a changeset using both a number and a
   5.201 -hexadecimal string.  The number is \emph{only valid in that
   5.202 -  repository}, while the hex string is the \emph{permanent, unchanging
   5.203 -  identifier} that will always identify that changeset in every copy
   5.204 -of the repository.
   5.205 -
   5.206 -This distinction is important.  If you send someone an email talking
   5.207 -about ``revision~33'', there's a high likelihood that their
   5.208 -revision~33 will \emph{not be the same} as yours.  The reason for this
   5.209 -is that a revision number depends on the order in which changes
   5.210 -arrived in a repository, and there is no guarantee that the same
   5.211 -changes will happen in the same order in different repositories.
   5.212 -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
   5.213 -while in another as $1,0,2$.
   5.214 -
   5.215 -Mercurial uses revision numbers purely as a convenient shorthand.  If
   5.216 -you need to discuss a changeset with someone, or make a record of a
   5.217 -changeset for some other reason (for example, in a bug report), use
   5.218 -the hexadecimal identifier.
   5.219 -
   5.220 -\subsection{Viewing specific revisions}
   5.221 -
   5.222 -To narrow the output of \hgcmd{log} down to a single revision, use the
   5.223 -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
   5.224 -revision number or a long-form changeset identifier, and you can
   5.225 -provide as many revisions as you want.  \interaction{tour.log-r}
   5.226 -
   5.227 -If you want to see the history of several revisions without having to
   5.228 -list each one, you can use \emph{range notation}; this lets you
   5.229 -express the idea ``I want all revisions between $a$ and $b$,
   5.230 -inclusive''.
   5.231 -\interaction{tour.log.range}
   5.232 -Mercurial also honours the order in which you specify revisions, so
   5.233 -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   5.234 -prints $4,3,2$.
   5.235 -
   5.236 -\subsection{More detailed information}
   5.237 -
   5.238 -While the summary information printed by \hgcmd{log} is useful if you
   5.239 -already know what you're looking for, you may need to see a complete
   5.240 -description of the change, or a list of the files changed, if you're
   5.241 -trying to decide whether a changeset is the one you're looking for.
   5.242 -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
   5.243 -option gives you this extra detail.
   5.244 -\interaction{tour.log-v}
   5.245 -
   5.246 -If you want to see both the description and content of a change, add
   5.247 -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
   5.248 -the content of a change as a \emph{unified diff} (if you've never seen
   5.249 -a unified diff before, see section~\ref{sec:mq:patch} for an overview).
   5.250 -\interaction{tour.log-vp}
   5.251 -
   5.252 -\section{All about command options}
   5.253 -
   5.254 -Let's take a brief break from exploring Mercurial commands to discuss
   5.255 -a pattern in the way that they work; you may find this useful to keep
   5.256 -in mind as we continiue our tour.
   5.257 -
   5.258 -Mercurial has a consistent and straightforward approach to dealing
   5.259 -with the options that you can pass to commands.  It follows the
   5.260 -conventions for options that are common to modern Linux and Unix
   5.261 -systems.
   5.262 -\begin{itemize}
   5.263 -\item Every option has a long name.  For example, as we've already
   5.264 -  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
   5.265 -\item Most options have short names, too.  Instead of
   5.266 -  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
   5.267 -  some options don't have short names is that the options in question
   5.268 -  are rarely used.)
   5.269 -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
   5.270 -  while short options start with one (e.g.~\hgopt{log}{-r}).
   5.271 -\item Option naming and usage is consistent across commands.  For
   5.272 -  example, every command that lets you specify a changeset~ID or
   5.273 -  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
   5.274 -  arguments.
   5.275 -\end{itemize}
   5.276 -In the examples throughout this book, I use short options instead of
   5.277 -long.  This just reflects my own preference, so don't read anything
   5.278 -significant into it.
   5.279 -
   5.280 -Most commands that print output of some kind will print more output
   5.281 -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
   5.282 -when passed \hggopt{-q} (or \hggopt{--quiet}).
   5.283 -
   5.284 -\section{Making and reviewing changes}
   5.285 -
   5.286 -Now that we have a grasp of viewing history in Mercurial, let's take a
   5.287 -look at making some changes and examining them.
   5.288 -
   5.289 -The first thing we'll do is isolate our experiment in a repository of
   5.290 -its own.  We use the \hgcmd{clone} command, but we don't need to
   5.291 -clone a copy of the remote repository.  Since we already have a copy
   5.292 -of it locally, we can just clone that instead.  This is much faster
   5.293 -than cloning over the network, and cloning a local repository uses
   5.294 -less disk space in most cases, too.
   5.295 -\interaction{tour.reclone}
   5.296 -As an aside, it's often good practice to keep a ``pristine'' copy of a
   5.297 -remote repository around, which you can then make temporary clones of
   5.298 -to create sandboxes for each task you want to work on.  This lets you
   5.299 -work on multiple tasks in parallel, each isolated from the others
   5.300 -until it's complete and you're ready to integrate it back.  Because
   5.301 -local clones are so cheap, there's almost no overhead to cloning and
   5.302 -destroying repositories whenever you want.
   5.303 -
   5.304 -In our \dirname{my-hello} repository, we have a file
   5.305 -\filename{hello.c} that contains the classic ``hello, world'' program.
   5.306 -Let's use the ancient and venerable \command{sed} command to edit this
   5.307 -file so that it prints a second line of output.  (I'm only using
   5.308 -\command{sed} to do this because it's easy to write a scripted example
   5.309 -this way.  Since you're not under the same constraint, you probably
   5.310 -won't want to use \command{sed}; simply use your preferred text editor to
   5.311 -do the same thing.)
   5.312 -\interaction{tour.sed}
   5.313 -
   5.314 -Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   5.315 -about the files in the repository.
   5.316 -\interaction{tour.status}
   5.317 -The \hgcmd{status} command prints no output for some files, but a line
   5.318 -starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   5.319 -it to, \hgcmd{status} will not print any output for files that have
   5.320 -not been modified.  
   5.321 -
   5.322 -The ``\texttt{M}'' indicates that Mercurial has noticed that we
   5.323 -modified \filename{hello.c}.  Notice that we didn't need to
   5.324 -\emph{inform} Mercurial that we were going to modify the file before
   5.325 -we started, or that we had modified the file after we were done; it
   5.326 -was able to figure this out itself.
   5.327 -
   5.328 -It's a little bit helpful to know that we've modified
   5.329 -\filename{hello.c}, but we might prefer to know exactly \emph{what}
   5.330 -changes we've made to it.  To do this, we use the \hgcmd{diff}
   5.331 -command.
   5.332 -\interaction{tour.diff}
   5.333 -
   5.334 -\section{Recording changes in a new changeset}
   5.335 -
   5.336 -We can modify files, build and test our changes, and use
   5.337 -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   5.338 -satisfied with what we've done and arrive at a natural stopping point
   5.339 -where we want to record our work in a new changeset.
   5.340 -
   5.341 -The \hgcmd{commit} command lets us create a new changeset; we'll
   5.342 -usually refer to this as ``making a commit'' or ``committing''.  
   5.343 -
   5.344 -\subsection{Writing a commit message}
   5.345 -
   5.346 -When we commit a change, Mercurial drops us into a text editor, to
   5.347 -enter a message that will describe the modifications we've made in
   5.348 -this changeset.  This is called the \emph{commit message}.  It will be
   5.349 -a record for readers of what we did and why, and it will be printed by
   5.350 -\hgcmd{log} after we've finished committing.
   5.351 -\interaction{tour.commit}
   5.352 -
   5.353 -The editor that the \hgcmd{commit} command drops us into will contain
   5.354 -an empty line, followed by a number of lines starting with
   5.355 -``\texttt{HG:}''.
   5.356 -\begin{codesample2}
   5.357 -  \emph{empty line}
   5.358 -  HG: changed hello.c
   5.359 -\end{codesample2}
   5.360 -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   5.361 -them only to tell us which files it's recording changes to.  Modifying
   5.362 -or deleting these lines has no effect.
   5.363 -
   5.364 -\subsection{Writing a good commit message}
   5.365 -
   5.366 -Since \hgcmd{log} only prints the first line of a commit message by
   5.367 -default, it's best to write a commit message whose first line stands
   5.368 -alone.  Here's a real example of a commit message that \emph{doesn't}
   5.369 -follow this guideline, and hence has a summary that is not readable.
   5.370 -\begin{codesample2}
   5.371 -  changeset:   73:584af0e231be
   5.372 -  user:        Censored Person <censored.person@example.org>
   5.373 -  date:        Tue Sep 26 21:37:07 2006 -0700
   5.374 -  summary:     include buildmeister/commondefs.   Add an exports and install
   5.375 -\end{codesample2}
   5.376 -
   5.377 -As far as the remainder of the contents of the commit message are
   5.378 -concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   5.379 -interpret or care about the contents of the commit message, though
   5.380 -your project may have policies that dictate a certain kind of
   5.381 -formatting.
   5.382 -
   5.383 -My personal preference is for short, but informative, commit messages
   5.384 -that tell me something that I can't figure out with a quick glance at
   5.385 -the output of \hgcmdargs{log}{--patch}.
   5.386 -
   5.387 -\subsection{Aborting a commit}
   5.388 -
   5.389 -If you decide that you don't want to commit while in the middle of
   5.390 -editing a commit message, simply exit from your editor without saving
   5.391 -the file that it's editing.  This will cause nothing to happen to
   5.392 -either the repository or the working directory.
   5.393 -
   5.394 -If we run the \hgcmd{commit} command without any arguments, it records
   5.395 -all of the changes we've made, as reported by \hgcmd{status} and
   5.396 -\hgcmd{diff}.
   5.397 -
   5.398 -\subsection{Admiring our new handywork}
   5.399 -
   5.400 -Once we've finished the commit, we can use the \hgcmd{tip} command to
   5.401 -display the changeset we just created.  This command produces output
   5.402 -that is identical to \hgcmd{log}, but it only displays the newest
   5.403 -revision in the repository.
   5.404 -\interaction{tour.tip}
   5.405 -We refer to the newest revision in the repository as the tip revision,
   5.406 -or simply the tip.
   5.407 -
   5.408 -\section{Sharing changes}
   5.409 -
   5.410 -We mentioned earlier that repositories in Mercurial are
   5.411 -self-contained.  This means that the changeset we just created exists
   5.412 -only in our \dirname{my-hello} repository.  Let's look at a few ways
   5.413 -that we can propagate this change into other repositories.
   5.414 -
   5.415 -\subsection{Pulling changes from another repository}
   5.416 -\label{sec:tour:pull}
   5.417 -
   5.418 -To get started, let's clone our original \dirname{hello} repository,
   5.419 -which does not contain the change we just committed.  We'll call our
   5.420 -temporary repository \dirname{hello-pull}.
   5.421 -\interaction{tour.clone-pull}
   5.422 -
   5.423 -We'll use the \hgcmd{pull} command to bring changes from
   5.424 -\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   5.425 -pulling unknown changes into a repository is a somewhat scary
   5.426 -prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   5.427 -what changes the \hgcmd{pull} command \emph{would} pull into the
   5.428 -repository, without actually pulling the changes in.
   5.429 -\interaction{tour.incoming}
   5.430 -(Of course, someone could cause more changesets to appear in the
   5.431 -repository that we ran \hgcmd{incoming} in, before we get a chance to
   5.432 -\hgcmd{pull} the changes, so that we could end up pulling changes that we
   5.433 -didn't expect.)
   5.434 -
   5.435 -Bringing changes into a repository is a simple matter of running the
   5.436 -\hgcmd{pull} command, and telling it which repository to pull from.
   5.437 -\interaction{tour.pull}
   5.438 -As you can see from the before-and-after output of \hgcmd{tip}, we
   5.439 -have successfully pulled changes into our repository.  There remains
   5.440 -one step before we can see these changes in the working directory.
   5.441 -
   5.442 -\subsection{Updating the working directory}
   5.443 -
   5.444 -We have so far glossed over the relationship between a repository and
   5.445 -its working directory.  The \hgcmd{pull} command that we ran in
   5.446 -section~\ref{sec:tour:pull} brought changes into the repository, but
   5.447 -if we check, there's no sign of those changes in the working
   5.448 -directory.  This is because \hgcmd{pull} does not (by default) touch
   5.449 -the working directory.  Instead, we use the \hgcmd{update} command to
   5.450 -do this.
   5.451 -\interaction{tour.update}
   5.452 -
   5.453 -It might seem a bit strange that \hgcmd{pull} doesn't update the
   5.454 -working directory automatically.  There's actually a good reason for
   5.455 -this: you can use \hgcmd{update} to update the working directory to
   5.456 -the state it was in at \emph{any revision} in the history of the
   5.457 -repository.  If you had the working directory updated to an old
   5.458 -revision---to hunt down the origin of a bug, say---and ran a
   5.459 -\hgcmd{pull} which automatically updated the working directory to a
   5.460 -new revision, you might not be terribly happy.
   5.461 -
   5.462 -However, since pull-then-update is such a common thing to do,
   5.463 -Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   5.464 -option to \hgcmd{pull}.
   5.465 -\begin{codesample2}
   5.466 -  hg pull -u
   5.467 -\end{codesample2}
   5.468 -If you look back at the output of \hgcmd{pull} in
   5.469 -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
   5.470 -you can see that it printed a helpful reminder that we'd have to take
   5.471 -an explicit step to update the working directory:
   5.472 -\begin{codesample2}
   5.473 -  (run 'hg update' to get a working copy)
   5.474 -\end{codesample2}
   5.475 -
   5.476 -To find out what revision the working directory is at, use the
   5.477 -\hgcmd{parents} command.
   5.478 -\interaction{tour.parents}
   5.479 -To update the working directory to a particular revision, give a
   5.480 -revision number or changeset~ID to the \hgcmd{update} command.
   5.481 -\interaction{tour.older}
   5.482 -If you omit an explicit revision, \hgcmd{update} will update to the
   5.483 -tip revision, as shown by the second call to \hgcmd{update} in the
   5.484 -example above.
   5.485 -
   5.486 -\subsection{Pushing changes to another repository}
   5.487 -
   5.488 -Mercurial lets us push changes to another repository, from the
   5.489 -repository we're currently visiting.  As with the example of
   5.490 -\hgcmd{pull} above, we'll create a temporary repository to push our
   5.491 -changes into.
   5.492 -\interaction{tour.clone-push}
   5.493 -The \hgcmd{outgoing} command tells us what changes would be pushed
   5.494 -into another repository.
   5.495 -\interaction{tour.outgoing}
   5.496 -And the \hgcmd{push} command does the actual push.
   5.497 -\interaction{tour.push}
   5.498 -As with \hgcmd{pull}, the \hgcmd{push} command does not update the
   5.499 -working directory in the repository that it's pushing changes into.
   5.500 -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
   5.501 -option that updates the other repository's working directory.)
   5.502 -
   5.503 -What happens if we try to pull or push changes and the receiving
   5.504 -repository already has those changes?  Nothing too exciting.
   5.505 -\interaction{tour.push.nothing}
   5.506 -
   5.507 -\subsection{Sharing changes over a network}
   5.508 -
   5.509 -The commands we have covered in the previous few sections are not
   5.510 -limited to working with local repositories.  Each works in exactly the
   5.511 -same fashion over a network connection; simply pass in a URL instead
   5.512 -of a local path.
   5.513 -\interaction{tour.outgoing.net}
   5.514 -In this example, we can see what changes we could push to the remote
   5.515 -repository, but the repository is understandably not set up to let
   5.516 -anonymous users push to it.
   5.517 -\interaction{tour.push.net}
   5.518 -
   5.519 -\section{Merging streams of work}
   5.520 -
   5.521 -We've now covered cloning a repository, making changes in a
   5.522 -repository, and pulling or pushing changes from one repository into
   5.523 -another.  Our next step is \emph{merging} changes from separate
   5.524 -repositories.
   5.525 -
   5.526 -Merging is a fundamental part of working with a distributed revision
   5.527 -control tool.
   5.528 -\begin{itemize}
   5.529 -\item Alice and Bob each have a personal copy of a repository for a
   5.530 -  project they're collaborating on.  Alice fixes a bug in her
   5.531 -  repository; Bob adds a new feature in his.  They want the shared
   5.532 -  repository to contain both the bug fix and the new feature.
   5.533 -\item I frequently work on several different tasks for a single
   5.534 -  project at once, each safely isolated in its own repository.
   5.535 -  Working this way means that I often need to merge one piece of my
   5.536 -  own work with another.
   5.537 -\end{itemize}
   5.538 -
   5.539 -Because merging is such a common thing to need to do, Mercurial makes
   5.540 -it easy.  Let's walk through the process.  We'll begin by cloning yet
   5.541 -another repository (see how often they spring up?) and making a change
   5.542 -in it.
   5.543 -\interaction{tour.merge.clone}
   5.544 -We should now have two copies of \filename{hello.c} with different
   5.545 -contents.
   5.546 -\interaction{tour.merge.cat}
   5.547 -
   5.548 -We already know that pulling changes from our \dirname{my-hello}
   5.549 -repository will have no effect on the working directory.
   5.550 -\interaction{tour.merge.pull}
   5.551 -However, the \hgcmd{pull} command says something about ``heads''.  
   5.552 -
   5.553 -A head is a change that has no descendants.  The tip revision is thus
   5.554 -a head, but a repository can contain more than one head.  We can view
   5.555 -them using the \hgcmd{heads} command.
   5.556 -\interaction{tour.merge.heads}
   5.557 -What happens if we try to use the normal \hgcmd{update} command to
   5.558 -update to the new tip?
   5.559 -\interaction{tour.merge.update}
   5.560 -Mercurial is telling us that the \hgcmd{update} command won't do a
   5.561 -merge.  Instead, we use the \hgcmd{merge} command to merge the two
   5.562 -heads.
   5.563 -\interaction{tour.merge.merge}
   5.564 -This updates the working directory so that it contains changes from
   5.565 -both heads, which is reflected in both the output of \hgcmd{parents}
   5.566 -and the contents of \filename{hello.c}.
   5.567 -\interaction{tour.merge.parents}
   5.568 -Whenever we've done a merge, \hgcmd{parents} will display two parents
   5.569 -until we \hgcmd{commit} the results of the merge.
   5.570 -\interaction{tour.merge.commit}
   5.571 -We now have a new tip revision; notice that it has \emph{both} of
   5.572 -our former heads as its parents.  These are the same revisions that
   5.573 -were previously displayed by \hgcmd{parents}.
   5.574 -\interaction{tour.merge.tip}
   5.575 -
   5.576 -%%% Local Variables: 
   5.577 -%%% mode: latex
   5.578 -%%% TeX-master: "00book"
   5.579 -%%% End: