1.1 --- a/en/ch02-tour-basic.xml	Sun Aug 16 03:41:39 2009 +0200
     1.2 +++ b/en/ch02-tour-basic.xml	Tue Sep 01 17:00:12 2009 +0200
     1.3 @@ -1,624 +1,1035 @@
     1.4 -\chapter{A tour of Mercurial: the basics}
     1.5 -\label{chap:tour-basic}
     1.6 -
     1.7 -\section{Installing Mercurial on your system}
     1.8 -\label{sec:tour:install}
     1.9 -
    1.10 -Prebuilt binary packages of Mercurial are available for every popular
    1.11 -operating system.  These make it easy to start using Mercurial on your
    1.12 -computer immediately.
    1.13 -
    1.14 -\subsection{Linux}
    1.15 -
    1.16 -Because each Linux distribution has its own packaging tools, policies,
    1.17 -and rate of development, it's difficult to give a comprehensive set of
    1.18 -instructions on how to install Mercurial binaries.  The version of
    1.19 -Mercurial that you will end up with can vary depending on how active
    1.20 -the person is who maintains the package for your distribution.
    1.21 -
    1.22 -To keep things simple, I will focus on installing Mercurial from the
    1.23 -command line under the most popular Linux distributions.  Most of
    1.24 -these distributions provide graphical package managers that will let
    1.25 -you install Mercurial with a single click; the package name to look
    1.26 -for is \texttt{mercurial}.
    1.27 -
    1.28 -\begin{itemize}
    1.29 -\item[Debian]
    1.30 -  \begin{codesample4}
    1.31 -    apt-get install mercurial
    1.32 -  \end{codesample4}
    1.33 -
    1.34 -\item[Fedora Core]
    1.35 -  \begin{codesample4}
    1.36 -    yum install mercurial
    1.37 -  \end{codesample4}
    1.38 -
    1.39 -\item[Gentoo]
    1.40 -  \begin{codesample4}
    1.41 -    emerge mercurial
    1.42 -  \end{codesample4}
    1.43 -
    1.44 -\item[OpenSUSE]
    1.45 -  \begin{codesample4}
    1.46 -    yum install mercurial
    1.47 -  \end{codesample4}
    1.48 -
    1.49 -\item[Ubuntu] Ubuntu's Mercurial package is based on Debian's.  To
    1.50 -  install it, run the following command.
    1.51 -  \begin{codesample4}
    1.52 -    apt-get install mercurial
    1.53 -  \end{codesample4}
    1.54 -  The Ubuntu package for Mercurial tends to lag behind the Debian
    1.55 -  version by a considerable time margin (at the time of writing, seven
    1.56 -  months), which in some cases will mean that on Ubuntu, you may run
    1.57 -  into problems that have since been fixed in the Debian package.
    1.58 -\end{itemize}
    1.59 -
    1.60 -\subsection{Solaris}
    1.61 -
    1.62 -SunFreeWare, at \url{http://www.sunfreeware.com}, is a good source for a
    1.63 -large number of pre-built Solaris packages for 32 and 64 bit Intel and
    1.64 -Sparc architectures, including current versions of Mercurial.
    1.65 -
    1.66 -\subsection{Mac OS X}
    1.67 -
    1.68 -Lee Cantey publishes an installer of Mercurial for Mac OS~X at
    1.69 -\url{http://mercurial.berkwood.com}.  This package works on both
    1.70 -Intel-~and Power-based Macs.  Before you can use it, you must install
    1.71 -a compatible version of Universal MacPython~\cite{web:macpython}.  This
    1.72 -is easy to do; simply follow the instructions on Lee's site.
    1.73 -
    1.74 -It's also possible to install Mercurial using Fink or MacPorts,
    1.75 -two popular free package managers for Mac OS X.  If you have Fink,
    1.76 -use \command{sudo fink install mercurial-py25}.  If MacPorts,
    1.77 -\command{sudo port install mercurial}.
    1.78 -
    1.79 -\subsection{Windows}
    1.80 -
    1.81 -Lee Cantey publishes an installer of Mercurial for Windows at
    1.82 -\url{http://mercurial.berkwood.com}.  This package has no external
    1.83 -dependencies; it ``just works''.
    1.84 -
    1.85 -\begin{note}
    1.86 -  The Windows version of Mercurial does not automatically convert line
    1.87 -  endings between Windows and Unix styles.  If you want to share work
    1.88 -  with Unix users, you must do a little additional configuration
    1.89 -  work. XXX Flesh this out.
    1.90 -\end{note}
    1.91 -
    1.92 -\section{Getting started}
    1.93 -
    1.94 -To begin, we'll use the \hgcmd{version} command to find out whether
    1.95 -Mercurial is actually installed properly.  The actual version
    1.96 -information that it prints isn't so important; it's whether it prints
    1.97 -anything at all that we care about.
    1.98 -\interaction{tour.version}
    1.99 -
   1.100 -\subsection{Built-in help}
   1.101 -
   1.102 -Mercurial provides a built-in help system.  This is invaluable for those
   1.103 -times when you find yourself stuck trying to remember how to run a
   1.104 -command.  If you are completely stuck, simply run \hgcmd{help}; it
   1.105 -will print a brief list of commands, along with a description of what
   1.106 -each does.  If you ask for help on a specific command (as below), it
   1.107 -prints more detailed information.
   1.108 -\interaction{tour.help}
   1.109 -For a more impressive level of detail (which you won't usually need)
   1.110 -run \hgcmdargs{help}{\hggopt{-v}}.  The \hggopt{-v} option is short
   1.111 -for \hggopt{--verbose}, and tells Mercurial to print more information
   1.112 -than it usually would.
   1.113 -
   1.114 -\section{Working with a repository}
   1.115 -
   1.116 -In Mercurial, everything happens inside a \emph{repository}.  The
   1.117 -repository for a project contains all of the files that ``belong to''
   1.118 -that project, along with a historical record of the project's files.
   1.119 -
   1.120 -There's nothing particularly magical about a repository; it is simply
   1.121 -a directory tree in your filesystem that Mercurial treats as special.
   1.122 -You can rename or delete a repository any time you like, using either the
   1.123 -command line or your file browser.
   1.124 -
   1.125 -\subsection{Making a local copy of a repository}
   1.126 -
   1.127 -\emph{Copying} a repository is just a little bit special.  While you
   1.128 -could use a normal file copying command to make a copy of a
   1.129 -repository, it's best to use a built-in command that Mercurial
   1.130 -provides.  This command is called \hgcmd{clone}, because it creates an
   1.131 -identical copy of an existing repository.
   1.132 -\interaction{tour.clone}
   1.133 -If our clone succeeded, we should now have a local directory called
   1.134 -\dirname{hello}.  This directory will contain some files.
   1.135 -\interaction{tour.ls}
   1.136 -These files have the same contents and history in our repository as
   1.137 -they do in the repository we cloned.
   1.138 -
   1.139 -Every Mercurial repository is complete, self-contained, and
   1.140 -independent.  It contains its own private copy of a project's files
   1.141 -and history.  A cloned repository remembers the location of the
   1.142 -repository it was cloned from, but it does not communicate with that
   1.143 -repository, or any other, unless you tell it to.
   1.144 -
   1.145 -What this means for now is that we're free to experiment with our
   1.146 -repository, safe in the knowledge that it's a private ``sandbox'' that
   1.147 -won't affect anyone else.
   1.148 -
   1.149 -\subsection{What's in a repository?}
   1.150 -
   1.151 -When we take a more detailed look inside a repository, we can see that
   1.152 -it contains a directory named \dirname{.hg}.  This is where Mercurial
   1.153 -keeps all of its metadata for the repository.
   1.154 -\interaction{tour.ls-a}
   1.155 -
   1.156 -The contents of the \dirname{.hg} directory and its subdirectories are
   1.157 -private to Mercurial.  Every other file and directory in the
   1.158 -repository is yours to do with as you please.
   1.159 -
   1.160 -To introduce a little terminology, the \dirname{.hg} directory is the
   1.161 -``real'' repository, and all of the files and directories that coexist
   1.162 -with it are said to live in the \emph{working directory}.  An easy way
   1.163 -to remember the distinction is that the \emph{repository} contains the
   1.164 -\emph{history} of your project, while the \emph{working directory}
   1.165 -contains a \emph{snapshot} of your project at a particular point in
   1.166 -history.
   1.167 -
   1.168 -\section{A tour through history}
   1.169 -
   1.170 -One of the first things we might want to do with a new, unfamiliar
   1.171 -repository is understand its history.  The \hgcmd{log} command gives
   1.172 -us a view of history.
   1.173 -\interaction{tour.log}
   1.174 -By default, this command prints a brief paragraph of output for each
   1.175 -change to the project that was recorded.  In Mercurial terminology, we
   1.176 -call each of these recorded events a \emph{changeset}, because it can
   1.177 -contain a record of changes to several files.
   1.178 -
   1.179 -The fields in a record of output from \hgcmd{log} are as follows.
   1.180 -\begin{itemize}
   1.181 -\item[\texttt{changeset}] This field has the format of a number,
   1.182 -  followed by a colon, followed by a hexadecimal string.  These are
   1.183 -  \emph{identifiers} for the changeset.  There are two identifiers
   1.184 -  because the number is shorter and easier to type than the hex
   1.185 -  string.
   1.186 -\item[\texttt{user}] The identity of the person who created the
   1.187 -  changeset.  This is a free-form field, but it most often contains a
   1.188 -  person's name and email address.
   1.189 -\item[\texttt{date}] The date and time on which the changeset was
   1.190 -  created, and the timezone in which it was created.  (The date and
   1.191 -  time are local to that timezone; they display what time and date it
   1.192 -  was for the person who created the changeset.)
   1.193 -\item[\texttt{summary}] The first line of the text message that the
   1.194 -  creator of the changeset entered to describe the changeset.
   1.195 -\end{itemize}
   1.196 -The default output printed by \hgcmd{log} is purely a summary; it is
   1.197 -missing a lot of detail.
   1.198 -
   1.199 -Figure~\ref{fig:tour-basic:history} provides a graphical representation of
   1.200 -the history of the \dirname{hello} repository, to make it a little
   1.201 -easier to see which direction history is ``flowing'' in.  We'll be
   1.202 -returning to this figure several times in this chapter and the chapter
   1.203 -that follows.
   1.204 -
   1.205 -\begin{figure}[ht]
   1.206 -  \centering
   1.207 -  \grafix{tour-history}
   1.208 -  \caption{Graphical history of the \dirname{hello} repository}
   1.209 -  \label{fig:tour-basic:history}
   1.210 -\end{figure}
   1.211 -
   1.212 -\subsection{Changesets, revisions, and talking to other 
   1.213 -  people}
   1.214 -
   1.215 -As English is a notoriously sloppy language, and computer science has
   1.216 -a hallowed history of terminological confusion (why use one term when
   1.217 -four will do?), revision control has a variety of words and phrases
   1.218 -that mean the same thing.  If you are talking about Mercurial history
   1.219 -with other people, you will find that the word ``changeset'' is often
   1.220 -compressed to ``change'' or (when written) ``cset'', and sometimes a
   1.221 -changeset is referred to as a ``revision'' or a ``rev''.
   1.222 -
   1.223 -While it doesn't matter what \emph{word} you use to refer to the
   1.224 -concept of ``a~changeset'', the \emph{identifier} that you use to
   1.225 -refer to ``a~\emph{specific} changeset'' is of great importance.
   1.226 -Recall that the \texttt{changeset} field in the output from
   1.227 -\hgcmd{log} identifies a changeset using both a number and a
   1.228 -hexadecimal string.
   1.229 -\begin{itemize}
   1.230 -\item The revision number is \emph{only valid in that repository},
   1.231 -\item while the hex string is the \emph{permanent, unchanging
   1.232 -    identifier} that will always identify that exact changeset in
   1.233 -  \emph{every} copy of the repository.
   1.234 -\end{itemize}
   1.235 -This distinction is important.  If you send someone an email talking
   1.236 -about ``revision~33'', there's a high likelihood that their
   1.237 -revision~33 will \emph{not be the same} as yours.  The reason for this
   1.238 -is that a revision number depends on the order in which changes
   1.239 -arrived in a repository, and there is no guarantee that the same
   1.240 -changes will happen in the same order in different repositories.
   1.241 -Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
   1.242 -while in another as $1,0,2$.
   1.243 -
   1.244 -Mercurial uses revision numbers purely as a convenient shorthand.  If
   1.245 -you need to discuss a changeset with someone, or make a record of a
   1.246 -changeset for some other reason (for example, in a bug report), use
   1.247 -the hexadecimal identifier.
   1.248 -
   1.249 -\subsection{Viewing specific revisions}
   1.250 -
   1.251 -To narrow the output of \hgcmd{log} down to a single revision, use the
   1.252 -\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
   1.253 -revision number or a long-form changeset identifier, and you can
   1.254 -provide as many revisions as you want.  \interaction{tour.log-r}
   1.255 -
   1.256 -If you want to see the history of several revisions without having to
   1.257 -list each one, you can use \emph{range notation}; this lets you
   1.258 -express the idea ``I want all revisions between $a$ and $b$,
   1.259 -inclusive''.
   1.260 -\interaction{tour.log.range}
   1.261 -Mercurial also honours the order in which you specify revisions, so
   1.262 -\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   1.263 -prints $4,3,2$.
   1.264 -
   1.265 -\subsection{More detailed information}
   1.266 -
   1.267 -While the summary information printed by \hgcmd{log} is useful if you
   1.268 -already know what you're looking for, you may need to see a complete
   1.269 -description of the change, or a list of the files changed, if you're
   1.270 -trying to decide whether a changeset is the one you're looking for.
   1.271 -The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
   1.272 -option gives you this extra detail.
   1.273 -\interaction{tour.log-v}
   1.274 -
   1.275 -If you want to see both the description and content of a change, add
   1.276 -the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
   1.277 -the content of a change as a \emph{unified diff} (if you've never seen
   1.278 -a unified diff before, see section~\ref{sec:mq:patch} for an overview).
   1.279 -\interaction{tour.log-vp}
   1.280 -
   1.281 -\section{All about command options}
   1.282 -
   1.283 -Let's take a brief break from exploring Mercurial commands to discuss
   1.284 -a pattern in the way that they work; you may find this useful to keep
   1.285 -in mind as we continue our tour.
   1.286 -
   1.287 -Mercurial has a consistent and straightforward approach to dealing
   1.288 -with the options that you can pass to commands.  It follows the
   1.289 -conventions for options that are common to modern Linux and Unix
   1.290 -systems.
   1.291 -\begin{itemize}
   1.292 -\item Every option has a long name.  For example, as we've already
   1.293 -  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
   1.294 -\item Most options have short names, too.  Instead of
   1.295 -  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
   1.296 -  some options don't have short names is that the options in question
   1.297 -  are rarely used.)
   1.298 -\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
   1.299 -  while short options start with one (e.g.~\hgopt{log}{-r}).
   1.300 -\item Option naming and usage is consistent across commands.  For
   1.301 -  example, every command that lets you specify a changeset~ID or
   1.302 -  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
   1.303 -  arguments.
   1.304 -\end{itemize}
   1.305 -In the examples throughout this book, I use short options instead of
   1.306 -long.  This just reflects my own preference, so don't read anything
   1.307 -significant into it.
   1.308 -
   1.309 -Most commands that print output of some kind will print more output
   1.310 -when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
   1.311 -when passed \hggopt{-q} (or \hggopt{--quiet}).
   1.312 -
   1.313 -\section{Making and reviewing changes}
   1.314 -
   1.315 -Now that we have a grasp of viewing history in Mercurial, let's take a
   1.316 -look at making some changes and examining them.
   1.317 -
   1.318 -The first thing we'll do is isolate our experiment in a repository of
   1.319 -its own.  We use the \hgcmd{clone} command, but we don't need to
   1.320 -clone a copy of the remote repository.  Since we already have a copy
   1.321 -of it locally, we can just clone that instead.  This is much faster
   1.322 -than cloning over the network, and cloning a local repository uses
   1.323 -less disk space in most cases, too.
   1.324 -\interaction{tour.reclone}
   1.325 -As an aside, it's often good practice to keep a ``pristine'' copy of a
   1.326 -remote repository around, which you can then make temporary clones of
   1.327 -to create sandboxes for each task you want to work on.  This lets you
   1.328 -work on multiple tasks in parallel, each isolated from the others
   1.329 -until it's complete and you're ready to integrate it back.  Because
   1.330 -local clones are so cheap, there's almost no overhead to cloning and
   1.331 -destroying repositories whenever you want.
   1.332 -
   1.333 -In our \dirname{my-hello} repository, we have a file
   1.334 -\filename{hello.c} that contains the classic ``hello, world'' program.
   1.335 -Let's use the ancient and venerable \command{sed} command to edit this
   1.336 -file so that it prints a second line of output.  (I'm only using
   1.337 -\command{sed} to do this because it's easy to write a scripted example
   1.338 -this way.  Since you're not under the same constraint, you probably
   1.339 -won't want to use \command{sed}; simply use your preferred text editor to
   1.340 -do the same thing.)
   1.341 -\interaction{tour.sed}
   1.342 -
   1.343 -Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   1.344 -about the files in the repository.
   1.345 -\interaction{tour.status}
   1.346 -The \hgcmd{status} command prints no output for some files, but a line
   1.347 -starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   1.348 -it to, \hgcmd{status} will not print any output for files that have
   1.349 -not been modified.  
   1.350 -
   1.351 -The ``\texttt{M}'' indicates that Mercurial has noticed that we
   1.352 -modified \filename{hello.c}.  We didn't need to \emph{inform}
   1.353 -Mercurial that we were going to modify the file before we started, or
   1.354 -that we had modified the file after we were done; it was able to
   1.355 -figure this out itself.
   1.356 -
   1.357 -It's a little bit helpful to know that we've modified
   1.358 -\filename{hello.c}, but we might prefer to know exactly \emph{what}
   1.359 -changes we've made to it.  To do this, we use the \hgcmd{diff}
   1.360 -command.
   1.361 -\interaction{tour.diff}
   1.362 -
   1.363 -\section{Recording changes in a new changeset}
   1.364 -
   1.365 -We can modify files, build and test our changes, and use
   1.366 -\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   1.367 -satisfied with what we've done and arrive at a natural stopping point
   1.368 -where we want to record our work in a new changeset.
   1.369 -
   1.370 -The \hgcmd{commit} command lets us create a new changeset; we'll
   1.371 -usually refer to this as ``making a commit'' or ``committing''.  
   1.372 -
   1.373 -\subsection{Setting up a username}
   1.374 -
   1.375 -When you try to run \hgcmd{commit} for the first time, it is not
   1.376 -guaranteed to succeed.  Mercurial records your name and address with
   1.377 -each change that you commit, so that you and others will later be able
   1.378 -to tell who made each change.  Mercurial tries to automatically figure
   1.379 -out a sensible username to commit the change with.  It will attempt
   1.380 -each of the following methods, in order:
   1.381 -\begin{enumerate}
   1.382 -\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
   1.383 -  command on the command line, followed by a username, this is always
   1.384 -  given the highest precedence.
   1.385 -\item If you have set the \envar{HGUSER} environment variable, this is
   1.386 -  checked next.
   1.387 -\item If you create a file in your home directory called
   1.388 -  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
   1.389 -  used next.  To see what the contents of this file should look like,
   1.390 -  refer to section~\ref{sec:tour-basic:username} below.
   1.391 -\item If you have set the \envar{EMAIL} environment variable, this
   1.392 -  will be used next.
   1.393 -\item Mercurial will query your system to find out your local user
   1.394 -  name and host name, and construct a username from these components.
   1.395 -  Since this often results in a username that is not very useful, it
   1.396 -  will print a warning if it has to do this.
   1.397 -\end{enumerate}
   1.398 -If all of these mechanisms fail, Mercurial will fail, printing an
   1.399 -error message.  In this case, it will not let you commit until you set
   1.400 -up a username.
   1.401 -
   1.402 -You should think of the \envar{HGUSER} environment variable and the
   1.403 -\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
   1.404 -\emph{override} Mercurial's default selection of username.  For normal
   1.405 -use, the simplest and most robust way to set a username for yourself
   1.406 -is by creating a \sfilename{.hgrc} file; see below for details.
   1.407 -
   1.408 -\subsubsection{Creating a Mercurial configuration file}
   1.409 -\label{sec:tour-basic:username}
   1.410 -
   1.411 -To set a user name, use your favourite editor to create a file called
   1.412 -\sfilename{.hgrc} in your home directory.  Mercurial will use this
   1.413 -file to look up your personalised configuration settings.  The initial
   1.414 -contents of your \sfilename{.hgrc} should look like this.
   1.415 -\begin{codesample2}
   1.416 -  # This is a Mercurial configuration file.
   1.417 -  [ui]
   1.418 -  username = Firstname Lastname <email.address@domain.net>
   1.419 -\end{codesample2}
   1.420 -The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
   1.421 -so you can read the ``\texttt{username = ...}'' line as meaning ``set
   1.422 -the value of the \texttt{username} item in the \texttt{ui} section''.
   1.423 -A section continues until a new section begins, or the end of the
   1.424 -file.  Mercurial ignores empty lines and treats any text from
   1.425 -``\texttt{\#}'' to the end of a line as a comment.
   1.426 -
   1.427 -\subsubsection{Choosing a user name}
   1.428 -
   1.429 -You can use any text you like as the value of the \texttt{username}
   1.430 -config item, since this information is for reading by other people,
   1.431 -but for interpreting by Mercurial.  The convention that most people
   1.432 -follow is to use their name and email address, as in the example
   1.433 -above.
   1.434 -
   1.435 -\begin{note}
   1.436 -  Mercurial's built-in web server obfuscates email addresses, to make
   1.437 -  it more difficult for the email harvesting tools that spammers use.
   1.438 -  This reduces the likelihood that you'll start receiving more junk
   1.439 -  email if you publish a Mercurial repository on the web.
   1.440 -\end{note}
   1.441 -
   1.442 -\subsection{Writing a commit message}
   1.443 -
   1.444 -When we commit a change, Mercurial drops us into a text editor, to
   1.445 -enter a message that will describe the modifications we've made in
   1.446 -this changeset.  This is called the \emph{commit message}.  It will be
   1.447 -a record for readers of what we did and why, and it will be printed by
   1.448 -\hgcmd{log} after we've finished committing.
   1.449 -\interaction{tour.commit}
   1.450 -
   1.451 -The editor that the \hgcmd{commit} command drops us into will contain
   1.452 -an empty line, followed by a number of lines starting with
   1.453 -``\texttt{HG:}''.
   1.454 -\begin{codesample2}
   1.455 -  \emph{empty line}
   1.456 -  HG: changed hello.c
   1.457 -\end{codesample2}
   1.458 -Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   1.459 -them only to tell us which files it's recording changes to.  Modifying
   1.460 -or deleting these lines has no effect.
   1.461 -
   1.462 -\subsection{Writing a good commit message}
   1.463 -
   1.464 -Since \hgcmd{log} only prints the first line of a commit message by
   1.465 -default, it's best to write a commit message whose first line stands
   1.466 -alone.  Here's a real example of a commit message that \emph{doesn't}
   1.467 -follow this guideline, and hence has a summary that is not readable.
   1.468 -\begin{codesample2}
   1.469 -  changeset:   73:584af0e231be
   1.470 -  user:        Censored Person <censored.person@example.org>
   1.471 -  date:        Tue Sep 26 21:37:07 2006 -0700
   1.472 -  summary:     include buildmeister/commondefs.   Add an exports and install
   1.473 -\end{codesample2}
   1.474 -
   1.475 -As far as the remainder of the contents of the commit message are
   1.476 -concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   1.477 -interpret or care about the contents of the commit message, though
   1.478 -your project may have policies that dictate a certain kind of
   1.479 -formatting.
   1.480 -
   1.481 -My personal preference is for short, but informative, commit messages
   1.482 -that tell me something that I can't figure out with a quick glance at
   1.483 -the output of \hgcmdargs{log}{--patch}.
   1.484 -
   1.485 -\subsection{Aborting a commit}
   1.486 -
   1.487 -If you decide that you don't want to commit while in the middle of
   1.488 -editing a commit message, simply exit from your editor without saving
   1.489 -the file that it's editing.  This will cause nothing to happen to
   1.490 -either the repository or the working directory.
   1.491 -
   1.492 -If we run the \hgcmd{commit} command without any arguments, it records
   1.493 -all of the changes we've made, as reported by \hgcmd{status} and
   1.494 -\hgcmd{diff}.
   1.495 -
   1.496 -\subsection{Admiring our new handiwork}
   1.497 -
   1.498 -Once we've finished the commit, we can use the \hgcmd{tip} command to
   1.499 -display the changeset we just created.  This command produces output
   1.500 -that is identical to \hgcmd{log}, but it only displays the newest
   1.501 -revision in the repository.
   1.502 -\interaction{tour.tip}
   1.503 -We refer to the newest revision in the repository as the tip revision,
   1.504 -or simply the tip.
   1.505 -
   1.506 -\section{Sharing changes}
   1.507 -
   1.508 -We mentioned earlier that repositories in Mercurial are
   1.509 -self-contained.  This means that the changeset we just created exists
   1.510 -only in our \dirname{my-hello} repository.  Let's look at a few ways
   1.511 -that we can propagate this change into other repositories.
   1.512 -
   1.513 -\subsection{Pulling changes from another repository}
   1.514 -\label{sec:tour:pull}
   1.515 -
   1.516 -To get started, let's clone our original \dirname{hello} repository,
   1.517 -which does not contain the change we just committed.  We'll call our
   1.518 -temporary repository \dirname{hello-pull}.
   1.519 -\interaction{tour.clone-pull}
   1.520 -
   1.521 -We'll use the \hgcmd{pull} command to bring changes from
   1.522 -\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   1.523 -pulling unknown changes into a repository is a somewhat scary
   1.524 -prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   1.525 -what changes the \hgcmd{pull} command \emph{would} pull into the
   1.526 -repository, without actually pulling the changes in.
   1.527 -\interaction{tour.incoming}
   1.528 -(Of course, someone could cause more changesets to appear in the
   1.529 -repository that we ran \hgcmd{incoming} in, before we get a chance to
   1.530 -\hgcmd{pull} the changes, so that we could end up pulling changes that we
   1.531 -didn't expect.)
   1.532 -
   1.533 -Bringing changes into a repository is a simple matter of running the
   1.534 -\hgcmd{pull} command, and telling it which repository to pull from.
   1.535 -\interaction{tour.pull}
   1.536 -As you can see from the before-and-after output of \hgcmd{tip}, we
   1.537 -have successfully pulled changes into our repository.  There remains
   1.538 -one step before we can see these changes in the working directory.
   1.539 -
   1.540 -\subsection{Updating the working directory}
   1.541 -
   1.542 -We have so far glossed over the relationship between a repository and
   1.543 -its working directory.  The \hgcmd{pull} command that we ran in
   1.544 -section~\ref{sec:tour:pull} brought changes into the repository, but
   1.545 -if we check, there's no sign of those changes in the working
   1.546 -directory.  This is because \hgcmd{pull} does not (by default) touch
   1.547 -the working directory.  Instead, we use the \hgcmd{update} command to
   1.548 -do this.
   1.549 -\interaction{tour.update}
   1.550 -
   1.551 -It might seem a bit strange that \hgcmd{pull} doesn't update the
   1.552 -working directory automatically.  There's actually a good reason for
   1.553 -this: you can use \hgcmd{update} to update the working directory to
   1.554 -the state it was in at \emph{any revision} in the history of the
   1.555 -repository.  If you had the working directory updated to an old
   1.556 -revision---to hunt down the origin of a bug, say---and ran a
   1.557 -\hgcmd{pull} which automatically updated the working directory to a
   1.558 -new revision, you might not be terribly happy.
   1.559 -
   1.560 -However, since pull-then-update is such a common thing to do,
   1.561 -Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   1.562 -option to \hgcmd{pull}.
   1.563 -\begin{codesample2}
   1.564 -  hg pull -u
   1.565 -\end{codesample2}
   1.566 -If you look back at the output of \hgcmd{pull} in
   1.567 -section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
   1.568 -you can see that it printed a helpful reminder that we'd have to take
   1.569 -an explicit step to update the working directory:
   1.570 -\begin{codesample2}
   1.571 -  (run 'hg update' to get a working copy)
   1.572 -\end{codesample2}
   1.573 -
   1.574 -To find out what revision the working directory is at, use the
   1.575 -\hgcmd{parents} command.
   1.576 -\interaction{tour.parents}
   1.577 -If you look back at figure~\ref{fig:tour-basic:history}, you'll see
   1.578 -arrows connecting each changeset.  The node that the arrow leads
   1.579 -\emph{from} in each case is a parent, and the node that the arrow
   1.580 -leads \emph{to} is its child.  The working directory has a parent in
   1.581 -just the same way; this is the changeset that the working directory
   1.582 -currently contains.
   1.583 -
   1.584 -To update the working directory to a particular revision, give a
   1.585 -revision number or changeset~ID to the \hgcmd{update} command.
   1.586 -\interaction{tour.older}
   1.587 -If you omit an explicit revision, \hgcmd{update} will update to the
   1.588 -tip revision, as shown by the second call to \hgcmd{update} in the
   1.589 -example above.
   1.590 -
   1.591 -\subsection{Pushing changes to another repository}
   1.592 -
   1.593 -Mercurial lets us push changes to another repository, from the
   1.594 -repository we're currently visiting.  As with the example of
   1.595 -\hgcmd{pull} above, we'll create a temporary repository to push our
   1.596 -changes into.
   1.597 -\interaction{tour.clone-push}
   1.598 -The \hgcmd{outgoing} command tells us what changes would be pushed
   1.599 -into another repository.
   1.600 -\interaction{tour.outgoing}
   1.601 -And the \hgcmd{push} command does the actual push.
   1.602 -\interaction{tour.push}
   1.603 -As with \hgcmd{pull}, the \hgcmd{push} command does not update the
   1.604 -working directory in the repository that it's pushing changes into.
   1.605 -(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
   1.606 -option that updates the other repository's working directory.)
   1.607 -
   1.608 -What happens if we try to pull or push changes and the receiving
   1.609 -repository already has those changes?  Nothing too exciting.
   1.610 -\interaction{tour.push.nothing}
   1.611 -
   1.612 -\subsection{Sharing changes over a network}
   1.613 -
   1.614 -The commands we have covered in the previous few sections are not
   1.615 -limited to working with local repositories.  Each works in exactly the
   1.616 -same fashion over a network connection; simply pass in a URL instead
   1.617 -of a local path.
   1.618 -\interaction{tour.outgoing.net}
   1.619 -In this example, we can see what changes we could push to the remote
   1.620 -repository, but the repository is understandably not set up to let
   1.621 -anonymous users push to it.
   1.622 -\interaction{tour.push.net}
   1.623 -
   1.624 -%%% Local Variables: 
   1.625 -%%% mode: latex
   1.626 -%%% TeX-master: "00book"
   1.627 -%%% End: 
   1.628 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
   1.629 +
   1.630 +<chapter id="chap:tour-basic">
   1.631 +  <?dbhtml filename="a-tour-of-mercurial-the-basics.html"?>
   1.632 +  <title>A tour of Mercurial: the basics</title>
   1.633 +
   1.634 +  <sect1 id="sec:tour:install">
   1.635 +    <title>Installing Mercurial on your system</title>
   1.636 +
   1.637 +    <para id="x_1">Prebuilt binary packages of Mercurial are available for
   1.638 +      every popular operating system.  These make it easy to start
   1.639 +      using Mercurial on your computer immediately.</para>
   1.640 +
   1.641 +    <sect2>
   1.642 +      <title>Windows</title>
   1.643 +
   1.644 +      <para id="x_c">The best version of Mercurial for Windows is
   1.645 +	TortoiseHg, which can be found at <ulink
   1.646 +	  url="http://bitbucket.org/tortoisehg/stable/wiki/Home">http://bitbucket.org/tortoisehg/stable/wiki/Home</ulink>. 
   1.647 +	This package has no external dependencies; it <quote>just
   1.648 +	  works</quote>.  It provides both command line and graphical
   1.649 +	user interfaces.</para>
   1.650 +
   1.651 +    </sect2>
   1.652 +
   1.653 +    <sect2>
   1.654 +      <title>Mac OS X</title>
   1.655 +
   1.656 +      <para id="x_a">Lee Cantey publishes an installer of Mercurial
   1.657 +	for Mac OS X at <ulink
   1.658 +	  url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>.</para>
   1.659 +    </sect2>
   1.660 +
   1.661 +    <sect2>
   1.662 +      <title>Linux</title>
   1.663 +
   1.664 +      <para id="x_2">Because each Linux distribution has its own packaging
   1.665 +	tools, policies, and rate of development, it's difficult to
   1.666 +	give a comprehensive set of instructions on how to install
   1.667 +	Mercurial binaries.  The version of Mercurial that you will
   1.668 +	end up with can vary depending on how active the person is who
   1.669 +	maintains the package for your distribution.</para>
   1.670 +
   1.671 +      <para id="x_3">To keep things simple, I will focus on installing
   1.672 +	Mercurial from the command line under the most popular Linux
   1.673 +	distributions.  Most of these distributions provide graphical
   1.674 +	package managers that will let you install Mercurial with a
   1.675 +	single click; the package name to look for is
   1.676 +	<literal>mercurial</literal>.</para>
   1.677 +
   1.678 +      <itemizedlist>
   1.679 +	<listitem><para id="x_4">Ubuntu and Debian:</para>
   1.680 +	  <programlisting>apt-get install mercurial</programlisting></listitem>
   1.681 +	<listitem><para id="x_5">Fedora:</para>
   1.682 +	  <programlisting>yum install mercurial</programlisting></listitem>
   1.683 +	<listitem><para id="x_715">OpenSUSE:</para>
   1.684 +	  <programlisting>zypper install mercurial</programlisting></listitem>
   1.685 +	<listitem><para id="x_6">Gentoo:</para>
   1.686 +	  <programlisting>emerge mercurial</programlisting></listitem>
   1.687 +      </itemizedlist>
   1.688 +
   1.689 +    </sect2>
   1.690 +    <sect2>
   1.691 +      <title>Solaris</title>
   1.692 +
   1.693 +      <para id="x_9">SunFreeWare, at <ulink
   1.694 +	  url="http://www.sunfreeware.com">http://www.sunfreeware.com</ulink>, 
   1.695 +	provides prebuilt packages of Mercurial.</para>
   1.696 +
   1.697 +    </sect2>
   1.698 +
   1.699 +  </sect1>
   1.700 +
   1.701 +  <sect1>
   1.702 +    <title>Getting started</title>
   1.703 +
   1.704 +    <para id="x_e">To begin, we'll use the <command role="hg-cmd">hg
   1.705 +	version</command> command to find out whether Mercurial is
   1.706 +      installed properly.  The actual version information that it
   1.707 +      prints isn't so important; we simply care whether the command
   1.708 +      runs and prints anything at all.</para>
   1.709 +
   1.710 +    &interaction.tour.version;
   1.711 +
   1.712 +    <sect2>
   1.713 +      <title>Built-in help</title>
   1.714 +
   1.715 +      <para id="x_f">Mercurial provides a built-in help system.  This is
   1.716 +	  invaluable for those times when you find yourself stuck
   1.717 +	  trying to remember how to run a command.  If you are
   1.718 +	  completely stuck, simply run <command role="hg-cmd">hg
   1.719 +	    help</command>; it will print a brief list of commands,
   1.720 +	  along with a description of what each does.  If you ask for
   1.721 +	  help on a specific command (as below), it prints more
   1.722 +	  detailed information.</para>
   1.723 +
   1.724 +	&interaction.tour.help;
   1.725 +
   1.726 +	<para id="x_10">For a more impressive level of detail (which you won't
   1.727 +	  usually need) run <command role="hg-cmd">hg help <option
   1.728 +	      role="hg-opt-global">-v</option></command>.  The <option
   1.729 +	    role="hg-opt-global">-v</option> option is short for
   1.730 +	  <option role="hg-opt-global">--verbose</option>, and tells
   1.731 +	  Mercurial to print more information than it usually
   1.732 +	  would.</para>
   1.733 +
   1.734 +    </sect2>
   1.735 +  </sect1>
   1.736 +  <sect1>
   1.737 +    <title>Working with a repository</title>
   1.738 +
   1.739 +    <para id="x_11">In Mercurial, everything happens inside a
   1.740 +      <emphasis>repository</emphasis>.  The repository for a project
   1.741 +      contains all of the files that <quote>belong to</quote> that
   1.742 +      project, along with a historical record of the project's
   1.743 +      files.</para>
   1.744 +
   1.745 +    <para id="x_12">There's nothing particularly magical about a repository; it
   1.746 +      is simply a directory tree in your filesystem that Mercurial
   1.747 +      treats as special. You can rename or delete a repository any
   1.748 +      time you like, using either the command line or your file
   1.749 +      browser.</para>
   1.750 +
   1.751 +    <sect2>
   1.752 +      <title>Making a local copy of a repository</title>
   1.753 +
   1.754 +      <para id="x_13"><emphasis>Copying</emphasis> a repository is just a little
   1.755 +	bit special.  While you could use a normal file copying
   1.756 +	command to make a copy of a repository, it's best to use a
   1.757 +	built-in command that Mercurial provides.  This command is
   1.758 +	called <command role="hg-cmd">hg clone</command>, because it
   1.759 +	makes an identical copy of an existing repository.</para>
   1.760 +
   1.761 +      &interaction.tour.clone;
   1.762 +
   1.763 +      <para id="x_67c">One advantage of using <command role="hg-cmd">hg
   1.764 +	  clone</command> is that, as we can see above, it lets us clone
   1.765 +	repositories over the network.  Another is that it remembers
   1.766 +	where we cloned from, which we'll find useful soon when we
   1.767 +	want to fetch new changes from another repository.</para>
   1.768 +
   1.769 +      <para id="x_14">If our clone succeeded, we should now have a local
   1.770 +	directory called <filename class="directory">hello</filename>.
   1.771 +	This directory will contain some files.</para>
   1.772 +
   1.773 +      &interaction.tour.ls;
   1.774 +
   1.775 +      <para id="x_15">These files have the same contents and history in our
   1.776 +	repository as they do in the repository we cloned.</para>
   1.777 +
   1.778 +      <para id="x_16">Every Mercurial repository is complete,
   1.779 +	self-contained, and independent.  It contains its own private
   1.780 +	copy of a project's files and history.  As we just mentioned,
   1.781 +	a cloned repository remembers the location of the repository
   1.782 +	it was cloned from, but Mercurial will not communicate with
   1.783 +	that repository, or any other, unless you tell it to.</para>
   1.784 +
   1.785 +      <para id="x_17">What this means for now is that we're free to experiment
   1.786 +	with our repository, safe in the knowledge that it's a private
   1.787 +	<quote>sandbox</quote> that won't affect anyone else.</para>
   1.788 +
   1.789 +    </sect2>
   1.790 +    <sect2>
   1.791 +      <title>What's in a repository?</title>
   1.792 +
   1.793 +      <para id="x_18">When we take a more detailed look inside a repository, we
   1.794 +	can see that it contains a directory named <filename
   1.795 +	  class="directory">.hg</filename>.  This is where Mercurial
   1.796 +	keeps all of its metadata for the repository.</para>
   1.797 +
   1.798 +      &interaction.tour.ls-a;
   1.799 +
   1.800 +      <para id="x_19">The contents of the <filename
   1.801 +	  class="directory">.hg</filename> directory and its
   1.802 +	subdirectories are private to Mercurial.  Every other file and
   1.803 +	directory in the repository is yours to do with as you
   1.804 +	please.</para>
   1.805 +
   1.806 +      <para id="x_1a">To introduce a little terminology, the <filename
   1.807 +	  class="directory">.hg</filename> directory is the
   1.808 +	<quote>real</quote> repository, and all of the files and
   1.809 +	directories that coexist with it are said to live in the
   1.810 +	<emphasis>working directory</emphasis>.  An easy way to
   1.811 +	remember the distinction is that the
   1.812 +	<emphasis>repository</emphasis> contains the
   1.813 +	<emphasis>history</emphasis> of your project, while the
   1.814 +	<emphasis>working directory</emphasis> contains a
   1.815 +	<emphasis>snapshot</emphasis> of your project at a particular
   1.816 +	point in history.</para>
   1.817 +
   1.818 +    </sect2>
   1.819 +  </sect1>
   1.820 +  <sect1>
   1.821 +    <title>A tour through history</title>
   1.822 +
   1.823 +    <para id="x_1b">One of the first things we might want to do with a new,
   1.824 +      unfamiliar repository is understand its history.  The <command
   1.825 +	role="hg-cmd">hg log</command> command gives us a view of
   1.826 +      the history of changes in the repository.</para>
   1.827 +
   1.828 +    &interaction.tour.log;
   1.829 +
   1.830 +    <para id="x_1c">By default, this command prints a brief paragraph of output
   1.831 +      for each change to the project that was recorded.  In Mercurial
   1.832 +      terminology, we call each of these recorded events a
   1.833 +      <emphasis>changeset</emphasis>, because it can contain a record
   1.834 +      of changes to several files.</para>
   1.835 +
   1.836 +    <para id="x_1d">The fields in a record of output from <command
   1.837 +	role="hg-cmd">hg log</command> are as follows.</para>
   1.838 +
   1.839 +    <itemizedlist>
   1.840 +      <listitem><para id="x_1e"><literal>changeset</literal>: This
   1.841 +	  field has the format of a number, followed by a colon,
   1.842 +	  followed by a hexadecimal (or <emphasis>hex</emphasis>)
   1.843 +	  string.  These are <emphasis>identifiers</emphasis> for the
   1.844 +	  changeset.  The hex string is a unique identifier: the same
   1.845 +	  hex string will always refer to the same changeset in every
   1.846 +	  copy of this repository. The
   1.847 +	  number is shorter and easier to type than the hex string,
   1.848 +	  but it isn't unique: the same number in two different clones
   1.849 +	  of a repository may identify different changesets.</para>
   1.850 +      </listitem>
   1.851 +      <listitem><para id="x_1f"><literal>user</literal>: The identity of the
   1.852 +	  person who created the changeset.  This is a free-form
   1.853 +	  field, but it most often contains a person's name and email
   1.854 +	  address.</para></listitem>
   1.855 +      <listitem><para id="x_20"><literal>date</literal>: The date and time on
   1.856 +	  which the changeset was created, and the timezone in which
   1.857 +	  it was created.  (The date and time are local to that
   1.858 +	  timezone; they display what time and date it was for the
   1.859 +	  person who created the changeset.)</para></listitem>
   1.860 +      <listitem><para id="x_21"><literal>summary</literal>: The first line of
   1.861 +	  the text message that the creator of the changeset entered
   1.862 +	  to describe the changeset.</para></listitem>
   1.863 +      <listitem>
   1.864 +	<para id="x_67d">Some changesets, such as the first in the list above,
   1.865 +	  have a <literal>tag</literal> field.  A tag is another way
   1.866 +	  to identify a changeset, by giving it an easy-to-remember
   1.867 +	  name. (The tag named <literal>tip</literal> is special: it
   1.868 +	  always refers to the newest change in a repository.)</para>
   1.869 +      </listitem>
   1.870 +    </itemizedlist>
   1.871 +
   1.872 +    <para id="x_22">The default output printed by <command
   1.873 +	role="hg-cmd">hg log</command> is purely a summary; it is
   1.874 +      missing a lot of detail.</para>
   1.875 +
   1.876 +    <para id="x_23"><xref linkend="fig:tour-basic:history"/> provides
   1.877 +      a graphical representation of the history of the <filename
   1.878 +	class="directory">hello</filename> repository, to make it a
   1.879 +      little easier to see which direction history is
   1.880 +      <quote>flowing</quote> in.  We'll be returning to this figure
   1.881 +      several times in this chapter and the chapter that
   1.882 +      follows.</para>
   1.883 +
   1.884 +    <figure id="fig:tour-basic:history">
   1.885 +      <title>Graphical history of the <filename
   1.886 +	  class="directory">hello</filename> repository</title>
   1.887 +      <mediaobject>
   1.888 +	<imageobject><imagedata fileref="figs/tour-history.png"/></imageobject>
   1.889 +	<textobject><phrase>XXX add text</phrase></textobject>
   1.890 +      </mediaobject>
   1.891 +    </figure>
   1.892 +
   1.893 +    <sect2>
   1.894 +      <title>Changesets, revisions, and talking to other
   1.895 +	people</title>
   1.896 +
   1.897 +      <para id="x_25">As English is a notoriously sloppy language, and computer
   1.898 +	science has a hallowed history of terminological confusion
   1.899 +	(why use one term when four will do?), revision control has a
   1.900 +	variety of words and phrases that mean the same thing.  If you
   1.901 +	are talking about Mercurial history with other people, you
   1.902 +	will find that the word <quote>changeset</quote> is often
   1.903 +	compressed to <quote>change</quote> or (when written)
   1.904 +	<quote>cset</quote>, and sometimes a changeset is referred to
   1.905 +	as a <quote>revision</quote> or a <quote>rev</quote>.</para>
   1.906 +
   1.907 +      <para id="x_26">While it doesn't matter what <emphasis>word</emphasis> you
   1.908 +	use to refer to the concept of <quote>a changeset</quote>, the
   1.909 +	<emphasis>identifier</emphasis> that you use to refer to
   1.910 +	<quote>a <emphasis>specific</emphasis> changeset</quote> is of
   1.911 +	great importance. Recall that the <literal>changeset</literal>
   1.912 +	field in the output from <command role="hg-cmd">hg
   1.913 +	  log</command> identifies a changeset using both a number and
   1.914 +	a hexadecimal string.</para>
   1.915 +      <itemizedlist>
   1.916 +	<listitem><para id="x_27">The revision number is a handy
   1.917 +	    notation that is <emphasis>only valid in that
   1.918 +	      repository</emphasis>.</para></listitem>
   1.919 +	<listitem><para id="x_28">The hexadecimal string is the
   1.920 +	    <emphasis>permanent, unchanging identifier</emphasis> that
   1.921 +	    will always identify that exact changeset in
   1.922 +	    <emphasis>every</emphasis> copy of the
   1.923 +	    repository.</para></listitem></itemizedlist>
   1.924 +
   1.925 +      <para id="x_29">This distinction is important.  If you send
   1.926 +	someone an email talking about <quote>revision 33</quote>,
   1.927 +	there's a high likelihood that their revision 33 will
   1.928 +	<emphasis>not be the same</emphasis> as yours.  The reason for
   1.929 +	this is that a revision number depends on the order in which
   1.930 +	changes arrived in a repository, and there is no guarantee
   1.931 +	that the same changes will happen in the same order in
   1.932 +	different repositories. Three changes <literal>a,b,c</literal>
   1.933 +	can easily appear in one repository as
   1.934 +	<literal>0,1,2</literal>, while in another as
   1.935 +	<literal>0,2,1</literal>.</para>
   1.936 +
   1.937 +      <para id="x_2a">Mercurial uses revision numbers purely as a convenient
   1.938 +	shorthand.  If you need to discuss a changeset with someone,
   1.939 +	or make a record of a changeset for some other reason (for
   1.940 +	example, in a bug report), use the hexadecimal
   1.941 +	identifier.</para>
   1.942 +
   1.943 +    </sect2>
   1.944 +    <sect2>
   1.945 +      <title>Viewing specific revisions</title>
   1.946 +
   1.947 +      <para id="x_2b">To narrow the output of <command role="hg-cmd">hg
   1.948 +	  log</command> down to a single revision, use the <option
   1.949 +	  role="hg-opt-log">-r</option> (or <option
   1.950 +	  role="hg-opt-log">--rev</option>) option.  You can use
   1.951 +	either a revision number or a hexadecimal identifier,
   1.952 +	and you can provide as many revisions as you want.</para>
   1.953 +
   1.954 +      &interaction.tour.log-r;
   1.955 +
   1.956 +      <para id="x_2c">If you want to see the history of several revisions
   1.957 +	without having to list each one, you can use <emphasis>range
   1.958 +	  notation</emphasis>; this lets you express the idea <quote>I
   1.959 +	  want all revisions between <literal>abc</literal> and
   1.960 +	  <literal>def</literal>, inclusive</quote>.</para>
   1.961 +      
   1.962 +	&interaction.tour.log.range;
   1.963 +
   1.964 +      <para id="x_2d">Mercurial also honours the order in which you specify
   1.965 +	revisions, so <command role="hg-cmd">hg log -r 2:4</command>
   1.966 +	prints 2, 3, and 4. while <command role="hg-cmd">hg log -r
   1.967 +	  4:2</command> prints 4, 3, and 2.</para>
   1.968 +
   1.969 +    </sect2>
   1.970 +    <sect2>
   1.971 +      <title>More detailed information</title>
   1.972 +
   1.973 +      <para id="x_2e">While the summary information printed by <command
   1.974 +	  role="hg-cmd">hg log</command> is useful if you already know
   1.975 +	what you're looking for, you may need to see a complete
   1.976 +	description of the change, or a list of the files changed, if
   1.977 +	you're trying to decide whether a changeset is the one you're
   1.978 +	looking for. The <command role="hg-cmd">hg log</command>
   1.979 +	command's <option role="hg-opt-global">-v</option> (or <option
   1.980 +	  role="hg-opt-global">--verbose</option>) option gives you
   1.981 +	this extra detail.</para>
   1.982 +
   1.983 +      &interaction.tour.log-v;
   1.984 +
   1.985 +      <para id="x_2f">If you want to see both the description and
   1.986 +	content of a change, add the <option
   1.987 +	  role="hg-opt-log">-p</option> (or <option
   1.988 +	  role="hg-opt-log">--patch</option>) option.  This displays
   1.989 +	the content of a change as a <emphasis>unified diff</emphasis>
   1.990 +	(if you've never seen a unified diff before, see <xref
   1.991 +	  linkend="sec:mq:patch"/> for an overview).</para>
   1.992 +
   1.993 +      &interaction.tour.log-vp;
   1.994 +
   1.995 +      <para id="x_67e">The <option role="hg-opt-log">-p</option> option is
   1.996 +	tremendously useful, so it's well worth remembering.</para>
   1.997 +
   1.998 +    </sect2>
   1.999 +  </sect1>
  1.1000 +
  1.1001 +  <sect1>
  1.1002 +    <title>All about command options</title>
  1.1003 +
  1.1004 +    <para id="x_30">Let's take a brief break from exploring Mercurial commands
  1.1005 +      to discuss a pattern in the way that they work; you may find
  1.1006 +      this useful to keep in mind as we continue our tour.</para>
  1.1007 +
  1.1008 +    <para id="x_31">Mercurial has a consistent and straightforward approach to
  1.1009 +      dealing with the options that you can pass to commands.  It
  1.1010 +      follows the conventions for options that are common to modern
  1.1011 +      Linux and Unix systems.</para>
  1.1012 +
  1.1013 +    <itemizedlist>
  1.1014 +      <listitem>
  1.1015 +	<para id="x_32">Every option has a long name.  For example, as
  1.1016 +	  we've already seen, the <command role="hg-cmd">hg
  1.1017 +	    log</command> command accepts a <option
  1.1018 +	    role="hg-opt-log">--rev</option> option.</para>
  1.1019 +      </listitem>
  1.1020 +      <listitem>
  1.1021 +	<para id="x_33">Most options have short names, too.  Instead
  1.1022 +	  of <option role="hg-opt-log">--rev</option>, we can use
  1.1023 +	  <option role="hg-opt-log">-r</option>.  (The reason that
  1.1024 +	  some options don't have short names is that the options in
  1.1025 +	  question are rarely used.)</para>
  1.1026 +      </listitem>
  1.1027 +      <listitem>
  1.1028 +	<para id="x_34">Long options start with two dashes (e.g.
  1.1029 +	  <option role="hg-opt-log">--rev</option>), while short
  1.1030 +	  options start with one (e.g. <option
  1.1031 +	    role="hg-opt-log">-r</option>).</para>
  1.1032 +      </listitem>
  1.1033 +      <listitem>
  1.1034 +	<para id="x_35">Option naming and usage is consistent across
  1.1035 +	  commands.  For example, every command that lets you specify
  1.1036 +	  a changeset ID or revision number accepts both <option
  1.1037 +	    role="hg-opt-log">-r</option> and <option
  1.1038 +	    role="hg-opt-log">--rev</option> arguments.</para>
  1.1039 +      </listitem>
  1.1040 +      <listitem>
  1.1041 +	<para id="x_67f">If you are using short options, you can save typing by
  1.1042 +	  running them together. For example, the command <command
  1.1043 +	    role="hg-cmd">hg log -v -p -r 2</command> can be written
  1.1044 +	  as <command role="hg-cmd">hg log -vpr2</command>.</para>
  1.1045 +      </listitem>
  1.1046 +    </itemizedlist>
  1.1047 +
  1.1048 +    <para id="x_36">In the examples throughout this book, I usually
  1.1049 +      use short options instead of long.  This simply reflects my own
  1.1050 +      preference, so don't read anything significant into it.</para>
  1.1051 +
  1.1052 +    <para id="x_37">Most commands that print output of some kind will print more
  1.1053 +      output when passed a <option role="hg-opt-global">-v</option>
  1.1054 +      (or <option role="hg-opt-global">--verbose</option>) option, and
  1.1055 +      less when passed <option role="hg-opt-global">-q</option> (or
  1.1056 +      <option role="hg-opt-global">--quiet</option>).</para>
  1.1057 +
  1.1058 +    <note>
  1.1059 +      <title>Option naming consistency</title>
  1.1060 +
  1.1061 +      <para id="x_680">Almost always, Mercurial commands use consistent option
  1.1062 +	names to refer to the same concepts.  For instance, if a
  1.1063 +	command deals with changesets, you'll always identify them
  1.1064 +	with <option role="hg-opt-log">--rev</option> or <option
  1.1065 +	  role="hg-opt-log">-r</option>.  This consistent use of
  1.1066 +	option names makes it easier to remember what options a
  1.1067 +	particular command takes.</para>
  1.1068 +    </note>
  1.1069 +
  1.1070 +  </sect1>
  1.1071 +  <sect1>
  1.1072 +    <title>Making and reviewing changes</title>
  1.1073 +
  1.1074 +    <para id="x_38">Now that we have a grasp of viewing history in Mercurial,
  1.1075 +      let's take a look at making some changes and examining
  1.1076 +      them.</para>
  1.1077 +
  1.1078 +    <para id="x_39">The first thing we'll do is isolate our experiment in a
  1.1079 +      repository of its own.  We use the <command role="hg-cmd">hg
  1.1080 +	clone</command> command, but we don't need to clone a copy of
  1.1081 +      the remote repository.  Since we already have a copy of it
  1.1082 +      locally, we can just clone that instead.  This is much faster
  1.1083 +      than cloning over the network, and cloning a local repository
  1.1084 +      uses less disk space in most cases, too<footnote>
  1.1085 +	<para id="x_681">The saving of space arises when source and destination
  1.1086 +	  repositories are on the same filesystem, in which case
  1.1087 +	  Mercurial will use hardlinks to do copy-on-write sharing of
  1.1088 +	  its internal metadata.  If that explanation meant nothing to
  1.1089 +	  you, don't worry: everything happens transparently and
  1.1090 +	  automatically, and you don't need to understand it.</para>
  1.1091 +	</footnote>.</para>
  1.1092 +
  1.1093 +    &interaction.tour.reclone;
  1.1094 +
  1.1095 +    <para id="x_3a">As an aside, it's often good practice to keep a
  1.1096 +      <quote>pristine</quote> copy of a remote repository around,
  1.1097 +      which you can then make temporary clones of to create sandboxes
  1.1098 +      for each task you want to work on.  This lets you work on
  1.1099 +      multiple tasks in parallel, each isolated from the others until
  1.1100 +      it's complete and you're ready to integrate it back.  Because
  1.1101 +      local clones are so cheap, there's almost no overhead to cloning
  1.1102 +      and destroying repositories whenever you want.</para>
  1.1103 +
  1.1104 +    <para id="x_3b">In our <filename class="directory">my-hello</filename>
  1.1105 +      repository, we have a file <filename>hello.c</filename> that
  1.1106 +      contains the classic <quote>hello, world</quote> program.</para>
  1.1107 +
  1.1108 +    &interaction.tour.cat1;
  1.1109 +
  1.1110 +    <para id="x_682">Let's edit this file so that it prints a second line of
  1.1111 +      output.</para>
  1.1112 +
  1.1113 +    &interaction.tour.cat2;
  1.1114 +
  1.1115 +    <para id="x_3c">Mercurial's <command role="hg-cmd">hg status</command>
  1.1116 +      command will tell us what Mercurial knows about the files in the
  1.1117 +      repository.</para>
  1.1118 +
  1.1119 +    &interaction.tour.status;
  1.1120 +
  1.1121 +    <para id="x_3d">The <command role="hg-cmd">hg status</command> command
  1.1122 +      prints no output for some files, but a line starting with
  1.1123 +      <quote><literal>M</literal></quote> for
  1.1124 +      <filename>hello.c</filename>.  Unless you tell it to, <command
  1.1125 +	role="hg-cmd">hg status</command> will not print any output
  1.1126 +      for files that have not been modified.</para>
  1.1127 +
  1.1128 +    <para id="x_3e">The <quote><literal>M</literal></quote> indicates that
  1.1129 +      Mercurial has noticed that we modified
  1.1130 +      <filename>hello.c</filename>.  We didn't need to
  1.1131 +      <emphasis>inform</emphasis> Mercurial that we were going to
  1.1132 +      modify the file before we started, or that we had modified the
  1.1133 +      file after we were done; it was able to figure this out
  1.1134 +      itself.</para>
  1.1135 +
  1.1136 +    <para id="x_3f">It's somewhat helpful to know that we've modified
  1.1137 +      <filename>hello.c</filename>, but we might prefer to know
  1.1138 +      exactly <emphasis>what</emphasis> changes we've made to it.  To
  1.1139 +      do this, we use the <command role="hg-cmd">hg diff</command>
  1.1140 +      command.</para>
  1.1141 +
  1.1142 +    &interaction.tour.diff;
  1.1143 +
  1.1144 +    <tip>
  1.1145 +      <title>Understanding patches</title>
  1.1146 +
  1.1147 +      <para id="x_683">Remember to take a look at <xref
  1.1148 +	  linkend="sec:mq:patch"/> if you don't know how to read
  1.1149 +	output above.</para>
  1.1150 +    </tip>
  1.1151 +  </sect1>
  1.1152 +  <sect1>
  1.1153 +    <title>Recording changes in a new changeset</title>
  1.1154 +
  1.1155 +    <para id="x_40">We can modify files, build and test our changes, and use
  1.1156 +      <command role="hg-cmd">hg status</command> and <command
  1.1157 +	role="hg-cmd">hg diff</command> to review our changes, until
  1.1158 +      we're satisfied with what we've done and arrive at a natural
  1.1159 +      stopping point where we want to record our work in a new
  1.1160 +      changeset.</para>
  1.1161 +
  1.1162 +    <para id="x_41">The <command role="hg-cmd">hg commit</command> command lets
  1.1163 +      us create a new changeset; we'll usually refer to this as
  1.1164 +      <quote>making a commit</quote> or
  1.1165 +      <quote>committing</quote>.</para>
  1.1166 +
  1.1167 +    <sect2>
  1.1168 +      <title>Setting up a username</title>
  1.1169 +
  1.1170 +      <para id="x_42">When you try to run <command role="hg-cmd">hg
  1.1171 +	  commit</command> for the first time, it is not guaranteed to
  1.1172 +	succeed.  Mercurial records your name and address with each
  1.1173 +	change that you commit, so that you and others will later be
  1.1174 +	able to tell who made each change.  Mercurial tries to
  1.1175 +	automatically figure out a sensible username to commit the
  1.1176 +	change with.  It will attempt each of the following methods,
  1.1177 +	in order:</para>
  1.1178 +      <orderedlist>
  1.1179 +	<listitem><para id="x_43">If you specify a <option
  1.1180 +	      role="hg-opt-commit">-u</option> option to the <command
  1.1181 +	      role="hg-cmd">hg commit</command> command on the command
  1.1182 +	    line, followed by a username, this is always given the
  1.1183 +	    highest precedence.</para></listitem>
  1.1184 +	<listitem><para id="x_44">If you have set the <envar>HGUSER</envar>
  1.1185 +	    environment variable, this is checked
  1.1186 +	    next.</para></listitem>
  1.1187 +	<listitem><para id="x_45">If you create a file in your home
  1.1188 +	    directory called <filename
  1.1189 +	      role="special">.hgrc</filename>, with a <envar
  1.1190 +	      role="rc-item-ui">username</envar> entry, that will be
  1.1191 +	    used next.  To see what the contents of this file should
  1.1192 +	    look like, refer to <xref
  1.1193 +	      linkend="sec:tour-basic:username"/>
  1.1194 +	    below.</para></listitem>
  1.1195 +	<listitem><para id="x_46">If you have set the <envar>EMAIL</envar>
  1.1196 +	    environment variable, this will be used
  1.1197 +	    next.</para></listitem>
  1.1198 +	<listitem><para id="x_47">Mercurial will query your system to find out
  1.1199 +	    your local user name and host name, and construct a
  1.1200 +	    username from these components. Since this often results
  1.1201 +	    in a username that is not very useful, it will print a
  1.1202 +	    warning if it has to do
  1.1203 +	    this.</para></listitem>
  1.1204 +      </orderedlist>
  1.1205 +      <para id="x_48">If all of these mechanisms fail, Mercurial will
  1.1206 +	  fail, printing an error message.  In this case, it will not
  1.1207 +	  let you commit until you set up a
  1.1208 +	  username.</para>
  1.1209 +      <para id="x_49">You should think of the <envar>HGUSER</envar> environment
  1.1210 +	variable and the <option role="hg-opt-commit">-u</option>
  1.1211 +	option to the <command role="hg-cmd">hg commit</command>
  1.1212 +	command as ways to <emphasis>override</emphasis> Mercurial's
  1.1213 +	default selection of username.  For normal use, the simplest
  1.1214 +	and most robust way to set a username for yourself is by
  1.1215 +	creating a <filename role="special">.hgrc</filename> file; see
  1.1216 +	below for details.</para>
  1.1217 +      <sect3 id="sec:tour-basic:username">
  1.1218 +	<title>Creating a Mercurial configuration file</title>
  1.1219 +
  1.1220 +	<para id="x_4a">To set a user name, use your favorite editor
  1.1221 +	  to create a file called <filename
  1.1222 +	    role="special">.hgrc</filename> in your home directory.
  1.1223 +	  Mercurial will use this file to look up your personalised
  1.1224 +	  configuration settings.  The initial contents of your
  1.1225 +	  <filename role="special">.hgrc</filename> should look like
  1.1226 +	  this.</para>
  1.1227 +
  1.1228 +	<tip>
  1.1229 +	  <title><quote>Home directory</quote> on Windows</title>
  1.1230 +
  1.1231 +	  <para id="x_716">When we refer to your home directory, on an English
  1.1232 +	    language installation of Windows this will usually be a
  1.1233 +	    folder named after your user name in
  1.1234 +	    <filename>C:\Documents and Settings</filename>.  You can
  1.1235 +	    find out the exact name of your home directory by opening
  1.1236 +	    a command prompt window and running the following
  1.1237 +	    command.</para>
  1.1238 +
  1.1239 +	  <screen><prompt>C:\></prompt> <userinput>echo %UserProfile%</userinput></screen>
  1.1240 +	</tip>
  1.1241 +
  1.1242 +	<programlisting># This is a Mercurial configuration file.
  1.1243 +[ui]
  1.1244 +username = Firstname Lastname &lt;email.address@example.net&gt;</programlisting>
  1.1245 +
  1.1246 +	<para id="x_4b">The <quote><literal>[ui]</literal></quote> line begins a
  1.1247 +	  <emphasis>section</emphasis> of the config file, so you can
  1.1248 +	  read the <quote><literal>username = ...</literal></quote>
  1.1249 +	  line as meaning <quote>set the value of the
  1.1250 +	    <literal>username</literal> item in the
  1.1251 +	    <literal>ui</literal> section</quote>. A section continues
  1.1252 +	  until a new section begins, or the end of the file.
  1.1253 +	  Mercurial ignores empty lines and treats any text from
  1.1254 +	  <quote><literal>#</literal></quote> to the end of a line as
  1.1255 +	  a comment.</para>
  1.1256 +      </sect3>
  1.1257 +
  1.1258 +      <sect3>
  1.1259 +	<title>Choosing a user name</title>
  1.1260 +
  1.1261 +	<para id="x_4c">You can use any text you like as the value of
  1.1262 +	  the <literal>username</literal> config item, since this
  1.1263 +	  information is for reading by other people, but will not be
  1.1264 +	  interpreted by Mercurial.  The convention that most people
  1.1265 +	  follow is to use their name and email address, as in the
  1.1266 +	  example above.</para>
  1.1267 +	<note>
  1.1268 +	  <para id="x_4d">Mercurial's built-in web server obfuscates
  1.1269 +	    email addresses, to make it more difficult for the email
  1.1270 +	    harvesting tools that spammers use. This reduces the
  1.1271 +	    likelihood that you'll start receiving more junk email if
  1.1272 +	    you publish a Mercurial repository on the
  1.1273 +	    web.</para></note>
  1.1274 +      </sect3>
  1.1275 +    </sect2>
  1.1276 +    <sect2>
  1.1277 +      <title>Writing a commit message</title>
  1.1278 +
  1.1279 +      <para id="x_4e">When we commit a change, Mercurial drops us into
  1.1280 +	a text editor, to enter a message that will describe the
  1.1281 +	modifications we've made in this changeset.  This is called
  1.1282 +	the <emphasis>commit message</emphasis>.  It will be a record
  1.1283 +	for readers of what we did and why, and it will be printed by
  1.1284 +	<command role="hg-cmd">hg log</command> after we've finished
  1.1285 +	committing.</para>
  1.1286 +
  1.1287 +       &interaction.tour.commit;
  1.1288 +
  1.1289 +      <para id="x_4f">The editor that the <command role="hg-cmd">hg
  1.1290 +	  commit</command> command drops us into will contain an empty
  1.1291 +	line or two, followed by a number of lines starting with
  1.1292 +	<quote><literal>HG:</literal></quote>.</para>
  1.1293 +
  1.1294 +    <programlisting>
  1.1295 +This is where I type my commit comment.
  1.1296 +
  1.1297 +HG: Enter commit message.  Lines beginning with 'HG:' are removed.
  1.1298 +HG: --
  1.1299 +HG: user: Bryan O'Sullivan &lt;bos@serpentine.com&gt;
  1.1300 +HG: branch 'default'
  1.1301 +HG: changed hello.c</programlisting>
  1.1302 +
  1.1303 +      <para id="x_50">Mercurial ignores the lines that start with
  1.1304 +	<quote><literal>HG:</literal></quote>; it uses them only to
  1.1305 +	tell us which files it's recording changes to.  Modifying or
  1.1306 +	deleting these lines has no effect.</para>
  1.1307 +    </sect2>
  1.1308 +    <sect2>
  1.1309 +      <title>Writing a good commit message</title>
  1.1310 +
  1.1311 +      <para id="x_51">Since <command role="hg-cmd">hg log</command>
  1.1312 +	only prints the first line of a commit message by default,
  1.1313 +	it's best to write a commit message whose first line stands
  1.1314 +	alone.  Here's a real example of a commit message that
  1.1315 +	<emphasis>doesn't</emphasis> follow this guideline, and hence
  1.1316 +	has a summary that is not readable.</para>
  1.1317 +
  1.1318 +      <programlisting>
  1.1319 +changeset:   73:584af0e231be
  1.1320 +user:        Censored Person &lt;censored.person@example.org&gt;
  1.1321 +date:        Tue Sep 26 21:37:07 2006 -0700
  1.1322 +summary:     include buildmeister/commondefs. Add exports.</programlisting>
  1.1323 +
  1.1324 +      <para id="x_52">As far as the remainder of the contents of the
  1.1325 +	commit message are concerned, there are no hard-and-fast
  1.1326 +	rules.  Mercurial itself doesn't interpret or care about the
  1.1327 +	contents of the commit message, though your project may have
  1.1328 +	policies that dictate a certain kind of formatting.</para>
  1.1329 +      <para id="x_53">My personal preference is for short, but
  1.1330 +	informative, commit messages that tell me something that I
  1.1331 +	can't figure out with a quick glance at the output of <command
  1.1332 +	  role="hg-cmd">hg log --patch</command>.</para>
  1.1333 +      <para id="x_55">If we run the <command role="hg-cmd">hg
  1.1334 +	  commit</command> command without any arguments, it records
  1.1335 +	all of the changes we've made, as reported by <command
  1.1336 +	  role="hg-cmd">hg status</command> and <command
  1.1337 +	  role="hg-cmd">hg diff</command>.</para>
  1.1338 +
  1.1339 +      <note>
  1.1340 +	<title>A surprise for Subversion users</title>
  1.1341 +
  1.1342 +	<para id="x_717">Like other Mercurial commands, if we don't supply
  1.1343 +	  explicit names to commit to the <command role="hg-cmd">hg
  1.1344 +	    commit</command>, it will operate across a repository's
  1.1345 +	  entire working directory.  Be wary of this if you're coming
  1.1346 +	  from the Subversion or CVS world, since you might expect it
  1.1347 +	  to operate only on the current directory that you happen to
  1.1348 +	  be visiting and its subdirectories.</para>
  1.1349 +      </note>
  1.1350 +    </sect2>
  1.1351 +
  1.1352 +    <sect2>
  1.1353 +      <title>Aborting a commit</title>
  1.1354 +
  1.1355 +      <para id="x_54">If you decide that you don't want to commit
  1.1356 +	while in the middle of editing a commit message, simply exit
  1.1357 +	from your editor without saving the file that it's editing.
  1.1358 +	This will cause nothing to happen to either the repository or
  1.1359 +	the working directory.</para>
  1.1360 +    </sect2>
  1.1361 +
  1.1362 +    <sect2>
  1.1363 +      <title>Admiring our new handiwork</title>
  1.1364 +
  1.1365 +      <para id="x_56">Once we've finished the commit, we can use the
  1.1366 +	<command role="hg-cmd">hg tip</command> command to display the
  1.1367 +	changeset we just created.  This command produces output that
  1.1368 +	is identical to <command role="hg-cmd">hg log</command>, but
  1.1369 +	it only displays the newest revision in the repository.</para>
  1.1370 +
  1.1371 +      &interaction.tour.tip;
  1.1372 +
  1.1373 +      <para id="x_57">We refer to the newest revision in the
  1.1374 +	repository as the <emphasis>tip revision</emphasis>, or simply
  1.1375 +	the <emphasis>tip</emphasis>.</para>
  1.1376 +
  1.1377 +      <para id="x_684">By the way, the <command role="hg-cmd">hg tip</command>
  1.1378 +	command accepts many of the same options as <command
  1.1379 +	  role="hg-cmd">hg log</command>, so <option
  1.1380 +	  role="hg-opt-global">-v</option> above indicates <quote>be
  1.1381 +	  verbose</quote>, <option role="hg-opt-tip">-p</option>
  1.1382 +	specifies <quote>print a patch</quote>.  The use of <option
  1.1383 +	  role="hg-opt-tip">-p</option> to print patches is another
  1.1384 +	example of the consistent naming we mentioned earlier.</para>
  1.1385 +    </sect2>
  1.1386 +  </sect1>
  1.1387 +
  1.1388 +  <sect1>
  1.1389 +    <title>Sharing changes</title>
  1.1390 +
  1.1391 +    <para id="x_58">We mentioned earlier that repositories in
  1.1392 +      Mercurial are self-contained.  This means that the changeset we
  1.1393 +      just created exists only in our <filename
  1.1394 +	class="directory">my-hello</filename> repository.  Let's look
  1.1395 +      at a few ways that we can propagate this change into other
  1.1396 +      repositories.</para>
  1.1397 +
  1.1398 +    <sect2 id="sec:tour:pull">
  1.1399 +      <title>Pulling changes from another repository</title>
  1.1400 +
  1.1401 +      <para id="x_59">To get started, let's clone our original
  1.1402 +	<filename class="directory">hello</filename> repository, which
  1.1403 +	does not contain the change we just committed.  We'll call our
  1.1404 +	temporary repository <filename
  1.1405 +	  class="directory">hello-pull</filename>.</para>
  1.1406 +
  1.1407 +      &interaction.tour.clone-pull;
  1.1408 +
  1.1409 +      <para id="x_5a">We'll use the <command role="hg-cmd">hg
  1.1410 +	  pull</command> command to bring changes from <filename
  1.1411 +	  class="directory">my-hello</filename> into <filename
  1.1412 +	  class="directory">hello-pull</filename>.  However, blindly
  1.1413 +	pulling unknown changes into a repository is a somewhat scary
  1.1414 +	prospect.  Mercurial provides the <command role="hg-cmd">hg
  1.1415 +	  incoming</command> command to tell us what changes the
  1.1416 +	<command role="hg-cmd">hg pull</command> command
  1.1417 +	<emphasis>would</emphasis> pull into the repository, without
  1.1418 +	actually pulling the changes in.</para>
  1.1419 +
  1.1420 +      &interaction.tour.incoming;
  1.1421 +
  1.1422 +      <para id="x_5c">Bringing changes into a repository is a simple
  1.1423 +	matter of running the <command role="hg-cmd">hg pull</command>
  1.1424 +	command, and optionally telling it which repository to pull from.</para>
  1.1425 +
  1.1426 +      &interaction.tour.pull;
  1.1427 +
  1.1428 +      <para id="x_5d">As you can see from the before-and-after output
  1.1429 +	of <command role="hg-cmd">hg tip</command>, we have
  1.1430 +	successfully pulled changes into our repository.  However,
  1.1431 +	Mercurial separates pulling changes in from updating the
  1.1432 +	working directory. There remains one step before we will see
  1.1433 +	the changes that we just pulled appear in the working
  1.1434 +	directory.</para>
  1.1435 +
  1.1436 +      <tip>
  1.1437 +	<title>Pulling specific changes</title>
  1.1438 +
  1.1439 +	<para id="x_5b">It is possible that due to the delay between
  1.1440 +	  running <command role="hg-cmd">hg incoming</command> and
  1.1441 +	  <command role="hg-cmd">hg pull</command>, you may not see
  1.1442 +	  all changesets that will be brought from the other
  1.1443 +	  repository. Suppose you're pulling changes from a repository
  1.1444 +	  on the network somewhere. While you are looking at the
  1.1445 +	  <command role="hg-cmd">hg incoming</command> output, and
  1.1446 +	  before you pull those changes, someone might have committed
  1.1447 +	  something in the remote repository. This means that it's
  1.1448 +	  possible to pull more changes than you saw when using
  1.1449 +	  <command role="hg-cmd">hg incoming</command>.</para>
  1.1450 +
  1.1451 +	<para id="x_718">If you only want to pull precisely the changes that were
  1.1452 +	  listed by <command role="hg-cmd">hg incoming</command>, or
  1.1453 +	  you have some other reason to pull a subset of changes,
  1.1454 +	  simply identify the change that you want to pull by its
  1.1455 +	  changeset ID, e.g. <command>hg pull
  1.1456 +	    -r7e95bb</command>.</para>
  1.1457 +      </tip>
  1.1458 +    </sect2>
  1.1459 +
  1.1460 +    <sect2>
  1.1461 +      <title>Updating the working directory</title>
  1.1462 +
  1.1463 +      <para id="x_5e">We have so far glossed over the relationship
  1.1464 +	between a repository and its working directory.  The <command
  1.1465 +	  role="hg-cmd">hg pull</command> command that we ran in
  1.1466 +	<xref linkend="sec:tour:pull"/> brought changes into the
  1.1467 +	repository, but if we check, there's no sign of those changes
  1.1468 +	in the working directory.  This is because <command
  1.1469 +	  role="hg-cmd">hg pull</command> does not (by default) touch
  1.1470 +	the working directory.  Instead, we use the <command
  1.1471 +	  role="hg-cmd">hg update</command> command to do this.</para>
  1.1472 +
  1.1473 +      &interaction.tour.update;
  1.1474 +
  1.1475 +      <para id="x_5f">It might seem a bit strange that <command
  1.1476 +	  role="hg-cmd">hg pull</command> doesn't update the working
  1.1477 +	directory automatically.  There's actually a good reason for
  1.1478 +	this: you can use <command role="hg-cmd">hg update</command>
  1.1479 +	to update the working directory to the state it was in at
  1.1480 +	<emphasis>any revision</emphasis> in the history of the
  1.1481 +	repository.  If you had the working directory updated to an
  1.1482 +	old revision&emdash;to hunt down the origin of a bug,
  1.1483 +	say&emdash;and ran a <command role="hg-cmd">hg pull</command>
  1.1484 +	which automatically updated the working directory to a new
  1.1485 +	revision, you might not be terribly happy.</para>
  1.1486 +
  1.1487 +      <para id="x_60">Since pull-then-update is such a common sequence
  1.1488 +	of operations, Mercurial lets you combine the two by passing
  1.1489 +	the <option role="hg-opt-pull">-u</option> option to <command
  1.1490 +	  role="hg-cmd">hg pull</command>.</para>
  1.1491 +
  1.1492 +      <para id="x_61">If you look back at the output of <command
  1.1493 +	  role="hg-cmd">hg pull</command> in <xref
  1.1494 +	    linkend="sec:tour:pull"/> when we ran it without <option
  1.1495 +	  role="hg-opt-pull">-u</option>, you can see that it printed
  1.1496 +	a helpful reminder that we'd have to take an explicit step to
  1.1497 +	update the working directory.</para>
  1.1498 +
  1.1499 +      <para id="x_62">To find out what revision the working directory
  1.1500 +	is at, use the <command role="hg-cmd">hg parents</command>
  1.1501 +	command.</para>
  1.1502 +
  1.1503 +      &interaction.tour.parents;
  1.1504 +
  1.1505 +      <para id="x_63">If you look back at <xref
  1.1506 +	  linkend="fig:tour-basic:history"/>, you'll see arrows
  1.1507 +	connecting each changeset.  The node that the arrow leads
  1.1508 +	<emphasis>from</emphasis> in each case is a parent, and the
  1.1509 +	node that the arrow leads <emphasis>to</emphasis> is its
  1.1510 +	child.  The working directory has a parent in just the same
  1.1511 +	way; this is the changeset that the working directory
  1.1512 +	currently contains.</para>
  1.1513 +
  1.1514 +      <para id="x_64">To update the working directory to a particular
  1.1515 +	revision, give a revision number or changeset ID to the
  1.1516 +	<command role="hg-cmd">hg update</command> command.</para>
  1.1517 +
  1.1518 +      &interaction.tour.older;
  1.1519 +
  1.1520 +      <para id="x_65">If you omit an explicit revision, <command
  1.1521 +	  role="hg-cmd">hg update</command> will update to the tip
  1.1522 +	revision, as shown by the second call to <command
  1.1523 +	  role="hg-cmd">hg update</command> in the example
  1.1524 +	above.</para>
  1.1525 +    </sect2>
  1.1526 +
  1.1527 +    <sect2>
  1.1528 +      <title>Pushing changes to another repository</title>
  1.1529 +
  1.1530 +      <para id="x_66">Mercurial lets us push changes to another
  1.1531 +	repository, from the repository we're currently visiting. As
  1.1532 +	with the example of <command role="hg-cmd">hg pull</command>
  1.1533 +	above, we'll create a temporary repository to push our changes
  1.1534 +	into.</para>
  1.1535 +
  1.1536 +      &interaction.tour.clone-push;
  1.1537 +
  1.1538 +      <para id="x_67">The <command role="hg-cmd">hg outgoing</command>
  1.1539 +	command tells us what changes would be pushed into another
  1.1540 +	repository.</para>
  1.1541 +
  1.1542 +      &interaction.tour.outgoing;
  1.1543 +
  1.1544 +      <para id="x_68">And the <command role="hg-cmd">hg push</command>
  1.1545 +	command does the actual push.</para>
  1.1546 +
  1.1547 +      &interaction.tour.push;
  1.1548 +
  1.1549 +      <para id="x_69">As with <command role="hg-cmd">hg
  1.1550 +	  pull</command>, the <command role="hg-cmd">hg push</command>
  1.1551 +	command does not update the working directory in the
  1.1552 +	repository that it's pushing changes into. Unlike <command
  1.1553 +	  role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg
  1.1554 +	  push</command> does not provide a <literal>-u</literal>
  1.1555 +	option that updates the other repository's working directory.
  1.1556 +	This asymmetry is deliberate: the repository we're pushing to
  1.1557 +	might be on a remote server and shared between several people.
  1.1558 +	If we were to update its working directory while someone was
  1.1559 +	working in it, their work would be disrupted.</para>
  1.1560 +
  1.1561 +      <para id="x_6a">What happens if we try to pull or push changes
  1.1562 +	  and the receiving repository already has those changes?
  1.1563 +	  Nothing too exciting.</para>
  1.1564 +
  1.1565 +      &interaction.tour.push.nothing;
  1.1566 +    </sect2>
  1.1567 +
  1.1568 +    <sect2>
  1.1569 +      <title>Default locations</title>
  1.1570 +
  1.1571 +      <para id="x_719">When we clone a repository, Mercurial records the location
  1.1572 +	of the repository we cloned in the
  1.1573 +	<filename>.hg/hgrc</filename> file of the new repository.  If
  1.1574 +	we don't supply a location to <command>hg pull</command> from
  1.1575 +	or <command>hg push</command> to, those commands will use this
  1.1576 +	location as a default.  The <command>hg incoming</command>
  1.1577 +	and <command>hg outgoing</command> commands do so too.</para>
  1.1578 +
  1.1579 +      <para id="x_71a">If you open a repository's <filename>.hg/hgrc</filename>
  1.1580 +	file in a text editor, you will see contents like the
  1.1581 +	following.</para>
  1.1582 +
  1.1583 +      <programlisting>[paths]
  1.1584 +default = http://www.selenic.com/repo/hg</programlisting>
  1.1585 +
  1.1586 +      <para id="x_71b">It is possible&emdash;and often useful&emdash;to have the
  1.1587 +	default location for <command>hg push</command> and
  1.1588 +	<command>hg outgoing</command> be different from those for
  1.1589 +	<command>hg pull</command> and <command>hg incoming</command>.
  1.1590 +	We can do this by adding a <literal>default-push</literal>
  1.1591 +	entry to the <literal>[paths]</literal> section of the
  1.1592 +	<filename>.hg/hgrc</filename> file, as follows.</para>
  1.1593 +
  1.1594 +      <programlisting>[paths]
  1.1595 +default = http://www.selenic.com/repo/hg
  1.1596 +default-push = http://hg.example.com/hg</programlisting>
  1.1597 +    </sect2>
  1.1598 +
  1.1599 +    <sect2>
  1.1600 +      <title>Sharing changes over a network</title>
  1.1601 +
  1.1602 +      <para id="x_6b">The commands we have covered in the previous few
  1.1603 +	  sections are not limited to working with local repositories.
  1.1604 +	  Each works in exactly the same fashion over a network
  1.1605 +	  connection; simply pass in a URL instead of a local
  1.1606 +	  path.</para>
  1.1607 +	
  1.1608 +      &interaction.tour.outgoing.net;
  1.1609 +
  1.1610 +      <para id="x_6c">In this example, we can see what changes we
  1.1611 +	could push to the remote repository, but the repository is
  1.1612 +	understandably not set up to let anonymous users push to
  1.1613 +	it.</para>
  1.1614 +
  1.1615 +      &interaction.tour.push.net;
  1.1616 +    </sect2>
  1.1617 +  </sect1>
  1.1618 +
  1.1619 +  <sect1>
  1.1620 +    <title>Starting a new project</title>
  1.1621 +
  1.1622 +    <para id="x_71c">It is just as easy to begin a new project as to work on one
  1.1623 +      that already exists.  The <command>hg init</command> command
  1.1624 +      creates a new, empty Mercurial repository.</para>
  1.1625 +
  1.1626 +    &interaction.ch01-new.init;
  1.1627 +
  1.1628 +    <para id="x_71d">This simply creates a repository named
  1.1629 +      <filename>myproject</filename> in the current directory.</para>
  1.1630 +
  1.1631 +    &interaction.ch01-new.ls;
  1.1632 +
  1.1633 +    <para id="x_71e">We can tell that <filename>myproject</filename> is a
  1.1634 +      Mercurial repository, because it contains a
  1.1635 +      <filename>.hg</filename> directory.</para>
  1.1636 +
  1.1637 +    &interaction.ch01-new.ls2;
  1.1638 +
  1.1639 +    <para id="x_71f">If we want to add some pre-existing files to the repository,
  1.1640 +      we copy them into place, and tell Mercurial to start tracking
  1.1641 +      them using the <command>hg add</command> command.</para>
  1.1642 +
  1.1643 +    &interaction.ch01-new.add;
  1.1644 +
  1.1645 +    <para id="x_720">Once we are satisfied that our project looks right, we
  1.1646 +      commit our changes.</para>
  1.1647 +
  1.1648 +    &interaction.ch01-new.commit;
  1.1649 +
  1.1650 +    <para id="x_721">It takes just a few moments to start using Mercurial on a
  1.1651 +      new project, which is part of its appeal. Revision control is
  1.1652 +      now so easy to work with, we can use it on the smallest of
  1.1653 +      projects that we might not have considered with a more
  1.1654 +      complicated tool.</para>
  1.1655 +  </sect1>
  1.1656 +</chapter>
  1.1657 +
  1.1658 +<!--
  1.1659 +local variables: 
  1.1660 +sgml-parent-document: ("00book.xml" "book" "chapter")
  1.1661 +end:
  1.1662 +-->