hgbook
diff es/tour-basic.tex @ 346:6d899c80bfb5
added note about terms that have more than one accepted usage form.
author | jerojasro@localhost |
---|---|
date | Sun Oct 19 22:30:24 2008 -0500 (2008-10-19) |
parents | 04c08ad7e92e |
children | 9f460a706292 |
line diff
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 22:30:24 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: