1.1 --- a/es/tour-basic.tex	Sat Oct 18 07:48:21 2008 -0500
     1.2 +++ b/es/tour-basic.tex	Sun Oct 19 23:53:39 2008 -0500
     1.3 @@ -0,0 +1,631 @@
     1.4 +\chapter{Una gira de Mercurial: lo básico}
     1.5 +\label{chap:tour-basic}
     1.6 +
     1.7 +\section{Instalar Mercurial en su sistema}
     1.8 +\label{sec:tour:install}
     1.9 +Hay paquetes binarios precompilados de Mercurial disponibles para cada
    1.10 +sistema operativo popular. Esto hace fácil empezar a usar Mercurial
    1.11 +en su computador inmediatamente.
    1.12 +
    1.13 +\subsection{Linux}
    1.14 +
    1.15 +Dado que cada distribución de Linux tiene sus propias herramientas de
    1.16 +manejo de paquetes, políticas, y ritmos de desarrollo, es difícil dar
    1.17 +un conjunto exhaustivo de instrucciones sobre cómo instalar el paquete
    1.18 +de Mercurial. La versión de Mercurial que usted tenga a disposición
    1.19 +puede variar dependiendo de qué tan activa sea la persona que mantiene
    1.20 +el paquete para su distribución.
    1.21 +
    1.22 +Para mantener las cosas simples, me enfocaré en instalar Mercurial
    1.23 +desde la línea de comandos en las distribuciones de Linux más
    1.24 +populares. La mayoría de estas distribuciones proveen administradores
    1.25 +de paquetes gráficos que le permitirán instalar Mercurial con un solo
    1.26 +clic; el nombre de paquete a buscar es \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] El paquete de Mercurial de Ubuntu está basado en el de
    1.50 +    Debian. Para instalarlo, ejecute el siguiente comando.
    1.51 +  \begin{codesample4}
    1.52 +    apt-get install mercurial
    1.53 +  \end{codesample4}
    1.54 +  El paquete de Mercurial para Ubuntu tiende a atrasarse con respecto
    1.55 +  a la versión de Debian por un margen de tiempo considerable
    1.56 +  (al momento de escribir esto, 7 meses), lo que en algunos casos
    1.57 +  significará que usted puede encontrarse con problemas que ya habrán
    1.58 +  sido resueltos en el paquete de Debian.
    1.59 +\end{itemize}
    1.60 +
    1.61 +\subsection{Solaris}
    1.62 +
    1.63 +SunFreeWare, en \url{http://www.sunfreeware.com}, es una buena fuente
    1.64 +para un gran número de paquetes compilados para Solaris para las
    1.65 +arquitecturas Intel y Sparc de 32 y 64 bits, incluyendo versiones
    1.66 +actuales de Mercurial.
    1.67 +
    1.68 +\subsection{Mac OS X}
    1.69 +
    1.70 +Lee Cantey publica un instalador de Mercurial para Mac OS~X en 
    1.71 +\url{http://mercurial.berkwood.com}.  Este paquete funciona en tanto
    1.72 +en Macs basados en Intel como basados en PowerPC. Antes de que pueda
    1.73 +usarlo, usted debe instalar una versión compatible de Universal
    1.74 +MacPython~\cite{web:macpython}. Esto es fácil de hacer; simplemente
    1.75 +siga las instrucciones de el sitio de Lee.
    1.76 +
    1.77 +También es posible instalar Mercurial usando Fink o MacPorts, dos
    1.78 +administradores de paquetes gratuitos y populares para Mac OS X. Si
    1.79 +usted tiene Fink, use \command{sudo apt-get install mercurial-py25}.
    1.80 +Si usa MacPorts, \command{sudo port install mercurial}.
    1.81 +
    1.82 +\subsection{Windows}
    1.83 +
    1.84 +Lee Cantey publica un instalador de Mercurial para Windows en
    1.85 +\url{http://mercurial.berkwood.com}. Este paquete no tiene
    1.86 +% TODO traducción de it just works. Agreed?
    1.87 +dependencias externas; ``simplemente funciona''.
    1.88 +
    1.89 +\begin{note}
    1.90 +    La versión de Windows de Mercurial no convierte automáticamente
    1.91 +    los fines de línea entre estilos Windows y Unix. Si usted desea
    1.92 +    compartir trabajo con usuarios de Unix, deberá hacer un trabajo
    1.93 +    adicional de configuración. XXX Terminar esto.
    1.94 +\end{note}
    1.95 +
    1.96 +\section{Arrancando}
    1.97 +
    1.98 +Para empezar, usaremos el comando \hgcmd{version} para revisar si
    1.99 +Mercurial está instalado adecuadamente. La información de la versión
   1.100 +que es impresa no es tan importante; lo que nos importa es si imprime
   1.101 +algo en absoluto.
   1.102 +
   1.103 +\interaction{tour.version}
   1.104 +
   1.105 +% TODO builtin-> integrado?
   1.106 +\subsection{Ayuda integrada}
   1.107 +
   1.108 +Mercurial provee un sistema de ayuda integrada. Esto es invaluable
   1.109 +para ésas ocasiones en la que usted está atorado tratando de recordar
   1.110 +cómo ejecutar un comando. Si está completamente atorado, simplemente
   1.111 +ejecute \hgcmd{help}; esto imprimirá una breve lista de comandos,
   1.112 +junto con una descripción de qué hace cada uno. Si usted solicita
   1.113 +ayuda sobre un comando específico (como abajo), se imprime información
   1.114 +más detallada.
   1.115 +\interaction{tour.help}
   1.116 +Para un nivel más impresionante de detalle (que usted no va a
   1.117 +necesitar usualmente) ejecute \hgcmdargs{help}{\hggopt{-v}}. La opción
   1.118 +\hggopt{-v} es la abreviación para \hggopt{--verbose}, y le indica a
   1.119 +Mercurial que imprima más información de lo que haría usualmente.
   1.120 +
   1.121 +\section{Working with a repository}
   1.122 +
   1.123 +In Mercurial, everything happens inside a \emph{repository}.  The
   1.124 +repository for a project contains all of the files that ``belong to''
   1.125 +that project, along with a historical record of the project's files.
   1.126 +
   1.127 +There's nothing particularly magical about a repository; it is simply
   1.128 +a directory tree in your filesystem that Mercurial treats as special.
   1.129 +You can rename or delete a repository any time you like, using either the
   1.130 +command line or your file browser.
   1.131 +
   1.132 +\subsection{Making a local copy of a repository}
   1.133 +
   1.134 +\emph{Copying} a repository is just a little bit special.  While you
   1.135 +could use a normal file copying command to make a copy of a
   1.136 +repository, it's best to use a built-in command that Mercurial
   1.137 +provides.  This command is called \hgcmd{clone}, because it creates an
   1.138 +identical copy of an existing repository.
   1.139 +\interaction{tour.clone}
   1.140 +If our clone succeeded, we should now have a local directory called
   1.141 +\dirname{hello}.  This directory will contain some files.
   1.142 +\interaction{tour.ls}
   1.143 +These files have the same contents and history in our repository as
   1.144 +they do in the repository we cloned.
   1.145 +
   1.146 +Every Mercurial repository is complete, self-contained, and
   1.147 +independent.  It contains its own private copy of a project's files
   1.148 +and history.  A cloned repository remembers the location of the
   1.149 +repository it was cloned from, but it does not communicate with that
   1.150 +repository, or any other, unless you tell it to.
   1.151 +
   1.152 +What this means for now is that we're free to experiment with our
   1.153 +repository, safe in the knowledge that it's a private ``sandbox'' that
   1.154 +won't affect anyone else.
   1.155 +
   1.156 +\subsection{What's in a repository?}
   1.157 +
   1.158 +When we take a more detailed look inside a repository, we can see that
   1.159 +it contains a directory named \dirname{.hg}.  This is where Mercurial
   1.160 +keeps all of its metadata for the repository.
   1.161 +\interaction{tour.ls-a}
   1.162 +
   1.163 +The contents of the \dirname{.hg} directory and its subdirectories are
   1.164 +private to Mercurial.  Every other file and directory in the
   1.165 +repository is yours to do with as you please.
   1.166 +
   1.167 +To introduce a little terminology, the \dirname{.hg} directory is the
   1.168 +``real'' repository, and all of the files and directories that coexist
   1.169 +with it are said to live in the \emph{working directory}.  An easy way
   1.170 +to remember the distinction is that the \emph{repository} contains the
   1.171 +\emph{history} of your project, while the \emph{working directory}
   1.172 +contains a \emph{snapshot} of your project at a particular point in
   1.173 +history.
   1.174 +
   1.175 +\section{A tour through history}
   1.176 +
   1.177 +One of the first things we might want to do with a new, unfamiliar
   1.178 +repository is understand its history.  The \hgcmd{log} command gives
   1.179 +us a view of history.
   1.180 +\interaction{tour.log}
   1.181 +By default, this command prints a brief paragraph of output for each
   1.182 +change to the project that was recorded.  In Mercurial terminology, we
   1.183 +call each of these recorded events a \emph{changeset}, because it can
   1.184 +contain a record of changes to several files.
   1.185 +
   1.186 +The fields in a record of output from \hgcmd{log} are as follows.
   1.187 +\begin{itemize}
   1.188 +\item[\texttt{changeset}] This field has the format of a number,
   1.189 +  followed by a colon, followed by a hexadecimal string.  These are
   1.190 +  \emph{identifiers} for the changeset.  There are two identifiers
   1.191 +  because the number is shorter and easier to type than the hex
   1.192 +  string.
   1.193 +\item[\texttt{user}] The identity of the person who created the
   1.194 +  changeset.  This is a free-form field, but it most often contains a
   1.195 +  person's name and email address.
   1.196 +\item[\texttt{date}] The date and time on which the changeset was
   1.197 +  created, and the timezone in which it was created.  (The date and
   1.198 +  time are local to that timezone; they display what time and date it
   1.199 +  was for the person who created the changeset.)
   1.200 +\item[\texttt{summary}] The first line of the text message that the
   1.201 +  creator of the changeset entered to describe the changeset.
   1.202 +\end{itemize}
   1.203 +The default output printed by \hgcmd{log} is purely a summary; it is
   1.204 +missing a lot of detail.
   1.205 +
   1.206 +Figure~\ref{fig:tour-basic:history} provides a graphical representation of
   1.207 +the history of the \dirname{hello} repository, to make it a little
   1.208 +easier to see which direction history is ``flowing'' in.  We'll be
   1.209 +returning to this figure several times in this chapter and the chapter
   1.210 +that follows.
   1.211 +
   1.212 +\begin{figure}[ht]
   1.213 +  \centering
   1.214 +  \grafix{tour-history}
   1.215 +  \caption{Graphical history of the \dirname{hello} repository}
   1.216 +  \label{fig:tour-basic:history}
   1.217 +\end{figure}
   1.218 +
   1.219 +\subsection{Changesets, revisions, and talking to other 
   1.220 +  people}
   1.221 +
   1.222 +As English is a notoriously sloppy language, and computer science has
   1.223 +a hallowed history of terminological confusion (why use one term when
   1.224 +four will do?), revision control has a variety of words and phrases
   1.225 +that mean the same thing.  If you are talking about Mercurial history
   1.226 +with other people, you will find that the word ``changeset'' is often
   1.227 +compressed to ``change'' or (when written) ``cset'', and sometimes a
   1.228 +changeset is referred to as a ``revision'' or a ``rev''.
   1.229 +
   1.230 +While it doesn't matter what \emph{word} you use to refer to the
   1.231 +concept of ``a~changeset'', the \emph{identifier} that you use to
   1.232 +refer to ``a~\emph{specific} changeset'' is of great importance.
   1.233 +Recall that the \texttt{changeset} field in the output from
   1.234 +\hgcmd{log} identifies a changeset using both a number and a
   1.235 +hexadecimal string.
   1.236 +\begin{itemize}
   1.237 +\item The revision number is \emph{only valid in that repository},
   1.238 +\item while the hex string is the \emph{permanent, unchanging
   1.239 +    identifier} that will always identify that exact changeset in
   1.240 +  \emph{every} copy of the repository.
   1.241 +\end{itemize}
   1.242 +This distinction is important.  If you send someone an email talking
   1.243 +about ``revision~33'', there's a high likelihood that their
   1.244 +revision~33 will \emph{not be the same} as yours.  The reason for this
   1.245 +is that a revision number depends on the order in which changes
   1.246 +arrived in a repository, and there is no guarantee that the same
   1.247 +changes will happen in the same order in different repositories.
   1.248 +Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
   1.249 +while in another as $1,0,2$.
   1.250 +
   1.251 +Mercurial uses revision numbers purely as a convenient shorthand.  If
   1.252 +you need to discuss a changeset with someone, or make a record of a
   1.253 +changeset for some other reason (for example, in a bug report), use
   1.254 +the hexadecimal identifier.
   1.255 +
   1.256 +\subsection{Viewing specific revisions}
   1.257 +
   1.258 +To narrow the output of \hgcmd{log} down to a single revision, use the
   1.259 +\hgopt{log}{-r} (or \hgopt{log}{--rev}) option.  You can use either a
   1.260 +revision number or a long-form changeset identifier, and you can
   1.261 +provide as many revisions as you want.  \interaction{tour.log-r}
   1.262 +
   1.263 +If you want to see the history of several revisions without having to
   1.264 +list each one, you can use \emph{range notation}; this lets you
   1.265 +express the idea ``I want all revisions between $a$ and $b$,
   1.266 +inclusive''.
   1.267 +\interaction{tour.log.range}
   1.268 +Mercurial also honours the order in which you specify revisions, so
   1.269 +\hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
   1.270 +prints $4,3,2$.
   1.271 +
   1.272 +\subsection{More detailed information}
   1.273 +
   1.274 +While the summary information printed by \hgcmd{log} is useful if you
   1.275 +already know what you're looking for, you may need to see a complete
   1.276 +description of the change, or a list of the files changed, if you're
   1.277 +trying to decide whether a changeset is the one you're looking for.
   1.278 +The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
   1.279 +option gives you this extra detail.
   1.280 +\interaction{tour.log-v}
   1.281 +
   1.282 +If you want to see both the description and content of a change, add
   1.283 +the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option.  This displays
   1.284 +the content of a change as a \emph{unified diff} (if you've never seen
   1.285 +a unified diff before, see section~\ref{sec:mq:patch} for an overview).
   1.286 +\interaction{tour.log-vp}
   1.287 +
   1.288 +\section{All about command options}
   1.289 +
   1.290 +Let's take a brief break from exploring Mercurial commands to discuss
   1.291 +a pattern in the way that they work; you may find this useful to keep
   1.292 +in mind as we continue our tour.
   1.293 +
   1.294 +Mercurial has a consistent and straightforward approach to dealing
   1.295 +with the options that you can pass to commands.  It follows the
   1.296 +conventions for options that are common to modern Linux and Unix
   1.297 +systems.
   1.298 +\begin{itemize}
   1.299 +\item Every option has a long name.  For example, as we've already
   1.300 +  seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
   1.301 +\item Most options have short names, too.  Instead of
   1.302 +  \hgopt{log}{--rev}, we can use \hgopt{log}{-r}.  (The reason that
   1.303 +  some options don't have short names is that the options in question
   1.304 +  are rarely used.)
   1.305 +\item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
   1.306 +  while short options start with one (e.g.~\hgopt{log}{-r}).
   1.307 +\item Option naming and usage is consistent across commands.  For
   1.308 +  example, every command that lets you specify a changeset~ID or
   1.309 +  revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
   1.310 +  arguments.
   1.311 +\end{itemize}
   1.312 +In the examples throughout this book, I use short options instead of
   1.313 +long.  This just reflects my own preference, so don't read anything
   1.314 +significant into it.
   1.315 +
   1.316 +Most commands that print output of some kind will print more output
   1.317 +when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
   1.318 +when passed \hggopt{-q} (or \hggopt{--quiet}).
   1.319 +
   1.320 +\section{Making and reviewing changes}
   1.321 +
   1.322 +Now that we have a grasp of viewing history in Mercurial, let's take a
   1.323 +look at making some changes and examining them.
   1.324 +
   1.325 +The first thing we'll do is isolate our experiment in a repository of
   1.326 +its own.  We use the \hgcmd{clone} command, but we don't need to
   1.327 +clone a copy of the remote repository.  Since we already have a copy
   1.328 +of it locally, we can just clone that instead.  This is much faster
   1.329 +than cloning over the network, and cloning a local repository uses
   1.330 +less disk space in most cases, too.
   1.331 +\interaction{tour.reclone}
   1.332 +As an aside, it's often good practice to keep a ``pristine'' copy of a
   1.333 +remote repository around, which you can then make temporary clones of
   1.334 +to create sandboxes for each task you want to work on.  This lets you
   1.335 +work on multiple tasks in parallel, each isolated from the others
   1.336 +until it's complete and you're ready to integrate it back.  Because
   1.337 +local clones are so cheap, there's almost no overhead to cloning and
   1.338 +destroying repositories whenever you want.
   1.339 +
   1.340 +In our \dirname{my-hello} repository, we have a file
   1.341 +\filename{hello.c} that contains the classic ``hello, world'' program.
   1.342 +Let's use the ancient and venerable \command{sed} command to edit this
   1.343 +file so that it prints a second line of output.  (I'm only using
   1.344 +\command{sed} to do this because it's easy to write a scripted example
   1.345 +this way.  Since you're not under the same constraint, you probably
   1.346 +won't want to use \command{sed}; simply use your preferred text editor to
   1.347 +do the same thing.)
   1.348 +\interaction{tour.sed}
   1.349 +
   1.350 +Mercurial's \hgcmd{status} command will tell us what Mercurial knows
   1.351 +about the files in the repository.
   1.352 +\interaction{tour.status}
   1.353 +The \hgcmd{status} command prints no output for some files, but a line
   1.354 +starting with ``\texttt{M}'' for \filename{hello.c}.  Unless you tell
   1.355 +it to, \hgcmd{status} will not print any output for files that have
   1.356 +not been modified.  
   1.357 +
   1.358 +The ``\texttt{M}'' indicates that Mercurial has noticed that we
   1.359 +modified \filename{hello.c}.  We didn't need to \emph{inform}
   1.360 +Mercurial that we were going to modify the file before we started, or
   1.361 +that we had modified the file after we were done; it was able to
   1.362 +figure this out itself.
   1.363 +
   1.364 +It's a little bit helpful to know that we've modified
   1.365 +\filename{hello.c}, but we might prefer to know exactly \emph{what}
   1.366 +changes we've made to it.  To do this, we use the \hgcmd{diff}
   1.367 +command.
   1.368 +\interaction{tour.diff}
   1.369 +
   1.370 +\section{Recording changes in a new changeset}
   1.371 +
   1.372 +We can modify files, build and test our changes, and use
   1.373 +\hgcmd{status} and \hgcmd{diff} to review our changes, until we're
   1.374 +satisfied with what we've done and arrive at a natural stopping point
   1.375 +where we want to record our work in a new changeset.
   1.376 +
   1.377 +The \hgcmd{commit} command lets us create a new changeset; we'll
   1.378 +usually refer to this as ``making a commit'' or ``committing''.  
   1.379 +
   1.380 +\subsection{Setting up a username}
   1.381 +
   1.382 +When you try to run \hgcmd{commit} for the first time, it is not
   1.383 +guaranteed to succeed.  Mercurial records your name and address with
   1.384 +each change that you commit, so that you and others will later be able
   1.385 +to tell who made each change.  Mercurial tries to automatically figure
   1.386 +out a sensible username to commit the change with.  It will attempt
   1.387 +each of the following methods, in order:
   1.388 +\begin{enumerate}
   1.389 +\item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
   1.390 +  command on the command line, followed by a username, this is always
   1.391 +  given the highest precedence.
   1.392 +\item If you have set the \envar{HGUSER} environment variable, this is
   1.393 +  checked next.
   1.394 +\item If you create a file in your home directory called
   1.395 +  \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
   1.396 +  used next.  To see what the contents of this file should look like,
   1.397 +  refer to section~\ref{sec:tour-basic:username} below.
   1.398 +\item If you have set the \envar{EMAIL} environment variable, this
   1.399 +  will be used next.
   1.400 +\item Mercurial will query your system to find out your local user
   1.401 +  name and host name, and construct a username from these components.
   1.402 +  Since this often results in a username that is not very useful, it
   1.403 +  will print a warning if it has to do this.
   1.404 +\end{enumerate}
   1.405 +If all of these mechanisms fail, Mercurial will fail, printing an
   1.406 +error message.  In this case, it will not let you commit until you set
   1.407 +up a username.
   1.408 +
   1.409 +You should think of the \envar{HGUSER} environment variable and the
   1.410 +\hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
   1.411 +\emph{override} Mercurial's default selection of username.  For normal
   1.412 +use, the simplest and most robust way to set a username for yourself
   1.413 +is by creating a \sfilename{.hgrc} file; see below for details.
   1.414 +
   1.415 +\subsubsection{Creating a Mercurial configuration file}
   1.416 +\label{sec:tour-basic:username}
   1.417 +
   1.418 +To set a user name, use your favourite editor to create a file called
   1.419 +\sfilename{.hgrc} in your home directory.  Mercurial will use this
   1.420 +file to look up your personalised configuration settings.  The initial
   1.421 +contents of your \sfilename{.hgrc} should look like this.
   1.422 +\begin{codesample2}
   1.423 +  # This is a Mercurial configuration file.
   1.424 +  [ui]
   1.425 +  username = Firstname Lastname <email.address@domain.net>
   1.426 +\end{codesample2}
   1.427 +The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
   1.428 +so you can read the ``\texttt{username = ...}'' line as meaning ``set
   1.429 +the value of the \texttt{username} item in the \texttt{ui} section''.
   1.430 +A section continues until a new section begins, or the end of the
   1.431 +file.  Mercurial ignores empty lines and treats any text from
   1.432 +``\texttt{\#}'' to the end of a line as a comment.
   1.433 +
   1.434 +\subsubsection{Choosing a user name}
   1.435 +
   1.436 +You can use any text you like as the value of the \texttt{username}
   1.437 +config item, since this information is for reading by other people,
   1.438 +but for interpreting by Mercurial.  The convention that most people
   1.439 +follow is to use their name and email address, as in the example
   1.440 +above.
   1.441 +
   1.442 +\begin{note}
   1.443 +  Mercurial's built-in web server obfuscates email addresses, to make
   1.444 +  it more difficult for the email harvesting tools that spammers use.
   1.445 +  This reduces the likelihood that you'll start receiving more junk
   1.446 +  email if you publish a Mercurial repository on the web.
   1.447 +\end{note}
   1.448 +
   1.449 +\subsection{Writing a commit message}
   1.450 +
   1.451 +When we commit a change, Mercurial drops us into a text editor, to
   1.452 +enter a message that will describe the modifications we've made in
   1.453 +this changeset.  This is called the \emph{commit message}.  It will be
   1.454 +a record for readers of what we did and why, and it will be printed by
   1.455 +\hgcmd{log} after we've finished committing.
   1.456 +\interaction{tour.commit}
   1.457 +
   1.458 +The editor that the \hgcmd{commit} command drops us into will contain
   1.459 +an empty line, followed by a number of lines starting with
   1.460 +``\texttt{HG:}''.
   1.461 +\begin{codesample2}
   1.462 +  \emph{empty line}
   1.463 +  HG: changed hello.c
   1.464 +\end{codesample2}
   1.465 +Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
   1.466 +them only to tell us which files it's recording changes to.  Modifying
   1.467 +or deleting these lines has no effect.
   1.468 +
   1.469 +\subsection{Writing a good commit message}
   1.470 +
   1.471 +Since \hgcmd{log} only prints the first line of a commit message by
   1.472 +default, it's best to write a commit message whose first line stands
   1.473 +alone.  Here's a real example of a commit message that \emph{doesn't}
   1.474 +follow this guideline, and hence has a summary that is not readable.
   1.475 +\begin{codesample2}
   1.476 +  changeset:   73:584af0e231be
   1.477 +  user:        Censored Person <censored.person@example.org>
   1.478 +  date:        Tue Sep 26 21:37:07 2006 -0700
   1.479 +  summary:     include buildmeister/commondefs.   Add an exports and install
   1.480 +\end{codesample2}
   1.481 +
   1.482 +As far as the remainder of the contents of the commit message are
   1.483 +concerned, there are no hard-and-fast rules.  Mercurial itself doesn't
   1.484 +interpret or care about the contents of the commit message, though
   1.485 +your project may have policies that dictate a certain kind of
   1.486 +formatting.
   1.487 +
   1.488 +My personal preference is for short, but informative, commit messages
   1.489 +that tell me something that I can't figure out with a quick glance at
   1.490 +the output of \hgcmdargs{log}{--patch}.
   1.491 +
   1.492 +\subsection{Aborting a commit}
   1.493 +
   1.494 +If you decide that you don't want to commit while in the middle of
   1.495 +editing a commit message, simply exit from your editor without saving
   1.496 +the file that it's editing.  This will cause nothing to happen to
   1.497 +either the repository or the working directory.
   1.498 +
   1.499 +If we run the \hgcmd{commit} command without any arguments, it records
   1.500 +all of the changes we've made, as reported by \hgcmd{status} and
   1.501 +\hgcmd{diff}.
   1.502 +
   1.503 +\subsection{Admiring our new handiwork}
   1.504 +
   1.505 +Once we've finished the commit, we can use the \hgcmd{tip} command to
   1.506 +display the changeset we just created.  This command produces output
   1.507 +that is identical to \hgcmd{log}, but it only displays the newest
   1.508 +revision in the repository.
   1.509 +\interaction{tour.tip}
   1.510 +We refer to the newest revision in the repository as the tip revision,
   1.511 +or simply the tip.
   1.512 +
   1.513 +\section{Sharing changes}
   1.514 +
   1.515 +We mentioned earlier that repositories in Mercurial are
   1.516 +self-contained.  This means that the changeset we just created exists
   1.517 +only in our \dirname{my-hello} repository.  Let's look at a few ways
   1.518 +that we can propagate this change into other repositories.
   1.519 +
   1.520 +\subsection{Pulling changes from another repository}
   1.521 +\label{sec:tour:pull}
   1.522 +
   1.523 +To get started, let's clone our original \dirname{hello} repository,
   1.524 +which does not contain the change we just committed.  We'll call our
   1.525 +temporary repository \dirname{hello-pull}.
   1.526 +\interaction{tour.clone-pull}
   1.527 +
   1.528 +We'll use the \hgcmd{pull} command to bring changes from
   1.529 +\dirname{my-hello} into \dirname{hello-pull}.  However, blindly
   1.530 +pulling unknown changes into a repository is a somewhat scary
   1.531 +prospect.  Mercurial provides the \hgcmd{incoming} command to tell us
   1.532 +what changes the \hgcmd{pull} command \emph{would} pull into the
   1.533 +repository, without actually pulling the changes in.
   1.534 +\interaction{tour.incoming}
   1.535 +(Of course, someone could cause more changesets to appear in the
   1.536 +repository that we ran \hgcmd{incoming} in, before we get a chance to
   1.537 +\hgcmd{pull} the changes, so that we could end up pulling changes that we
   1.538 +didn't expect.)
   1.539 +
   1.540 +Bringing changes into a repository is a simple matter of running the
   1.541 +\hgcmd{pull} command, and telling it which repository to pull from.
   1.542 +\interaction{tour.pull}
   1.543 +As you can see from the before-and-after output of \hgcmd{tip}, we
   1.544 +have successfully pulled changes into our repository.  There remains
   1.545 +one step before we can see these changes in the working directory.
   1.546 +
   1.547 +\subsection{Updating the working directory}
   1.548 +
   1.549 +We have so far glossed over the relationship between a repository and
   1.550 +its working directory.  The \hgcmd{pull} command that we ran in
   1.551 +section~\ref{sec:tour:pull} brought changes into the repository, but
   1.552 +if we check, there's no sign of those changes in the working
   1.553 +directory.  This is because \hgcmd{pull} does not (by default) touch
   1.554 +the working directory.  Instead, we use the \hgcmd{update} command to
   1.555 +do this.
   1.556 +\interaction{tour.update}
   1.557 +
   1.558 +It might seem a bit strange that \hgcmd{pull} doesn't update the
   1.559 +working directory automatically.  There's actually a good reason for
   1.560 +this: you can use \hgcmd{update} to update the working directory to
   1.561 +the state it was in at \emph{any revision} in the history of the
   1.562 +repository.  If you had the working directory updated to an old
   1.563 +revision---to hunt down the origin of a bug, say---and ran a
   1.564 +\hgcmd{pull} which automatically updated the working directory to a
   1.565 +new revision, you might not be terribly happy.
   1.566 +
   1.567 +However, since pull-then-update is such a common thing to do,
   1.568 +Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
   1.569 +option to \hgcmd{pull}.
   1.570 +\begin{codesample2}
   1.571 +  hg pull -u
   1.572 +\end{codesample2}
   1.573 +If you look back at the output of \hgcmd{pull} in
   1.574 +section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
   1.575 +you can see that it printed a helpful reminder that we'd have to take
   1.576 +an explicit step to update the working directory:
   1.577 +\begin{codesample2}
   1.578 +  (run 'hg update' to get a working copy)
   1.579 +\end{codesample2}
   1.580 +
   1.581 +To find out what revision the working directory is at, use the
   1.582 +\hgcmd{parents} command.
   1.583 +\interaction{tour.parents}
   1.584 +If you look back at figure~\ref{fig:tour-basic:history}, you'll see
   1.585 +arrows connecting each changeset.  The node that the arrow leads
   1.586 +\emph{from} in each case is a parent, and the node that the arrow
   1.587 +leads \emph{to} is its child.  The working directory has a parent in
   1.588 +just the same way; this is the changeset that the working directory
   1.589 +currently contains.
   1.590 +
   1.591 +To update the working directory to a particular revision, give a
   1.592 +revision number or changeset~ID to the \hgcmd{update} command.
   1.593 +\interaction{tour.older}
   1.594 +If you omit an explicit revision, \hgcmd{update} will update to the
   1.595 +tip revision, as shown by the second call to \hgcmd{update} in the
   1.596 +example above.
   1.597 +
   1.598 +\subsection{Pushing changes to another repository}
   1.599 +
   1.600 +Mercurial lets us push changes to another repository, from the
   1.601 +repository we're currently visiting.  As with the example of
   1.602 +\hgcmd{pull} above, we'll create a temporary repository to push our
   1.603 +changes into.
   1.604 +\interaction{tour.clone-push}
   1.605 +The \hgcmd{outgoing} command tells us what changes would be pushed
   1.606 +into another repository.
   1.607 +\interaction{tour.outgoing}
   1.608 +And the \hgcmd{push} command does the actual push.
   1.609 +\interaction{tour.push}
   1.610 +As with \hgcmd{pull}, the \hgcmd{push} command does not update the
   1.611 +working directory in the repository that it's pushing changes into.
   1.612 +(Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
   1.613 +option that updates the other repository's working directory.)
   1.614 +
   1.615 +What happens if we try to pull or push changes and the receiving
   1.616 +repository already has those changes?  Nothing too exciting.
   1.617 +\interaction{tour.push.nothing}
   1.618 +
   1.619 +\subsection{Sharing changes over a network}
   1.620 +
   1.621 +The commands we have covered in the previous few sections are not
   1.622 +limited to working with local repositories.  Each works in exactly the
   1.623 +same fashion over a network connection; simply pass in a URL instead
   1.624 +of a local path.
   1.625 +\interaction{tour.outgoing.net}
   1.626 +In this example, we can see what changes we could push to the remote
   1.627 +repository, but the repository is understandably not set up to let
   1.628 +anonymous users push to it.
   1.629 +\interaction{tour.push.net}
   1.630 +
   1.631 +%%% Local Variables: 
   1.632 +%%% mode: latex
   1.633 +%%% TeX-master: "00book"
   1.634 +%%% End: