hgbook
annotate es/tour-basic.tex @ 343:2fb78d342e07
changed es/Leame.1st
upgraded the list of files on translation and revision.
added a term (builtin) to the glossary
changed es/concepts.tex
file added to define labels needed by other tex files
changed es/preface.tex
killed a TODO
changed es/tour-basic.tex
I have began the translation of this file. 34% completed, according to vim
changed es/undo.tex
file added to define labels needed by other tex files
upgraded the list of files on translation and revision.
added a term (builtin) to the glossary
changed es/concepts.tex
file added to define labels needed by other tex files
changed es/preface.tex
killed a TODO
changed es/tour-basic.tex
I have began the translation of this file. 34% completed, according to vim
changed es/undo.tex
file added to define labels needed by other tex files
author | jerojasro@localhost |
---|---|
date | Sun Oct 19 19:56:21 2008 -0500 (2008-10-19) |
parents | 04c08ad7e92e |
children | 9f460a706292 |
rev | line source |
---|---|
jerojasro@343 | 1 \chapter{Una gira de Mercurial: lo básico} |
jerojasro@343 | 2 \label{chap:tour-basic} |
jerojasro@343 | 3 |
jerojasro@343 | 4 \section{Instalar Mercurial en su sistema} |
jerojasro@343 | 5 \label{sec:tour:install} |
jerojasro@343 | 6 Hay paquetes binarios precompilados de Mercurial disponibles para cada |
jerojasro@343 | 7 sistema operativo popular. Esto hace fácil empezar a usar Mercurial |
jerojasro@343 | 8 en su computador inmediatamente. |
jerojasro@343 | 9 |
jerojasro@343 | 10 \subsection{Linux} |
jerojasro@343 | 11 |
jerojasro@343 | 12 Dado que cada distribución de Linux tiene sus propias herramientas de |
jerojasro@343 | 13 manejo de paquetes, políticas, y ritmos de desarrollo, es difícil dar |
jerojasro@343 | 14 un conjunto exhaustivo de instrucciones sobre cómo instalar el paquete |
jerojasro@343 | 15 de Mercurial. La versión de Mercurial que usted tenga a disposición |
jerojasro@343 | 16 puede variar dependiendo de qué tan activa sea la persona que mantiene |
jerojasro@343 | 17 el paquete para su distribución. |
jerojasro@343 | 18 |
jerojasro@343 | 19 Para mantener las cosas simples, me enfocaré en instalar Mercurial |
jerojasro@343 | 20 desde la línea de comandos en las distribuciones de Linux más |
jerojasro@343 | 21 populares. La mayoría de estas distribuciones proveen administradores |
jerojasro@343 | 22 de paquetes gráficos que le permitirán instalar Mercurial con un solo |
jerojasro@343 | 23 clic; el nombre de paquete a buscar es \texttt{mercurial}. |
jerojasro@343 | 24 |
jerojasro@343 | 25 \begin{itemize} |
jerojasro@343 | 26 \item[Debian] |
jerojasro@343 | 27 \begin{codesample4} |
jerojasro@343 | 28 apt-get install mercurial |
jerojasro@343 | 29 \end{codesample4} |
jerojasro@343 | 30 |
jerojasro@343 | 31 \item[Fedora Core] |
jerojasro@343 | 32 \begin{codesample4} |
jerojasro@343 | 33 yum install mercurial |
jerojasro@343 | 34 \end{codesample4} |
jerojasro@343 | 35 |
jerojasro@343 | 36 \item[Gentoo] |
jerojasro@343 | 37 \begin{codesample4} |
jerojasro@343 | 38 emerge mercurial |
jerojasro@343 | 39 \end{codesample4} |
jerojasro@343 | 40 |
jerojasro@343 | 41 \item[OpenSUSE] |
jerojasro@343 | 42 \begin{codesample4} |
jerojasro@343 | 43 yum install mercurial |
jerojasro@343 | 44 \end{codesample4} |
jerojasro@343 | 45 |
jerojasro@343 | 46 \item[Ubuntu] El paquete de Mercurial de Ubuntu está basado en el de |
jerojasro@343 | 47 Debian. Para instalarlo, ejecute el siguiente comando. |
jerojasro@343 | 48 \begin{codesample4} |
jerojasro@343 | 49 apt-get install mercurial |
jerojasro@343 | 50 \end{codesample4} |
jerojasro@343 | 51 El paquete de Mercurial para Ubuntu tiende a atrasarse con respecto |
jerojasro@343 | 52 a la versión de Debian por un margen de tiempo considerable |
jerojasro@343 | 53 (al momento de escribir esto, 7 meses), lo que en algunos casos |
jerojasro@343 | 54 significará que usted puede encontrarse con problemas que ya habrán |
jerojasro@343 | 55 sido resueltos en el paquete de Debian. |
jerojasro@343 | 56 \end{itemize} |
jerojasro@343 | 57 |
jerojasro@343 | 58 \subsection{Solaris} |
jerojasro@343 | 59 |
jerojasro@343 | 60 SunFreeWare, en \url{http://www.sunfreeware.com}, es una buena fuente |
jerojasro@343 | 61 para un gran número de paquetes compilados para Solaris para las |
jerojasro@343 | 62 arquitecturas Intel y Sparc de 32 y 64 bits, incluyendo versiones |
jerojasro@343 | 63 actuales de Mercurial. |
jerojasro@343 | 64 |
jerojasro@343 | 65 \subsection{Mac OS X} |
jerojasro@343 | 66 |
jerojasro@343 | 67 Lee Cantey publica un instalador de Mercurial para Mac OS~X en |
jerojasro@343 | 68 \url{http://mercurial.berkwood.com}. Este paquete funciona en tanto |
jerojasro@343 | 69 en Macs basados en Intel como basados en PowerPC. Antes de que pueda |
jerojasro@343 | 70 usarlo, usted debe instalar una versión compatible de Universal |
jerojasro@343 | 71 MacPython~\cite{web:macpython}. Esto es fácil de hacer; simplemente |
jerojasro@343 | 72 siga las instrucciones de el sitio de Lee. |
jerojasro@343 | 73 |
jerojasro@343 | 74 También es posible instalar Mercurial usando Fink o MacPorts, dos |
jerojasro@343 | 75 administradores de paquetes gratuitos y populares para Mac OS X. Si |
jerojasro@343 | 76 usted tiene Fink, use \command{sudo apt-get install mercurial-py25}. |
jerojasro@343 | 77 Si usa MacPorts, \command{sudo port install mercurial}. |
jerojasro@343 | 78 |
jerojasro@343 | 79 \subsection{Windows} |
jerojasro@343 | 80 |
jerojasro@343 | 81 Lee Cantey publica un instalador de Mercurial para Windows en |
jerojasro@343 | 82 \url{http://mercurial.berkwood.com}. Este paquete no tiene |
jerojasro@343 | 83 % TODO traducción de it just works. Agreed? |
jerojasro@343 | 84 dependencias externas; ``simplemente funciona''. |
jerojasro@343 | 85 |
jerojasro@343 | 86 \begin{note} |
jerojasro@343 | 87 La versión de Windows de Mercurial no convierte automáticamente |
jerojasro@343 | 88 los fines de línea entre estilos Windows y Unix. Si usted desea |
jerojasro@343 | 89 compartir trabajo con usuarios de Unix, deberá hacer un trabajo |
jerojasro@343 | 90 adicional de configuración. XXX Terminar esto. |
jerojasro@343 | 91 \end{note} |
jerojasro@343 | 92 |
jerojasro@343 | 93 \section{Arrancando} |
jerojasro@343 | 94 |
jerojasro@343 | 95 Para empezar, usaremos el comando \hgcmd{version} para revisar si |
jerojasro@343 | 96 Mercurial está instalado adecuadamente. La información de la versión |
jerojasro@343 | 97 que es impresa no es tan importante; lo que nos importa es si imprime |
jerojasro@343 | 98 algo en absoluto. |
jerojasro@343 | 99 |
jerojasro@343 | 100 \interaction{tour.version} |
jerojasro@343 | 101 |
jerojasro@343 | 102 % TODO builtin-> integrado? |
jerojasro@343 | 103 \subsection{Ayuda integrada} |
jerojasro@343 | 104 |
jerojasro@343 | 105 Mercurial provee un sistema de ayuda integrada. Esto es invaluable |
jerojasro@343 | 106 para ésas ocasiones en la que usted está atorado tratando de recordar |
jerojasro@343 | 107 cómo ejecutar un comando. Si está completamente atorado, simplemente |
jerojasro@343 | 108 ejecute \hgcmd{help}; esto imprimirá una breve lista de comandos, |
jerojasro@343 | 109 junto con una descripción de qué hace cada uno. Si usted solicita |
jerojasro@343 | 110 ayuda sobre un comando específico (como abajo), se imprime información |
jerojasro@343 | 111 más detallada. |
jerojasro@343 | 112 \interaction{tour.help} |
jerojasro@343 | 113 Para un nivel más impresionante de detalle (que usted no va a |
jerojasro@343 | 114 necesitar usualmente) ejecute \hgcmdargs{help}{\hggopt{-v}}. La opción |
jerojasro@343 | 115 \hggopt{-v} es la abreviación para \hggopt{--verbose}, y le indica a |
jerojasro@343 | 116 Mercurial que imprima más información de lo que haría usualmente. |
jerojasro@343 | 117 |
jerojasro@343 | 118 \section{Working with a repository} |
jerojasro@343 | 119 |
jerojasro@343 | 120 In Mercurial, everything happens inside a \emph{repository}. The |
jerojasro@343 | 121 repository for a project contains all of the files that ``belong to'' |
jerojasro@343 | 122 that project, along with a historical record of the project's files. |
jerojasro@343 | 123 |
jerojasro@343 | 124 There's nothing particularly magical about a repository; it is simply |
jerojasro@343 | 125 a directory tree in your filesystem that Mercurial treats as special. |
jerojasro@343 | 126 You can rename or delete a repository any time you like, using either the |
jerojasro@343 | 127 command line or your file browser. |
jerojasro@343 | 128 |
jerojasro@343 | 129 \subsection{Making a local copy of a repository} |
jerojasro@343 | 130 |
jerojasro@343 | 131 \emph{Copying} a repository is just a little bit special. While you |
jerojasro@343 | 132 could use a normal file copying command to make a copy of a |
jerojasro@343 | 133 repository, it's best to use a built-in command that Mercurial |
jerojasro@343 | 134 provides. This command is called \hgcmd{clone}, because it creates an |
jerojasro@343 | 135 identical copy of an existing repository. |
jerojasro@343 | 136 \interaction{tour.clone} |
jerojasro@343 | 137 If our clone succeeded, we should now have a local directory called |
jerojasro@343 | 138 \dirname{hello}. This directory will contain some files. |
jerojasro@343 | 139 \interaction{tour.ls} |
jerojasro@343 | 140 These files have the same contents and history in our repository as |
jerojasro@343 | 141 they do in the repository we cloned. |
jerojasro@343 | 142 |
jerojasro@343 | 143 Every Mercurial repository is complete, self-contained, and |
jerojasro@343 | 144 independent. It contains its own private copy of a project's files |
jerojasro@343 | 145 and history. A cloned repository remembers the location of the |
jerojasro@343 | 146 repository it was cloned from, but it does not communicate with that |
jerojasro@343 | 147 repository, or any other, unless you tell it to. |
jerojasro@343 | 148 |
jerojasro@343 | 149 What this means for now is that we're free to experiment with our |
jerojasro@343 | 150 repository, safe in the knowledge that it's a private ``sandbox'' that |
jerojasro@343 | 151 won't affect anyone else. |
jerojasro@343 | 152 |
jerojasro@343 | 153 \subsection{What's in a repository?} |
jerojasro@343 | 154 |
jerojasro@343 | 155 When we take a more detailed look inside a repository, we can see that |
jerojasro@343 | 156 it contains a directory named \dirname{.hg}. This is where Mercurial |
jerojasro@343 | 157 keeps all of its metadata for the repository. |
jerojasro@343 | 158 \interaction{tour.ls-a} |
jerojasro@343 | 159 |
jerojasro@343 | 160 The contents of the \dirname{.hg} directory and its subdirectories are |
jerojasro@343 | 161 private to Mercurial. Every other file and directory in the |
jerojasro@343 | 162 repository is yours to do with as you please. |
jerojasro@343 | 163 |
jerojasro@343 | 164 To introduce a little terminology, the \dirname{.hg} directory is the |
jerojasro@343 | 165 ``real'' repository, and all of the files and directories that coexist |
jerojasro@343 | 166 with it are said to live in the \emph{working directory}. An easy way |
jerojasro@343 | 167 to remember the distinction is that the \emph{repository} contains the |
jerojasro@343 | 168 \emph{history} of your project, while the \emph{working directory} |
jerojasro@343 | 169 contains a \emph{snapshot} of your project at a particular point in |
jerojasro@343 | 170 history. |
jerojasro@343 | 171 |
jerojasro@343 | 172 \section{A tour through history} |
jerojasro@343 | 173 |
jerojasro@343 | 174 One of the first things we might want to do with a new, unfamiliar |
jerojasro@343 | 175 repository is understand its history. The \hgcmd{log} command gives |
jerojasro@343 | 176 us a view of history. |
jerojasro@343 | 177 \interaction{tour.log} |
jerojasro@343 | 178 By default, this command prints a brief paragraph of output for each |
jerojasro@343 | 179 change to the project that was recorded. In Mercurial terminology, we |
jerojasro@343 | 180 call each of these recorded events a \emph{changeset}, because it can |
jerojasro@343 | 181 contain a record of changes to several files. |
jerojasro@343 | 182 |
jerojasro@343 | 183 The fields in a record of output from \hgcmd{log} are as follows. |
jerojasro@343 | 184 \begin{itemize} |
jerojasro@343 | 185 \item[\texttt{changeset}] This field has the format of a number, |
jerojasro@343 | 186 followed by a colon, followed by a hexadecimal string. These are |
jerojasro@343 | 187 \emph{identifiers} for the changeset. There are two identifiers |
jerojasro@343 | 188 because the number is shorter and easier to type than the hex |
jerojasro@343 | 189 string. |
jerojasro@343 | 190 \item[\texttt{user}] The identity of the person who created the |
jerojasro@343 | 191 changeset. This is a free-form field, but it most often contains a |
jerojasro@343 | 192 person's name and email address. |
jerojasro@343 | 193 \item[\texttt{date}] The date and time on which the changeset was |
jerojasro@343 | 194 created, and the timezone in which it was created. (The date and |
jerojasro@343 | 195 time are local to that timezone; they display what time and date it |
jerojasro@343 | 196 was for the person who created the changeset.) |
jerojasro@343 | 197 \item[\texttt{summary}] The first line of the text message that the |
jerojasro@343 | 198 creator of the changeset entered to describe the changeset. |
jerojasro@343 | 199 \end{itemize} |
jerojasro@343 | 200 The default output printed by \hgcmd{log} is purely a summary; it is |
jerojasro@343 | 201 missing a lot of detail. |
jerojasro@343 | 202 |
jerojasro@343 | 203 Figure~\ref{fig:tour-basic:history} provides a graphical representation of |
jerojasro@343 | 204 the history of the \dirname{hello} repository, to make it a little |
jerojasro@343 | 205 easier to see which direction history is ``flowing'' in. We'll be |
jerojasro@343 | 206 returning to this figure several times in this chapter and the chapter |
jerojasro@343 | 207 that follows. |
jerojasro@343 | 208 |
jerojasro@343 | 209 \begin{figure}[ht] |
jerojasro@343 | 210 \centering |
jerojasro@343 | 211 \grafix{tour-history} |
jerojasro@343 | 212 \caption{Graphical history of the \dirname{hello} repository} |
jerojasro@343 | 213 \label{fig:tour-basic:history} |
jerojasro@343 | 214 \end{figure} |
jerojasro@343 | 215 |
jerojasro@343 | 216 \subsection{Changesets, revisions, and talking to other |
jerojasro@343 | 217 people} |
jerojasro@343 | 218 |
jerojasro@343 | 219 As English is a notoriously sloppy language, and computer science has |
jerojasro@343 | 220 a hallowed history of terminological confusion (why use one term when |
jerojasro@343 | 221 four will do?), revision control has a variety of words and phrases |
jerojasro@343 | 222 that mean the same thing. If you are talking about Mercurial history |
jerojasro@343 | 223 with other people, you will find that the word ``changeset'' is often |
jerojasro@343 | 224 compressed to ``change'' or (when written) ``cset'', and sometimes a |
jerojasro@343 | 225 changeset is referred to as a ``revision'' or a ``rev''. |
jerojasro@343 | 226 |
jerojasro@343 | 227 While it doesn't matter what \emph{word} you use to refer to the |
jerojasro@343 | 228 concept of ``a~changeset'', the \emph{identifier} that you use to |
jerojasro@343 | 229 refer to ``a~\emph{specific} changeset'' is of great importance. |
jerojasro@343 | 230 Recall that the \texttt{changeset} field in the output from |
jerojasro@343 | 231 \hgcmd{log} identifies a changeset using both a number and a |
jerojasro@343 | 232 hexadecimal string. |
jerojasro@343 | 233 \begin{itemize} |
jerojasro@343 | 234 \item The revision number is \emph{only valid in that repository}, |
jerojasro@343 | 235 \item while the hex string is the \emph{permanent, unchanging |
jerojasro@343 | 236 identifier} that will always identify that exact changeset in |
jerojasro@343 | 237 \emph{every} copy of the repository. |
jerojasro@343 | 238 \end{itemize} |
jerojasro@343 | 239 This distinction is important. If you send someone an email talking |
jerojasro@343 | 240 about ``revision~33'', there's a high likelihood that their |
jerojasro@343 | 241 revision~33 will \emph{not be the same} as yours. The reason for this |
jerojasro@343 | 242 is that a revision number depends on the order in which changes |
jerojasro@343 | 243 arrived in a repository, and there is no guarantee that the same |
jerojasro@343 | 244 changes will happen in the same order in different repositories. |
jerojasro@343 | 245 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$, |
jerojasro@343 | 246 while in another as $1,0,2$. |
jerojasro@343 | 247 |
jerojasro@343 | 248 Mercurial uses revision numbers purely as a convenient shorthand. If |
jerojasro@343 | 249 you need to discuss a changeset with someone, or make a record of a |
jerojasro@343 | 250 changeset for some other reason (for example, in a bug report), use |
jerojasro@343 | 251 the hexadecimal identifier. |
jerojasro@343 | 252 |
jerojasro@343 | 253 \subsection{Viewing specific revisions} |
jerojasro@343 | 254 |
jerojasro@343 | 255 To narrow the output of \hgcmd{log} down to a single revision, use the |
jerojasro@343 | 256 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a |
jerojasro@343 | 257 revision number or a long-form changeset identifier, and you can |
jerojasro@343 | 258 provide as many revisions as you want. \interaction{tour.log-r} |
jerojasro@343 | 259 |
jerojasro@343 | 260 If you want to see the history of several revisions without having to |
jerojasro@343 | 261 list each one, you can use \emph{range notation}; this lets you |
jerojasro@343 | 262 express the idea ``I want all revisions between $a$ and $b$, |
jerojasro@343 | 263 inclusive''. |
jerojasro@343 | 264 \interaction{tour.log.range} |
jerojasro@343 | 265 Mercurial also honours the order in which you specify revisions, so |
jerojasro@343 | 266 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2} |
jerojasro@343 | 267 prints $4,3,2$. |
jerojasro@343 | 268 |
jerojasro@343 | 269 \subsection{More detailed information} |
jerojasro@343 | 270 |
jerojasro@343 | 271 While the summary information printed by \hgcmd{log} is useful if you |
jerojasro@343 | 272 already know what you're looking for, you may need to see a complete |
jerojasro@343 | 273 description of the change, or a list of the files changed, if you're |
jerojasro@343 | 274 trying to decide whether a changeset is the one you're looking for. |
jerojasro@343 | 275 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose}) |
jerojasro@343 | 276 option gives you this extra detail. |
jerojasro@343 | 277 \interaction{tour.log-v} |
jerojasro@343 | 278 |
jerojasro@343 | 279 If you want to see both the description and content of a change, add |
jerojasro@343 | 280 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays |
jerojasro@343 | 281 the content of a change as a \emph{unified diff} (if you've never seen |
jerojasro@343 | 282 a unified diff before, see section~\ref{sec:mq:patch} for an overview). |
jerojasro@343 | 283 \interaction{tour.log-vp} |
jerojasro@343 | 284 |
jerojasro@343 | 285 \section{All about command options} |
jerojasro@343 | 286 |
jerojasro@343 | 287 Let's take a brief break from exploring Mercurial commands to discuss |
jerojasro@343 | 288 a pattern in the way that they work; you may find this useful to keep |
jerojasro@343 | 289 in mind as we continue our tour. |
jerojasro@343 | 290 |
jerojasro@343 | 291 Mercurial has a consistent and straightforward approach to dealing |
jerojasro@343 | 292 with the options that you can pass to commands. It follows the |
jerojasro@343 | 293 conventions for options that are common to modern Linux and Unix |
jerojasro@343 | 294 systems. |
jerojasro@343 | 295 \begin{itemize} |
jerojasro@343 | 296 \item Every option has a long name. For example, as we've already |
jerojasro@343 | 297 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option. |
jerojasro@343 | 298 \item Most options have short names, too. Instead of |
jerojasro@343 | 299 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that |
jerojasro@343 | 300 some options don't have short names is that the options in question |
jerojasro@343 | 301 are rarely used.) |
jerojasro@343 | 302 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}), |
jerojasro@343 | 303 while short options start with one (e.g.~\hgopt{log}{-r}). |
jerojasro@343 | 304 \item Option naming and usage is consistent across commands. For |
jerojasro@343 | 305 example, every command that lets you specify a changeset~ID or |
jerojasro@343 | 306 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev} |
jerojasro@343 | 307 arguments. |
jerojasro@343 | 308 \end{itemize} |
jerojasro@343 | 309 In the examples throughout this book, I use short options instead of |
jerojasro@343 | 310 long. This just reflects my own preference, so don't read anything |
jerojasro@343 | 311 significant into it. |
jerojasro@343 | 312 |
jerojasro@343 | 313 Most commands that print output of some kind will print more output |
jerojasro@343 | 314 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less |
jerojasro@343 | 315 when passed \hggopt{-q} (or \hggopt{--quiet}). |
jerojasro@343 | 316 |
jerojasro@343 | 317 \section{Making and reviewing changes} |
jerojasro@343 | 318 |
jerojasro@343 | 319 Now that we have a grasp of viewing history in Mercurial, let's take a |
jerojasro@343 | 320 look at making some changes and examining them. |
jerojasro@343 | 321 |
jerojasro@343 | 322 The first thing we'll do is isolate our experiment in a repository of |
jerojasro@343 | 323 its own. We use the \hgcmd{clone} command, but we don't need to |
jerojasro@343 | 324 clone a copy of the remote repository. Since we already have a copy |
jerojasro@343 | 325 of it locally, we can just clone that instead. This is much faster |
jerojasro@343 | 326 than cloning over the network, and cloning a local repository uses |
jerojasro@343 | 327 less disk space in most cases, too. |
jerojasro@343 | 328 \interaction{tour.reclone} |
jerojasro@343 | 329 As an aside, it's often good practice to keep a ``pristine'' copy of a |
jerojasro@343 | 330 remote repository around, which you can then make temporary clones of |
jerojasro@343 | 331 to create sandboxes for each task you want to work on. This lets you |
jerojasro@343 | 332 work on multiple tasks in parallel, each isolated from the others |
jerojasro@343 | 333 until it's complete and you're ready to integrate it back. Because |
jerojasro@343 | 334 local clones are so cheap, there's almost no overhead to cloning and |
jerojasro@343 | 335 destroying repositories whenever you want. |
jerojasro@343 | 336 |
jerojasro@343 | 337 In our \dirname{my-hello} repository, we have a file |
jerojasro@343 | 338 \filename{hello.c} that contains the classic ``hello, world'' program. |
jerojasro@343 | 339 Let's use the ancient and venerable \command{sed} command to edit this |
jerojasro@343 | 340 file so that it prints a second line of output. (I'm only using |
jerojasro@343 | 341 \command{sed} to do this because it's easy to write a scripted example |
jerojasro@343 | 342 this way. Since you're not under the same constraint, you probably |
jerojasro@343 | 343 won't want to use \command{sed}; simply use your preferred text editor to |
jerojasro@343 | 344 do the same thing.) |
jerojasro@343 | 345 \interaction{tour.sed} |
jerojasro@343 | 346 |
jerojasro@343 | 347 Mercurial's \hgcmd{status} command will tell us what Mercurial knows |
jerojasro@343 | 348 about the files in the repository. |
jerojasro@343 | 349 \interaction{tour.status} |
jerojasro@343 | 350 The \hgcmd{status} command prints no output for some files, but a line |
jerojasro@343 | 351 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell |
jerojasro@343 | 352 it to, \hgcmd{status} will not print any output for files that have |
jerojasro@343 | 353 not been modified. |
jerojasro@343 | 354 |
jerojasro@343 | 355 The ``\texttt{M}'' indicates that Mercurial has noticed that we |
jerojasro@343 | 356 modified \filename{hello.c}. We didn't need to \emph{inform} |
jerojasro@343 | 357 Mercurial that we were going to modify the file before we started, or |
jerojasro@343 | 358 that we had modified the file after we were done; it was able to |
jerojasro@343 | 359 figure this out itself. |
jerojasro@343 | 360 |
jerojasro@343 | 361 It's a little bit helpful to know that we've modified |
jerojasro@343 | 362 \filename{hello.c}, but we might prefer to know exactly \emph{what} |
jerojasro@343 | 363 changes we've made to it. To do this, we use the \hgcmd{diff} |
jerojasro@343 | 364 command. |
jerojasro@343 | 365 \interaction{tour.diff} |
jerojasro@343 | 366 |
jerojasro@343 | 367 \section{Recording changes in a new changeset} |
jerojasro@343 | 368 |
jerojasro@343 | 369 We can modify files, build and test our changes, and use |
jerojasro@343 | 370 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're |
jerojasro@343 | 371 satisfied with what we've done and arrive at a natural stopping point |
jerojasro@343 | 372 where we want to record our work in a new changeset. |
jerojasro@343 | 373 |
jerojasro@343 | 374 The \hgcmd{commit} command lets us create a new changeset; we'll |
jerojasro@343 | 375 usually refer to this as ``making a commit'' or ``committing''. |
jerojasro@343 | 376 |
jerojasro@343 | 377 \subsection{Setting up a username} |
jerojasro@343 | 378 |
jerojasro@343 | 379 When you try to run \hgcmd{commit} for the first time, it is not |
jerojasro@343 | 380 guaranteed to succeed. Mercurial records your name and address with |
jerojasro@343 | 381 each change that you commit, so that you and others will later be able |
jerojasro@343 | 382 to tell who made each change. Mercurial tries to automatically figure |
jerojasro@343 | 383 out a sensible username to commit the change with. It will attempt |
jerojasro@343 | 384 each of the following methods, in order: |
jerojasro@343 | 385 \begin{enumerate} |
jerojasro@343 | 386 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit} |
jerojasro@343 | 387 command on the command line, followed by a username, this is always |
jerojasro@343 | 388 given the highest precedence. |
jerojasro@343 | 389 \item If you have set the \envar{HGUSER} environment variable, this is |
jerojasro@343 | 390 checked next. |
jerojasro@343 | 391 \item If you create a file in your home directory called |
jerojasro@343 | 392 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be |
jerojasro@343 | 393 used next. To see what the contents of this file should look like, |
jerojasro@343 | 394 refer to section~\ref{sec:tour-basic:username} below. |
jerojasro@343 | 395 \item If you have set the \envar{EMAIL} environment variable, this |
jerojasro@343 | 396 will be used next. |
jerojasro@343 | 397 \item Mercurial will query your system to find out your local user |
jerojasro@343 | 398 name and host name, and construct a username from these components. |
jerojasro@343 | 399 Since this often results in a username that is not very useful, it |
jerojasro@343 | 400 will print a warning if it has to do this. |
jerojasro@343 | 401 \end{enumerate} |
jerojasro@343 | 402 If all of these mechanisms fail, Mercurial will fail, printing an |
jerojasro@343 | 403 error message. In this case, it will not let you commit until you set |
jerojasro@343 | 404 up a username. |
jerojasro@343 | 405 |
jerojasro@343 | 406 You should think of the \envar{HGUSER} environment variable and the |
jerojasro@343 | 407 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to |
jerojasro@343 | 408 \emph{override} Mercurial's default selection of username. For normal |
jerojasro@343 | 409 use, the simplest and most robust way to set a username for yourself |
jerojasro@343 | 410 is by creating a \sfilename{.hgrc} file; see below for details. |
jerojasro@343 | 411 |
jerojasro@343 | 412 \subsubsection{Creating a Mercurial configuration file} |
jerojasro@343 | 413 \label{sec:tour-basic:username} |
jerojasro@343 | 414 |
jerojasro@343 | 415 To set a user name, use your favourite editor to create a file called |
jerojasro@343 | 416 \sfilename{.hgrc} in your home directory. Mercurial will use this |
jerojasro@343 | 417 file to look up your personalised configuration settings. The initial |
jerojasro@343 | 418 contents of your \sfilename{.hgrc} should look like this. |
jerojasro@343 | 419 \begin{codesample2} |
jerojasro@343 | 420 # This is a Mercurial configuration file. |
jerojasro@343 | 421 [ui] |
jerojasro@343 | 422 username = Firstname Lastname <email.address@domain.net> |
jerojasro@343 | 423 \end{codesample2} |
jerojasro@343 | 424 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file, |
jerojasro@343 | 425 so you can read the ``\texttt{username = ...}'' line as meaning ``set |
jerojasro@343 | 426 the value of the \texttt{username} item in the \texttt{ui} section''. |
jerojasro@343 | 427 A section continues until a new section begins, or the end of the |
jerojasro@343 | 428 file. Mercurial ignores empty lines and treats any text from |
jerojasro@343 | 429 ``\texttt{\#}'' to the end of a line as a comment. |
jerojasro@343 | 430 |
jerojasro@343 | 431 \subsubsection{Choosing a user name} |
jerojasro@343 | 432 |
jerojasro@343 | 433 You can use any text you like as the value of the \texttt{username} |
jerojasro@343 | 434 config item, since this information is for reading by other people, |
jerojasro@343 | 435 but for interpreting by Mercurial. The convention that most people |
jerojasro@343 | 436 follow is to use their name and email address, as in the example |
jerojasro@343 | 437 above. |
jerojasro@343 | 438 |
jerojasro@343 | 439 \begin{note} |
jerojasro@343 | 440 Mercurial's built-in web server obfuscates email addresses, to make |
jerojasro@343 | 441 it more difficult for the email harvesting tools that spammers use. |
jerojasro@343 | 442 This reduces the likelihood that you'll start receiving more junk |
jerojasro@343 | 443 email if you publish a Mercurial repository on the web. |
jerojasro@343 | 444 \end{note} |
jerojasro@343 | 445 |
jerojasro@343 | 446 \subsection{Writing a commit message} |
jerojasro@343 | 447 |
jerojasro@343 | 448 When we commit a change, Mercurial drops us into a text editor, to |
jerojasro@343 | 449 enter a message that will describe the modifications we've made in |
jerojasro@343 | 450 this changeset. This is called the \emph{commit message}. It will be |
jerojasro@343 | 451 a record for readers of what we did and why, and it will be printed by |
jerojasro@343 | 452 \hgcmd{log} after we've finished committing. |
jerojasro@343 | 453 \interaction{tour.commit} |
jerojasro@343 | 454 |
jerojasro@343 | 455 The editor that the \hgcmd{commit} command drops us into will contain |
jerojasro@343 | 456 an empty line, followed by a number of lines starting with |
jerojasro@343 | 457 ``\texttt{HG:}''. |
jerojasro@343 | 458 \begin{codesample2} |
jerojasro@343 | 459 \emph{empty line} |
jerojasro@343 | 460 HG: changed hello.c |
jerojasro@343 | 461 \end{codesample2} |
jerojasro@343 | 462 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses |
jerojasro@343 | 463 them only to tell us which files it's recording changes to. Modifying |
jerojasro@343 | 464 or deleting these lines has no effect. |
jerojasro@343 | 465 |
jerojasro@343 | 466 \subsection{Writing a good commit message} |
jerojasro@343 | 467 |
jerojasro@343 | 468 Since \hgcmd{log} only prints the first line of a commit message by |
jerojasro@343 | 469 default, it's best to write a commit message whose first line stands |
jerojasro@343 | 470 alone. Here's a real example of a commit message that \emph{doesn't} |
jerojasro@343 | 471 follow this guideline, and hence has a summary that is not readable. |
jerojasro@343 | 472 \begin{codesample2} |
jerojasro@343 | 473 changeset: 73:584af0e231be |
jerojasro@343 | 474 user: Censored Person <censored.person@example.org> |
jerojasro@343 | 475 date: Tue Sep 26 21:37:07 2006 -0700 |
jerojasro@343 | 476 summary: include buildmeister/commondefs. Add an exports and install |
jerojasro@343 | 477 \end{codesample2} |
jerojasro@343 | 478 |
jerojasro@343 | 479 As far as the remainder of the contents of the commit message are |
jerojasro@343 | 480 concerned, there are no hard-and-fast rules. Mercurial itself doesn't |
jerojasro@343 | 481 interpret or care about the contents of the commit message, though |
jerojasro@343 | 482 your project may have policies that dictate a certain kind of |
jerojasro@343 | 483 formatting. |
jerojasro@343 | 484 |
jerojasro@343 | 485 My personal preference is for short, but informative, commit messages |
jerojasro@343 | 486 that tell me something that I can't figure out with a quick glance at |
jerojasro@343 | 487 the output of \hgcmdargs{log}{--patch}. |
jerojasro@343 | 488 |
jerojasro@343 | 489 \subsection{Aborting a commit} |
jerojasro@343 | 490 |
jerojasro@343 | 491 If you decide that you don't want to commit while in the middle of |
jerojasro@343 | 492 editing a commit message, simply exit from your editor without saving |
jerojasro@343 | 493 the file that it's editing. This will cause nothing to happen to |
jerojasro@343 | 494 either the repository or the working directory. |
jerojasro@343 | 495 |
jerojasro@343 | 496 If we run the \hgcmd{commit} command without any arguments, it records |
jerojasro@343 | 497 all of the changes we've made, as reported by \hgcmd{status} and |
jerojasro@343 | 498 \hgcmd{diff}. |
jerojasro@343 | 499 |
jerojasro@343 | 500 \subsection{Admiring our new handiwork} |
jerojasro@343 | 501 |
jerojasro@343 | 502 Once we've finished the commit, we can use the \hgcmd{tip} command to |
jerojasro@343 | 503 display the changeset we just created. This command produces output |
jerojasro@343 | 504 that is identical to \hgcmd{log}, but it only displays the newest |
jerojasro@343 | 505 revision in the repository. |
jerojasro@343 | 506 \interaction{tour.tip} |
jerojasro@343 | 507 We refer to the newest revision in the repository as the tip revision, |
jerojasro@343 | 508 or simply the tip. |
jerojasro@343 | 509 |
jerojasro@343 | 510 \section{Sharing changes} |
jerojasro@343 | 511 |
jerojasro@343 | 512 We mentioned earlier that repositories in Mercurial are |
jerojasro@343 | 513 self-contained. This means that the changeset we just created exists |
jerojasro@343 | 514 only in our \dirname{my-hello} repository. Let's look at a few ways |
jerojasro@343 | 515 that we can propagate this change into other repositories. |
jerojasro@343 | 516 |
jerojasro@343 | 517 \subsection{Pulling changes from another repository} |
jerojasro@343 | 518 \label{sec:tour:pull} |
jerojasro@343 | 519 |
jerojasro@343 | 520 To get started, let's clone our original \dirname{hello} repository, |
jerojasro@343 | 521 which does not contain the change we just committed. We'll call our |
jerojasro@343 | 522 temporary repository \dirname{hello-pull}. |
jerojasro@343 | 523 \interaction{tour.clone-pull} |
jerojasro@343 | 524 |
jerojasro@343 | 525 We'll use the \hgcmd{pull} command to bring changes from |
jerojasro@343 | 526 \dirname{my-hello} into \dirname{hello-pull}. However, blindly |
jerojasro@343 | 527 pulling unknown changes into a repository is a somewhat scary |
jerojasro@343 | 528 prospect. Mercurial provides the \hgcmd{incoming} command to tell us |
jerojasro@343 | 529 what changes the \hgcmd{pull} command \emph{would} pull into the |
jerojasro@343 | 530 repository, without actually pulling the changes in. |
jerojasro@343 | 531 \interaction{tour.incoming} |
jerojasro@343 | 532 (Of course, someone could cause more changesets to appear in the |
jerojasro@343 | 533 repository that we ran \hgcmd{incoming} in, before we get a chance to |
jerojasro@343 | 534 \hgcmd{pull} the changes, so that we could end up pulling changes that we |
jerojasro@343 | 535 didn't expect.) |
jerojasro@343 | 536 |
jerojasro@343 | 537 Bringing changes into a repository is a simple matter of running the |
jerojasro@343 | 538 \hgcmd{pull} command, and telling it which repository to pull from. |
jerojasro@343 | 539 \interaction{tour.pull} |
jerojasro@343 | 540 As you can see from the before-and-after output of \hgcmd{tip}, we |
jerojasro@343 | 541 have successfully pulled changes into our repository. There remains |
jerojasro@343 | 542 one step before we can see these changes in the working directory. |
jerojasro@343 | 543 |
jerojasro@343 | 544 \subsection{Updating the working directory} |
jerojasro@343 | 545 |
jerojasro@343 | 546 We have so far glossed over the relationship between a repository and |
jerojasro@343 | 547 its working directory. The \hgcmd{pull} command that we ran in |
jerojasro@343 | 548 section~\ref{sec:tour:pull} brought changes into the repository, but |
jerojasro@343 | 549 if we check, there's no sign of those changes in the working |
jerojasro@343 | 550 directory. This is because \hgcmd{pull} does not (by default) touch |
jerojasro@343 | 551 the working directory. Instead, we use the \hgcmd{update} command to |
jerojasro@343 | 552 do this. |
jerojasro@343 | 553 \interaction{tour.update} |
jerojasro@343 | 554 |
jerojasro@343 | 555 It might seem a bit strange that \hgcmd{pull} doesn't update the |
jerojasro@343 | 556 working directory automatically. There's actually a good reason for |
jerojasro@343 | 557 this: you can use \hgcmd{update} to update the working directory to |
jerojasro@343 | 558 the state it was in at \emph{any revision} in the history of the |
jerojasro@343 | 559 repository. If you had the working directory updated to an old |
jerojasro@343 | 560 revision---to hunt down the origin of a bug, say---and ran a |
jerojasro@343 | 561 \hgcmd{pull} which automatically updated the working directory to a |
jerojasro@343 | 562 new revision, you might not be terribly happy. |
jerojasro@343 | 563 |
jerojasro@343 | 564 However, since pull-then-update is such a common thing to do, |
jerojasro@343 | 565 Mercurial lets you combine the two by passing the \hgopt{pull}{-u} |
jerojasro@343 | 566 option to \hgcmd{pull}. |
jerojasro@343 | 567 \begin{codesample2} |
jerojasro@343 | 568 hg pull -u |
jerojasro@343 | 569 \end{codesample2} |
jerojasro@343 | 570 If you look back at the output of \hgcmd{pull} in |
jerojasro@343 | 571 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u}, |
jerojasro@343 | 572 you can see that it printed a helpful reminder that we'd have to take |
jerojasro@343 | 573 an explicit step to update the working directory: |
jerojasro@343 | 574 \begin{codesample2} |
jerojasro@343 | 575 (run 'hg update' to get a working copy) |
jerojasro@343 | 576 \end{codesample2} |
jerojasro@343 | 577 |
jerojasro@343 | 578 To find out what revision the working directory is at, use the |
jerojasro@343 | 579 \hgcmd{parents} command. |
jerojasro@343 | 580 \interaction{tour.parents} |
jerojasro@343 | 581 If you look back at figure~\ref{fig:tour-basic:history}, you'll see |
jerojasro@343 | 582 arrows connecting each changeset. The node that the arrow leads |
jerojasro@343 | 583 \emph{from} in each case is a parent, and the node that the arrow |
jerojasro@343 | 584 leads \emph{to} is its child. The working directory has a parent in |
jerojasro@343 | 585 just the same way; this is the changeset that the working directory |
jerojasro@343 | 586 currently contains. |
jerojasro@343 | 587 |
jerojasro@343 | 588 To update the working directory to a particular revision, give a |
jerojasro@343 | 589 revision number or changeset~ID to the \hgcmd{update} command. |
jerojasro@343 | 590 \interaction{tour.older} |
jerojasro@343 | 591 If you omit an explicit revision, \hgcmd{update} will update to the |
jerojasro@343 | 592 tip revision, as shown by the second call to \hgcmd{update} in the |
jerojasro@343 | 593 example above. |
jerojasro@343 | 594 |
jerojasro@343 | 595 \subsection{Pushing changes to another repository} |
jerojasro@343 | 596 |
jerojasro@343 | 597 Mercurial lets us push changes to another repository, from the |
jerojasro@343 | 598 repository we're currently visiting. As with the example of |
jerojasro@343 | 599 \hgcmd{pull} above, we'll create a temporary repository to push our |
jerojasro@343 | 600 changes into. |
jerojasro@343 | 601 \interaction{tour.clone-push} |
jerojasro@343 | 602 The \hgcmd{outgoing} command tells us what changes would be pushed |
jerojasro@343 | 603 into another repository. |
jerojasro@343 | 604 \interaction{tour.outgoing} |
jerojasro@343 | 605 And the \hgcmd{push} command does the actual push. |
jerojasro@343 | 606 \interaction{tour.push} |
jerojasro@343 | 607 As with \hgcmd{pull}, the \hgcmd{push} command does not update the |
jerojasro@343 | 608 working directory in the repository that it's pushing changes into. |
jerojasro@343 | 609 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u} |
jerojasro@343 | 610 option that updates the other repository's working directory.) |
jerojasro@343 | 611 |
jerojasro@343 | 612 What happens if we try to pull or push changes and the receiving |
jerojasro@343 | 613 repository already has those changes? Nothing too exciting. |
jerojasro@343 | 614 \interaction{tour.push.nothing} |
jerojasro@343 | 615 |
jerojasro@343 | 616 \subsection{Sharing changes over a network} |
jerojasro@343 | 617 |
jerojasro@343 | 618 The commands we have covered in the previous few sections are not |
jerojasro@343 | 619 limited to working with local repositories. Each works in exactly the |
jerojasro@343 | 620 same fashion over a network connection; simply pass in a URL instead |
jerojasro@343 | 621 of a local path. |
jerojasro@343 | 622 \interaction{tour.outgoing.net} |
jerojasro@343 | 623 In this example, we can see what changes we could push to the remote |
jerojasro@343 | 624 repository, but the repository is understandably not set up to let |
jerojasro@343 | 625 anonymous users push to it. |
jerojasro@343 | 626 \interaction{tour.push.net} |
jerojasro@343 | 627 |
jerojasro@343 | 628 %%% Local Variables: |
jerojasro@343 | 629 %%% mode: latex |
jerojasro@343 | 630 %%% TeX-master: "00book" |
jerojasro@343 | 631 %%% End: |