hgbook

annotate es/tour-basic.tex @ 362:90b67ac5862b

find changesets by author, revision, files, or words in the commit message
translated up to section 1.4.1
author Javier Rojas <jerojasro@devnull.li>
date Sat Oct 25 15:01:39 2008 -0500 (2008-10-25)
parents 15a6b61335aa
children e8a5068c7605
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@352 118 \section{Trabajar con un repositorio}
jerojasro@352 119
jerojasro@352 120 En Mercurial, todo sucede dentro de un \emph{repositorio}. El
jerojasro@362 121 repositorio para un proyecto contiene todos los ficheros que
jerojasro@352 122 ``pertenecen a'' ése proyecto, junto con un registro histórico de los
jerojasro@362 123 ficheros de ese proyecto.
jerojasro@352 124
jerojasro@352 125 No hay nada particularmente mágico acerca de un repositorio; es
jerojasro@362 126 simplemente un árbol de directorios en su sistema de ficheros que
jerojasro@352 127 Mercurial trata como especial. Usted puede renombrar o borrar un
jerojasro@352 128 repositorio en el momento que lo desee, usando bien sea la línea de
jerojasro@352 129 comandos o su explorador de ficheros.
jerojasro@352 130
jerojasro@352 131 \subsection{Hacer una copia local de un repositorio}
jerojasro@352 132
jerojasro@352 133 \emph{Copiar} un repositorio es sólo ligeramente especial. Aunque
jerojasro@362 134 usted podría usar un programa normal de copia de ficheros para hacer
jerojasro@352 135 una copia del repositorio, es mejor usar el comando integrado que
jerojasro@352 136 Mercurial ofrece. Este comando se llama \hgcmd{clone}\ndt{Del término
jerojasro@352 137 ``clonar'' en inglés.}, porque crea una copia idéntica de un
jerojasro@352 138 repositorio existente.
jerojasro@343 139 \interaction{tour.clone}
jerojasro@352 140 Si nuestro clonado tiene éxito, deberíamos tener un directorio local
jerojasro@362 141 llamado \dirname{hello}. Este directorio contendrá algunos ficheros.
jerojasro@343 142 \interaction{tour.ls}
jerojasro@362 143 Estos ficheros tienen el mismo contenido e historial en nuestro
jerojasro@352 144 repositorio y en el repositorio que clonamos.
jerojasro@352 145
jerojasro@352 146 Cada repositorio Mercurial está completo, es autocontenido e
jerojasro@362 147 independiente. Contiene su propia copia de los ficheros y la historia
jerojasro@352 148 de un proyecto. Un repositorio clonado recuerda la ubicación de la que
jerojasro@352 149 fue clonado, pero no se comunica con ese repositorio, ni con ningún
jerojasro@352 150 otro, a menos que usted le indique que lo haga.
jerojasro@352 151
jerojasro@352 152 Lo que esto significa por ahora es que somos libres de experimentar
jerojasro@355 153 con nuestro repositorio, con la tranquilidad de saber que es una
jerojasro@355 154 % TODO figure out what to say instead of sandbox
jerojasro@355 155 ``caja de arena'' privada que no afectará a nadie más.
jerojasro@355 156
jerojasro@355 157 \subsection{Qué hay en un repositorio?}
jerojasro@355 158
jerojasro@355 159 Cuando miramos en detalle dentro de un repositorio, podemos ver que
jerojasro@355 160 contiene un directorio llamado \dirname{.hg}. Aquí es donde Mercurial
jerojasro@355 161 mantiene todos los metadatos del repositorio.
jerojasro@343 162 \interaction{tour.ls-a}
jerojasro@343 163
jerojasro@355 164 Los contenidos del directorio \dirname{.hg} y sus subdirectorios son
jerojasro@355 165 exclusivos de Mercurial. Usted es libre de hacer lo que desee con
jerojasro@362 166 cualquier otro fichero o directorio en el repositorio.
jerojasro@343 167
jerojasro@357 168 Para introducir algo de terminología, el directorio \dirname{.hg} es
jerojasro@362 169 el repositorio ``real'', y todos los ficheros y directorios que
jerojasro@357 170 coexisten con él están en el \emph{directorio de trabajo}. Una forma
jerojasro@357 171 sencilla de recordar esta distinción es que el \emph{repositorio}
jerojasro@357 172 % TODO unificar con Igor, si historia o historial
jerojasro@357 173 contiene el \emph{historial} de su proyecto, mientras que el
jerojasro@357 174 \emph{directorio de trabajo} contiene una \emph{instantánea} de su
jerojasro@357 175 proyecto en un punto particular del historial.
jerojasro@357 176
jerojasro@357 177 \section{Vistazo rápido al historial}
jerojasro@357 178
jerojasro@357 179 Una de las primeras cosas que se desea hacer con un repositorio nuevo,
jerojasro@357 180 poco conocido, es conocer su historial. el comando \hgcmd{log} nos
jerojasro@357 181 permite ver el mismo.
jerojasro@343 182 \interaction{tour.log}
jerojasro@358 183 Por defecto este programa imprime un párrafo breve por cada cambio al
jerojasro@358 184 proyecto que haya sido grabado. Dentro de la terminología de
jerojasro@358 185 Mercurial, cada uno de estos eventos es llamado \emph{conjuntos de
jerojasro@358 186 cambios}, porque pueden contener un registro de cambios a varios
jerojasro@362 187 ficheros.
jerojasro@358 188
jerojasro@358 189 Los campos de la salida de \hgcmd{log} son los siguientes.
jerojasro@343 190 \begin{itemize}
jerojasro@358 191 \item[\texttt{changeset}]\hspace{-0.5em}\ndt{Conjunto de cambios.} Este campo
jerojasro@358 192 tiene un número, seguido por un
jerojasro@358 193 % TODO digo mejor seguido por un dos puntos ? string =>
jerojasro@358 194 % cadena?
jerojasro@358 195 \texttt{:}, seguido por una cadena hexadecimal. Ambos son
jerojasro@358 196 \emph{identificadores} para el conjunto de cambios. Hay dos
jerojasro@358 197 identificadores porque el número es más corto y más fácil de
jerojasro@358 198 recordar que la cadena hexadecimal.
jerojasro@358 199
jerojasro@358 200 \item[\texttt{user}]\hspace{-0.5em}\ndt{Usuario.} La identidad de la
jerojasro@358 201 persona que creó el conjunto de cambios. Este es un campo en el
jerojasro@358 202 que se puede almacenar cualquier valor, pero en la mayoría de los
jerojasro@358 203 casos contiene el nombre de una persona y su dirección de correo
jerojasro@358 204 electrónico.
jerojasro@358 205
jerojasro@362 206 \item[\texttt{date}]\hspace{-0.5em}\ndt{Fecha.} La fecha y hora en la
jerojasro@362 207 que el conjunto de cambios fue creado, y la zona horaria en la que
jerojasro@362 208 fue creado. (La fecha y hora son locales a dicha zona horaria;
jerojasro@362 209 ambos muestran la fecha y hora para la persona que creó el
jerojasro@362 210 changeset).
jerojasro@362 211
jerojasro@362 212 \item[\texttt{summary}]\hspace{-0.5em}\ndt{Sumario.}
jerojasro@362 213 La primera línea del texto que usó la persona que creó el conjunto
jerojasro@362 214 de cambios para describir el mismo.
jerojasro@343 215 \end{itemize}
jerojasro@362 216 El texto impreso por \hgcmd{log} es sólo un sumario; omite una gran
jerojasro@362 217 cantidad de detalles.
jerojasro@362 218
jerojasro@362 219 La figura~\ref{fig:tour-basic:history} es una representación
jerojasro@362 220 gráfica del historial del repositorio \dirname{hello}, para hacer más
jerojasro@362 221 fácil ver en qué dirección está ``fluyendo'' el historial. Volveremos
jerojasro@362 222 a esto varias veces en este capítulo y en los siguientes.
jerojasro@343 223
jerojasro@343 224 \begin{figure}[ht]
jerojasro@343 225 \centering
jerojasro@343 226 \grafix{tour-history}
jerojasro@362 227 \caption{Historial gráfico de el repositorio \dirname{hello}}
jerojasro@343 228 \label{fig:tour-basic:history}
jerojasro@343 229 \end{figure}
jerojasro@343 230
jerojasro@362 231 \subsection{Conjuntos de cambios, revisiones, y comunicándose con
jerojasro@362 232 otras personas}
jerojasro@362 233
jerojasro@362 234 %TODO sloppy => desordenado ? TODO hablar del inglés? o de español?
jerojasro@362 235 Ya que el inglés es un lenguaje notablemente desordenado, y el área de
jerojasro@362 236 ciencias de la computación tiene una notable historia de confusión de
jerojasro@362 237 % TODO insertar ? al revés. no sé cómo en un teclado de estos.
jerojasro@362 238 términos (porqué usar sólo un término cuando cuatro pueden servir?),
jerojasro@362 239 el control de revisiones tiene una variedad de frases y palabras que
jerojasro@362 240 tienen el mismo significado. Si usted habla acerca del historial de
jerojasro@362 241 Mercurial con alguien, encontrará que la expresión ``conjunto de
jerojasro@362 242 cambios'' es abreviada a menudo como ``cambio'' o (por escrito)
jerojasro@362 243 ``cset''\ndt{Abreviatura para la expresión ``changeset'' en inglés.},
jerojasro@362 244 y algunas veces un se hace referencia a un conjunto de cambios como
jerojasro@362 245 una ``revisión'' o ``rev''\ndt{De nuevo, como abreviación para el
jerojasro@362 246 término en inglés para ``revisión'' (``revision'').}.
jerojasro@362 247
jerojasro@362 248 Si bien no es relevante qué \emph{palabra} use usted para referirse al
jerojasro@362 249 concepto ``conjunto de cambios'', el \emph{identificador} que usted
jerojasro@362 250 use para referise a ``un \emph{conjunto de cambios} particular'' es
jerojasro@362 251 muy importante. Recuerde que el campo \texttt{changeset} en la salida
jerojasro@362 252 de \hgcmd{log} identifica un conjunto de cambios usando tanto un
jerojasro@362 253 número como una cadena hexadecimal.
jerojasro@362 254
jerojasro@343 255 \begin{itemize}
jerojasro@362 256 \item El número de revisión \emph{sólo es válido dentro del
jerojasro@362 257 repositorio}.
jerojasro@362 258 \item Por otro lado, la cadena hexadecimal es el
jerojasro@362 259 \emph{identificador permanente e inmutable} que siempre
jerojasro@362 260 identificará ése conjunto de cambios en \emph{todas} las
jerojasro@362 261 copias del repositorio.
jerojasro@343 262 \end{itemize}
jerojasro@362 263 La diferencia es importante. Si usted le envía a alguien un correo
jerojasro@362 264 electrónico hablando acerca de la ``revisión~33'', hay una
jerojasro@362 265 probabilidad alta de que la revisión~33 de esa persona \emph{no sea la
jerojasro@362 266 misma suya}. Esto sucede porque el número de revisión depende de el
jerojasro@362 267 orden en que llegan los cambios al repositorio, y no hay ninguna
jerojasro@362 268 garantía de que los mismos cambios llegarán en el mismo orden en
jerojasro@362 269 diferentes repositorios. Tres cambios dados $a,b,c$ pueden aparecer en
jerojasro@362 270 un repositorio como $0,1,2$, mientras que en otro aparecen como
jerojasro@362 271 $1,0,2$.
jerojasro@362 272
jerojasro@362 273 Mercurial usa los números de revisión simplemente como una abreviación
jerojasro@362 274 conveniente. Si usted necesita hablar con alguien acerca de un
jerojasro@362 275 conjunto de cambios, o llevar el registro de un conjunto de cambios
jerojasro@362 276 por alguna otra razón (por ejemplo, en un reporte de fallo), use el
jerojasro@362 277 identificador hexadecimal.
jerojasro@343 278
jerojasro@343 279 \subsection{Viewing specific revisions}
jerojasro@343 280
jerojasro@343 281 To narrow the output of \hgcmd{log} down to a single revision, use the
jerojasro@343 282 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a
jerojasro@343 283 revision number or a long-form changeset identifier, and you can
jerojasro@343 284 provide as many revisions as you want. \interaction{tour.log-r}
jerojasro@343 285
jerojasro@343 286 If you want to see the history of several revisions without having to
jerojasro@343 287 list each one, you can use \emph{range notation}; this lets you
jerojasro@343 288 express the idea ``I want all revisions between $a$ and $b$,
jerojasro@343 289 inclusive''.
jerojasro@343 290 \interaction{tour.log.range}
jerojasro@343 291 Mercurial also honours the order in which you specify revisions, so
jerojasro@343 292 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
jerojasro@343 293 prints $4,3,2$.
jerojasro@343 294
jerojasro@343 295 \subsection{More detailed information}
jerojasro@343 296
jerojasro@343 297 While the summary information printed by \hgcmd{log} is useful if you
jerojasro@343 298 already know what you're looking for, you may need to see a complete
jerojasro@343 299 description of the change, or a list of the files changed, if you're
jerojasro@343 300 trying to decide whether a changeset is the one you're looking for.
jerojasro@343 301 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
jerojasro@343 302 option gives you this extra detail.
jerojasro@343 303 \interaction{tour.log-v}
jerojasro@343 304
jerojasro@343 305 If you want to see both the description and content of a change, add
jerojasro@343 306 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
jerojasro@343 307 the content of a change as a \emph{unified diff} (if you've never seen
jerojasro@343 308 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
jerojasro@343 309 \interaction{tour.log-vp}
jerojasro@343 310
jerojasro@343 311 \section{All about command options}
jerojasro@343 312
jerojasro@343 313 Let's take a brief break from exploring Mercurial commands to discuss
jerojasro@343 314 a pattern in the way that they work; you may find this useful to keep
jerojasro@343 315 in mind as we continue our tour.
jerojasro@343 316
jerojasro@343 317 Mercurial has a consistent and straightforward approach to dealing
jerojasro@343 318 with the options that you can pass to commands. It follows the
jerojasro@343 319 conventions for options that are common to modern Linux and Unix
jerojasro@343 320 systems.
jerojasro@343 321 \begin{itemize}
jerojasro@343 322 \item Every option has a long name. For example, as we've already
jerojasro@343 323 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
jerojasro@343 324 \item Most options have short names, too. Instead of
jerojasro@343 325 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
jerojasro@343 326 some options don't have short names is that the options in question
jerojasro@343 327 are rarely used.)
jerojasro@343 328 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
jerojasro@343 329 while short options start with one (e.g.~\hgopt{log}{-r}).
jerojasro@343 330 \item Option naming and usage is consistent across commands. For
jerojasro@343 331 example, every command that lets you specify a changeset~ID or
jerojasro@343 332 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
jerojasro@343 333 arguments.
jerojasro@343 334 \end{itemize}
jerojasro@343 335 In the examples throughout this book, I use short options instead of
jerojasro@343 336 long. This just reflects my own preference, so don't read anything
jerojasro@343 337 significant into it.
jerojasro@343 338
jerojasro@343 339 Most commands that print output of some kind will print more output
jerojasro@343 340 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
jerojasro@343 341 when passed \hggopt{-q} (or \hggopt{--quiet}).
jerojasro@343 342
jerojasro@343 343 \section{Making and reviewing changes}
jerojasro@343 344
jerojasro@343 345 Now that we have a grasp of viewing history in Mercurial, let's take a
jerojasro@343 346 look at making some changes and examining them.
jerojasro@343 347
jerojasro@343 348 The first thing we'll do is isolate our experiment in a repository of
jerojasro@343 349 its own. We use the \hgcmd{clone} command, but we don't need to
jerojasro@343 350 clone a copy of the remote repository. Since we already have a copy
jerojasro@343 351 of it locally, we can just clone that instead. This is much faster
jerojasro@343 352 than cloning over the network, and cloning a local repository uses
jerojasro@343 353 less disk space in most cases, too.
jerojasro@343 354 \interaction{tour.reclone}
jerojasro@343 355 As an aside, it's often good practice to keep a ``pristine'' copy of a
jerojasro@343 356 remote repository around, which you can then make temporary clones of
jerojasro@343 357 to create sandboxes for each task you want to work on. This lets you
jerojasro@343 358 work on multiple tasks in parallel, each isolated from the others
jerojasro@343 359 until it's complete and you're ready to integrate it back. Because
jerojasro@343 360 local clones are so cheap, there's almost no overhead to cloning and
jerojasro@343 361 destroying repositories whenever you want.
jerojasro@343 362
jerojasro@343 363 In our \dirname{my-hello} repository, we have a file
jerojasro@343 364 \filename{hello.c} that contains the classic ``hello, world'' program.
jerojasro@343 365 Let's use the ancient and venerable \command{sed} command to edit this
jerojasro@343 366 file so that it prints a second line of output. (I'm only using
jerojasro@343 367 \command{sed} to do this because it's easy to write a scripted example
jerojasro@343 368 this way. Since you're not under the same constraint, you probably
jerojasro@343 369 won't want to use \command{sed}; simply use your preferred text editor to
jerojasro@343 370 do the same thing.)
jerojasro@343 371 \interaction{tour.sed}
jerojasro@343 372
jerojasro@343 373 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
jerojasro@343 374 about the files in the repository.
jerojasro@343 375 \interaction{tour.status}
jerojasro@343 376 The \hgcmd{status} command prints no output for some files, but a line
jerojasro@343 377 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
jerojasro@343 378 it to, \hgcmd{status} will not print any output for files that have
jerojasro@343 379 not been modified.
jerojasro@343 380
jerojasro@343 381 The ``\texttt{M}'' indicates that Mercurial has noticed that we
jerojasro@343 382 modified \filename{hello.c}. We didn't need to \emph{inform}
jerojasro@343 383 Mercurial that we were going to modify the file before we started, or
jerojasro@343 384 that we had modified the file after we were done; it was able to
jerojasro@343 385 figure this out itself.
jerojasro@343 386
jerojasro@343 387 It's a little bit helpful to know that we've modified
jerojasro@343 388 \filename{hello.c}, but we might prefer to know exactly \emph{what}
jerojasro@343 389 changes we've made to it. To do this, we use the \hgcmd{diff}
jerojasro@343 390 command.
jerojasro@343 391 \interaction{tour.diff}
jerojasro@343 392
jerojasro@343 393 \section{Recording changes in a new changeset}
jerojasro@343 394
jerojasro@343 395 We can modify files, build and test our changes, and use
jerojasro@343 396 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
jerojasro@343 397 satisfied with what we've done and arrive at a natural stopping point
jerojasro@343 398 where we want to record our work in a new changeset.
jerojasro@343 399
jerojasro@343 400 The \hgcmd{commit} command lets us create a new changeset; we'll
jerojasro@343 401 usually refer to this as ``making a commit'' or ``committing''.
jerojasro@343 402
jerojasro@343 403 \subsection{Setting up a username}
jerojasro@343 404
jerojasro@343 405 When you try to run \hgcmd{commit} for the first time, it is not
jerojasro@343 406 guaranteed to succeed. Mercurial records your name and address with
jerojasro@343 407 each change that you commit, so that you and others will later be able
jerojasro@343 408 to tell who made each change. Mercurial tries to automatically figure
jerojasro@343 409 out a sensible username to commit the change with. It will attempt
jerojasro@343 410 each of the following methods, in order:
jerojasro@343 411 \begin{enumerate}
jerojasro@343 412 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
jerojasro@343 413 command on the command line, followed by a username, this is always
jerojasro@343 414 given the highest precedence.
jerojasro@343 415 \item If you have set the \envar{HGUSER} environment variable, this is
jerojasro@343 416 checked next.
jerojasro@343 417 \item If you create a file in your home directory called
jerojasro@343 418 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
jerojasro@343 419 used next. To see what the contents of this file should look like,
jerojasro@343 420 refer to section~\ref{sec:tour-basic:username} below.
jerojasro@343 421 \item If you have set the \envar{EMAIL} environment variable, this
jerojasro@343 422 will be used next.
jerojasro@343 423 \item Mercurial will query your system to find out your local user
jerojasro@343 424 name and host name, and construct a username from these components.
jerojasro@343 425 Since this often results in a username that is not very useful, it
jerojasro@343 426 will print a warning if it has to do this.
jerojasro@343 427 \end{enumerate}
jerojasro@343 428 If all of these mechanisms fail, Mercurial will fail, printing an
jerojasro@343 429 error message. In this case, it will not let you commit until you set
jerojasro@343 430 up a username.
jerojasro@343 431
jerojasro@343 432 You should think of the \envar{HGUSER} environment variable and the
jerojasro@343 433 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
jerojasro@343 434 \emph{override} Mercurial's default selection of username. For normal
jerojasro@343 435 use, the simplest and most robust way to set a username for yourself
jerojasro@343 436 is by creating a \sfilename{.hgrc} file; see below for details.
jerojasro@343 437
jerojasro@343 438 \subsubsection{Creating a Mercurial configuration file}
jerojasro@343 439 \label{sec:tour-basic:username}
jerojasro@343 440
jerojasro@343 441 To set a user name, use your favourite editor to create a file called
jerojasro@343 442 \sfilename{.hgrc} in your home directory. Mercurial will use this
jerojasro@343 443 file to look up your personalised configuration settings. The initial
jerojasro@343 444 contents of your \sfilename{.hgrc} should look like this.
jerojasro@343 445 \begin{codesample2}
jerojasro@343 446 # This is a Mercurial configuration file.
jerojasro@343 447 [ui]
jerojasro@343 448 username = Firstname Lastname <email.address@domain.net>
jerojasro@343 449 \end{codesample2}
jerojasro@343 450 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
jerojasro@343 451 so you can read the ``\texttt{username = ...}'' line as meaning ``set
jerojasro@343 452 the value of the \texttt{username} item in the \texttt{ui} section''.
jerojasro@343 453 A section continues until a new section begins, or the end of the
jerojasro@343 454 file. Mercurial ignores empty lines and treats any text from
jerojasro@343 455 ``\texttt{\#}'' to the end of a line as a comment.
jerojasro@343 456
jerojasro@343 457 \subsubsection{Choosing a user name}
jerojasro@343 458
jerojasro@343 459 You can use any text you like as the value of the \texttt{username}
jerojasro@343 460 config item, since this information is for reading by other people,
jerojasro@343 461 but for interpreting by Mercurial. The convention that most people
jerojasro@343 462 follow is to use their name and email address, as in the example
jerojasro@343 463 above.
jerojasro@343 464
jerojasro@343 465 \begin{note}
jerojasro@343 466 Mercurial's built-in web server obfuscates email addresses, to make
jerojasro@343 467 it more difficult for the email harvesting tools that spammers use.
jerojasro@343 468 This reduces the likelihood that you'll start receiving more junk
jerojasro@343 469 email if you publish a Mercurial repository on the web.
jerojasro@343 470 \end{note}
jerojasro@343 471
jerojasro@343 472 \subsection{Writing a commit message}
jerojasro@343 473
jerojasro@343 474 When we commit a change, Mercurial drops us into a text editor, to
jerojasro@343 475 enter a message that will describe the modifications we've made in
jerojasro@343 476 this changeset. This is called the \emph{commit message}. It will be
jerojasro@343 477 a record for readers of what we did and why, and it will be printed by
jerojasro@343 478 \hgcmd{log} after we've finished committing.
jerojasro@343 479 \interaction{tour.commit}
jerojasro@343 480
jerojasro@343 481 The editor that the \hgcmd{commit} command drops us into will contain
jerojasro@343 482 an empty line, followed by a number of lines starting with
jerojasro@343 483 ``\texttt{HG:}''.
jerojasro@343 484 \begin{codesample2}
jerojasro@343 485 \emph{empty line}
jerojasro@343 486 HG: changed hello.c
jerojasro@343 487 \end{codesample2}
jerojasro@343 488 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
jerojasro@343 489 them only to tell us which files it's recording changes to. Modifying
jerojasro@343 490 or deleting these lines has no effect.
jerojasro@343 491
jerojasro@343 492 \subsection{Writing a good commit message}
jerojasro@343 493
jerojasro@343 494 Since \hgcmd{log} only prints the first line of a commit message by
jerojasro@343 495 default, it's best to write a commit message whose first line stands
jerojasro@343 496 alone. Here's a real example of a commit message that \emph{doesn't}
jerojasro@343 497 follow this guideline, and hence has a summary that is not readable.
jerojasro@343 498 \begin{codesample2}
jerojasro@343 499 changeset: 73:584af0e231be
jerojasro@343 500 user: Censored Person <censored.person@example.org>
jerojasro@343 501 date: Tue Sep 26 21:37:07 2006 -0700
jerojasro@343 502 summary: include buildmeister/commondefs. Add an exports and install
jerojasro@343 503 \end{codesample2}
jerojasro@343 504
jerojasro@343 505 As far as the remainder of the contents of the commit message are
jerojasro@343 506 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
jerojasro@343 507 interpret or care about the contents of the commit message, though
jerojasro@343 508 your project may have policies that dictate a certain kind of
jerojasro@343 509 formatting.
jerojasro@343 510
jerojasro@343 511 My personal preference is for short, but informative, commit messages
jerojasro@343 512 that tell me something that I can't figure out with a quick glance at
jerojasro@343 513 the output of \hgcmdargs{log}{--patch}.
jerojasro@343 514
jerojasro@343 515 \subsection{Aborting a commit}
jerojasro@343 516
jerojasro@343 517 If you decide that you don't want to commit while in the middle of
jerojasro@343 518 editing a commit message, simply exit from your editor without saving
jerojasro@343 519 the file that it's editing. This will cause nothing to happen to
jerojasro@343 520 either the repository or the working directory.
jerojasro@343 521
jerojasro@343 522 If we run the \hgcmd{commit} command without any arguments, it records
jerojasro@343 523 all of the changes we've made, as reported by \hgcmd{status} and
jerojasro@343 524 \hgcmd{diff}.
jerojasro@343 525
jerojasro@343 526 \subsection{Admiring our new handiwork}
jerojasro@343 527
jerojasro@343 528 Once we've finished the commit, we can use the \hgcmd{tip} command to
jerojasro@343 529 display the changeset we just created. This command produces output
jerojasro@343 530 that is identical to \hgcmd{log}, but it only displays the newest
jerojasro@343 531 revision in the repository.
jerojasro@343 532 \interaction{tour.tip}
jerojasro@343 533 We refer to the newest revision in the repository as the tip revision,
jerojasro@343 534 or simply the tip.
jerojasro@343 535
jerojasro@343 536 \section{Sharing changes}
jerojasro@343 537
jerojasro@343 538 We mentioned earlier that repositories in Mercurial are
jerojasro@343 539 self-contained. This means that the changeset we just created exists
jerojasro@343 540 only in our \dirname{my-hello} repository. Let's look at a few ways
jerojasro@343 541 that we can propagate this change into other repositories.
jerojasro@343 542
jerojasro@343 543 \subsection{Pulling changes from another repository}
jerojasro@343 544 \label{sec:tour:pull}
jerojasro@343 545
jerojasro@343 546 To get started, let's clone our original \dirname{hello} repository,
jerojasro@343 547 which does not contain the change we just committed. We'll call our
jerojasro@343 548 temporary repository \dirname{hello-pull}.
jerojasro@343 549 \interaction{tour.clone-pull}
jerojasro@343 550
jerojasro@343 551 We'll use the \hgcmd{pull} command to bring changes from
jerojasro@343 552 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
jerojasro@343 553 pulling unknown changes into a repository is a somewhat scary
jerojasro@343 554 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
jerojasro@343 555 what changes the \hgcmd{pull} command \emph{would} pull into the
jerojasro@343 556 repository, without actually pulling the changes in.
jerojasro@343 557 \interaction{tour.incoming}
jerojasro@343 558 (Of course, someone could cause more changesets to appear in the
jerojasro@343 559 repository that we ran \hgcmd{incoming} in, before we get a chance to
jerojasro@343 560 \hgcmd{pull} the changes, so that we could end up pulling changes that we
jerojasro@343 561 didn't expect.)
jerojasro@343 562
jerojasro@343 563 Bringing changes into a repository is a simple matter of running the
jerojasro@343 564 \hgcmd{pull} command, and telling it which repository to pull from.
jerojasro@343 565 \interaction{tour.pull}
jerojasro@343 566 As you can see from the before-and-after output of \hgcmd{tip}, we
jerojasro@343 567 have successfully pulled changes into our repository. There remains
jerojasro@343 568 one step before we can see these changes in the working directory.
jerojasro@343 569
jerojasro@343 570 \subsection{Updating the working directory}
jerojasro@343 571
jerojasro@343 572 We have so far glossed over the relationship between a repository and
jerojasro@343 573 its working directory. The \hgcmd{pull} command that we ran in
jerojasro@343 574 section~\ref{sec:tour:pull} brought changes into the repository, but
jerojasro@343 575 if we check, there's no sign of those changes in the working
jerojasro@343 576 directory. This is because \hgcmd{pull} does not (by default) touch
jerojasro@343 577 the working directory. Instead, we use the \hgcmd{update} command to
jerojasro@343 578 do this.
jerojasro@343 579 \interaction{tour.update}
jerojasro@343 580
jerojasro@343 581 It might seem a bit strange that \hgcmd{pull} doesn't update the
jerojasro@343 582 working directory automatically. There's actually a good reason for
jerojasro@343 583 this: you can use \hgcmd{update} to update the working directory to
jerojasro@343 584 the state it was in at \emph{any revision} in the history of the
jerojasro@343 585 repository. If you had the working directory updated to an old
jerojasro@343 586 revision---to hunt down the origin of a bug, say---and ran a
jerojasro@343 587 \hgcmd{pull} which automatically updated the working directory to a
jerojasro@343 588 new revision, you might not be terribly happy.
jerojasro@343 589
jerojasro@343 590 However, since pull-then-update is such a common thing to do,
jerojasro@343 591 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
jerojasro@343 592 option to \hgcmd{pull}.
jerojasro@343 593 \begin{codesample2}
jerojasro@343 594 hg pull -u
jerojasro@343 595 \end{codesample2}
jerojasro@343 596 If you look back at the output of \hgcmd{pull} in
jerojasro@343 597 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
jerojasro@343 598 you can see that it printed a helpful reminder that we'd have to take
jerojasro@343 599 an explicit step to update the working directory:
jerojasro@343 600 \begin{codesample2}
jerojasro@343 601 (run 'hg update' to get a working copy)
jerojasro@343 602 \end{codesample2}
jerojasro@343 603
jerojasro@343 604 To find out what revision the working directory is at, use the
jerojasro@343 605 \hgcmd{parents} command.
jerojasro@343 606 \interaction{tour.parents}
jerojasro@343 607 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
jerojasro@343 608 arrows connecting each changeset. The node that the arrow leads
jerojasro@343 609 \emph{from} in each case is a parent, and the node that the arrow
jerojasro@343 610 leads \emph{to} is its child. The working directory has a parent in
jerojasro@343 611 just the same way; this is the changeset that the working directory
jerojasro@343 612 currently contains.
jerojasro@343 613
jerojasro@343 614 To update the working directory to a particular revision, give a
jerojasro@343 615 revision number or changeset~ID to the \hgcmd{update} command.
jerojasro@343 616 \interaction{tour.older}
jerojasro@343 617 If you omit an explicit revision, \hgcmd{update} will update to the
jerojasro@343 618 tip revision, as shown by the second call to \hgcmd{update} in the
jerojasro@343 619 example above.
jerojasro@343 620
jerojasro@343 621 \subsection{Pushing changes to another repository}
jerojasro@343 622
jerojasro@343 623 Mercurial lets us push changes to another repository, from the
jerojasro@343 624 repository we're currently visiting. As with the example of
jerojasro@343 625 \hgcmd{pull} above, we'll create a temporary repository to push our
jerojasro@343 626 changes into.
jerojasro@343 627 \interaction{tour.clone-push}
jerojasro@343 628 The \hgcmd{outgoing} command tells us what changes would be pushed
jerojasro@343 629 into another repository.
jerojasro@343 630 \interaction{tour.outgoing}
jerojasro@343 631 And the \hgcmd{push} command does the actual push.
jerojasro@343 632 \interaction{tour.push}
jerojasro@343 633 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
jerojasro@343 634 working directory in the repository that it's pushing changes into.
jerojasro@343 635 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
jerojasro@343 636 option that updates the other repository's working directory.)
jerojasro@343 637
jerojasro@343 638 What happens if we try to pull or push changes and the receiving
jerojasro@343 639 repository already has those changes? Nothing too exciting.
jerojasro@343 640 \interaction{tour.push.nothing}
jerojasro@343 641
jerojasro@343 642 \subsection{Sharing changes over a network}
jerojasro@343 643
jerojasro@343 644 The commands we have covered in the previous few sections are not
jerojasro@343 645 limited to working with local repositories. Each works in exactly the
jerojasro@343 646 same fashion over a network connection; simply pass in a URL instead
jerojasro@343 647 of a local path.
jerojasro@343 648 \interaction{tour.outgoing.net}
jerojasro@343 649 In this example, we can see what changes we could push to the remote
jerojasro@343 650 repository, but the repository is understandably not set up to let
jerojasro@343 651 anonymous users push to it.
jerojasro@343 652 \interaction{tour.push.net}
jerojasro@343 653
jerojasro@343 654 %%% Local Variables:
jerojasro@343 655 %%% mode: latex
jerojasro@343 656 %%% TeX-master: "00book"
jerojasro@343 657 %%% End: