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@352
|
121 repositorio para un proyecto contiene todos los archivos que
|
jerojasro@352
|
122 ``pertenecen a'' ése proyecto, junto con un registro histórico de los
|
jerojasro@352
|
123 archivos de ese proyecto.
|
jerojasro@352
|
124
|
jerojasro@352
|
125 No hay nada particularmente mágico acerca de un repositorio; es
|
jerojasro@352
|
126 simplemente un árbol de directorios en su sistema de archivos 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@352
|
134 usted podría usar un programa normal de copia de archivos 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@352
|
141 llamado \dirname{hello}. Este directorio contendrá algunos archivos.
|
jerojasro@343
|
142 \interaction{tour.ls}
|
jerojasro@352
|
143 Estos archivos 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@352
|
147 independiente. Contiene su propia copia de los archivos 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@355
|
166 cualquier otro archivo o directorio en el repositorio.
|
jerojasro@343
|
167
|
jerojasro@357
|
168 Para introducir algo de terminología, el directorio \dirname{.hg} es
|
jerojasro@357
|
169 el repositorio ``real'', y todos los archivos 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@343
|
183 By default, this command prints a brief paragraph of output for each
|
jerojasro@343
|
184 change to the project that was recorded. In Mercurial terminology, we
|
jerojasro@343
|
185 call each of these recorded events a \emph{changeset}, because it can
|
jerojasro@343
|
186 contain a record of changes to several files.
|
jerojasro@343
|
187
|
jerojasro@343
|
188 The fields in a record of output from \hgcmd{log} are as follows.
|
jerojasro@343
|
189 \begin{itemize}
|
jerojasro@343
|
190 \item[\texttt{changeset}] This field has the format of a number,
|
jerojasro@343
|
191 followed by a colon, followed by a hexadecimal string. These are
|
jerojasro@343
|
192 \emph{identifiers} for the changeset. There are two identifiers
|
jerojasro@343
|
193 because the number is shorter and easier to type than the hex
|
jerojasro@343
|
194 string.
|
jerojasro@343
|
195 \item[\texttt{user}] The identity of the person who created the
|
jerojasro@343
|
196 changeset. This is a free-form field, but it most often contains a
|
jerojasro@343
|
197 person's name and email address.
|
jerojasro@343
|
198 \item[\texttt{date}] The date and time on which the changeset was
|
jerojasro@343
|
199 created, and the timezone in which it was created. (The date and
|
jerojasro@343
|
200 time are local to that timezone; they display what time and date it
|
jerojasro@343
|
201 was for the person who created the changeset.)
|
jerojasro@343
|
202 \item[\texttt{summary}] The first line of the text message that the
|
jerojasro@343
|
203 creator of the changeset entered to describe the changeset.
|
jerojasro@343
|
204 \end{itemize}
|
jerojasro@343
|
205 The default output printed by \hgcmd{log} is purely a summary; it is
|
jerojasro@343
|
206 missing a lot of detail.
|
jerojasro@343
|
207
|
jerojasro@343
|
208 Figure~\ref{fig:tour-basic:history} provides a graphical representation of
|
jerojasro@343
|
209 the history of the \dirname{hello} repository, to make it a little
|
jerojasro@343
|
210 easier to see which direction history is ``flowing'' in. We'll be
|
jerojasro@343
|
211 returning to this figure several times in this chapter and the chapter
|
jerojasro@343
|
212 that follows.
|
jerojasro@343
|
213
|
jerojasro@343
|
214 \begin{figure}[ht]
|
jerojasro@343
|
215 \centering
|
jerojasro@343
|
216 \grafix{tour-history}
|
jerojasro@343
|
217 \caption{Graphical history of the \dirname{hello} repository}
|
jerojasro@343
|
218 \label{fig:tour-basic:history}
|
jerojasro@343
|
219 \end{figure}
|
jerojasro@343
|
220
|
jerojasro@343
|
221 \subsection{Changesets, revisions, and talking to other
|
jerojasro@343
|
222 people}
|
jerojasro@343
|
223
|
jerojasro@343
|
224 As English is a notoriously sloppy language, and computer science has
|
jerojasro@343
|
225 a hallowed history of terminological confusion (why use one term when
|
jerojasro@343
|
226 four will do?), revision control has a variety of words and phrases
|
jerojasro@343
|
227 that mean the same thing. If you are talking about Mercurial history
|
jerojasro@343
|
228 with other people, you will find that the word ``changeset'' is often
|
jerojasro@343
|
229 compressed to ``change'' or (when written) ``cset'', and sometimes a
|
jerojasro@343
|
230 changeset is referred to as a ``revision'' or a ``rev''.
|
jerojasro@343
|
231
|
jerojasro@343
|
232 While it doesn't matter what \emph{word} you use to refer to the
|
jerojasro@343
|
233 concept of ``a~changeset'', the \emph{identifier} that you use to
|
jerojasro@343
|
234 refer to ``a~\emph{specific} changeset'' is of great importance.
|
jerojasro@343
|
235 Recall that the \texttt{changeset} field in the output from
|
jerojasro@343
|
236 \hgcmd{log} identifies a changeset using both a number and a
|
jerojasro@343
|
237 hexadecimal string.
|
jerojasro@343
|
238 \begin{itemize}
|
jerojasro@343
|
239 \item The revision number is \emph{only valid in that repository},
|
jerojasro@343
|
240 \item while the hex string is the \emph{permanent, unchanging
|
jerojasro@343
|
241 identifier} that will always identify that exact changeset in
|
jerojasro@343
|
242 \emph{every} copy of the repository.
|
jerojasro@343
|
243 \end{itemize}
|
jerojasro@343
|
244 This distinction is important. If you send someone an email talking
|
jerojasro@343
|
245 about ``revision~33'', there's a high likelihood that their
|
jerojasro@343
|
246 revision~33 will \emph{not be the same} as yours. The reason for this
|
jerojasro@343
|
247 is that a revision number depends on the order in which changes
|
jerojasro@343
|
248 arrived in a repository, and there is no guarantee that the same
|
jerojasro@343
|
249 changes will happen in the same order in different repositories.
|
jerojasro@343
|
250 Three changes $a,b,c$ can easily appear in one repository as $0,1,2$,
|
jerojasro@343
|
251 while in another as $1,0,2$.
|
jerojasro@343
|
252
|
jerojasro@343
|
253 Mercurial uses revision numbers purely as a convenient shorthand. If
|
jerojasro@343
|
254 you need to discuss a changeset with someone, or make a record of a
|
jerojasro@343
|
255 changeset for some other reason (for example, in a bug report), use
|
jerojasro@343
|
256 the hexadecimal identifier.
|
jerojasro@343
|
257
|
jerojasro@343
|
258 \subsection{Viewing specific revisions}
|
jerojasro@343
|
259
|
jerojasro@343
|
260 To narrow the output of \hgcmd{log} down to a single revision, use the
|
jerojasro@343
|
261 \hgopt{log}{-r} (or \hgopt{log}{--rev}) option. You can use either a
|
jerojasro@343
|
262 revision number or a long-form changeset identifier, and you can
|
jerojasro@343
|
263 provide as many revisions as you want. \interaction{tour.log-r}
|
jerojasro@343
|
264
|
jerojasro@343
|
265 If you want to see the history of several revisions without having to
|
jerojasro@343
|
266 list each one, you can use \emph{range notation}; this lets you
|
jerojasro@343
|
267 express the idea ``I want all revisions between $a$ and $b$,
|
jerojasro@343
|
268 inclusive''.
|
jerojasro@343
|
269 \interaction{tour.log.range}
|
jerojasro@343
|
270 Mercurial also honours the order in which you specify revisions, so
|
jerojasro@343
|
271 \hgcmdargs{log}{-r 2:4} prints $2,3,4$ while \hgcmdargs{log}{-r 4:2}
|
jerojasro@343
|
272 prints $4,3,2$.
|
jerojasro@343
|
273
|
jerojasro@343
|
274 \subsection{More detailed information}
|
jerojasro@343
|
275
|
jerojasro@343
|
276 While the summary information printed by \hgcmd{log} is useful if you
|
jerojasro@343
|
277 already know what you're looking for, you may need to see a complete
|
jerojasro@343
|
278 description of the change, or a list of the files changed, if you're
|
jerojasro@343
|
279 trying to decide whether a changeset is the one you're looking for.
|
jerojasro@343
|
280 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
|
jerojasro@343
|
281 option gives you this extra detail.
|
jerojasro@343
|
282 \interaction{tour.log-v}
|
jerojasro@343
|
283
|
jerojasro@343
|
284 If you want to see both the description and content of a change, add
|
jerojasro@343
|
285 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
|
jerojasro@343
|
286 the content of a change as a \emph{unified diff} (if you've never seen
|
jerojasro@343
|
287 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
|
jerojasro@343
|
288 \interaction{tour.log-vp}
|
jerojasro@343
|
289
|
jerojasro@343
|
290 \section{All about command options}
|
jerojasro@343
|
291
|
jerojasro@343
|
292 Let's take a brief break from exploring Mercurial commands to discuss
|
jerojasro@343
|
293 a pattern in the way that they work; you may find this useful to keep
|
jerojasro@343
|
294 in mind as we continue our tour.
|
jerojasro@343
|
295
|
jerojasro@343
|
296 Mercurial has a consistent and straightforward approach to dealing
|
jerojasro@343
|
297 with the options that you can pass to commands. It follows the
|
jerojasro@343
|
298 conventions for options that are common to modern Linux and Unix
|
jerojasro@343
|
299 systems.
|
jerojasro@343
|
300 \begin{itemize}
|
jerojasro@343
|
301 \item Every option has a long name. For example, as we've already
|
jerojasro@343
|
302 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
|
jerojasro@343
|
303 \item Most options have short names, too. Instead of
|
jerojasro@343
|
304 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
|
jerojasro@343
|
305 some options don't have short names is that the options in question
|
jerojasro@343
|
306 are rarely used.)
|
jerojasro@343
|
307 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
|
jerojasro@343
|
308 while short options start with one (e.g.~\hgopt{log}{-r}).
|
jerojasro@343
|
309 \item Option naming and usage is consistent across commands. For
|
jerojasro@343
|
310 example, every command that lets you specify a changeset~ID or
|
jerojasro@343
|
311 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
|
jerojasro@343
|
312 arguments.
|
jerojasro@343
|
313 \end{itemize}
|
jerojasro@343
|
314 In the examples throughout this book, I use short options instead of
|
jerojasro@343
|
315 long. This just reflects my own preference, so don't read anything
|
jerojasro@343
|
316 significant into it.
|
jerojasro@343
|
317
|
jerojasro@343
|
318 Most commands that print output of some kind will print more output
|
jerojasro@343
|
319 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
|
jerojasro@343
|
320 when passed \hggopt{-q} (or \hggopt{--quiet}).
|
jerojasro@343
|
321
|
jerojasro@343
|
322 \section{Making and reviewing changes}
|
jerojasro@343
|
323
|
jerojasro@343
|
324 Now that we have a grasp of viewing history in Mercurial, let's take a
|
jerojasro@343
|
325 look at making some changes and examining them.
|
jerojasro@343
|
326
|
jerojasro@343
|
327 The first thing we'll do is isolate our experiment in a repository of
|
jerojasro@343
|
328 its own. We use the \hgcmd{clone} command, but we don't need to
|
jerojasro@343
|
329 clone a copy of the remote repository. Since we already have a copy
|
jerojasro@343
|
330 of it locally, we can just clone that instead. This is much faster
|
jerojasro@343
|
331 than cloning over the network, and cloning a local repository uses
|
jerojasro@343
|
332 less disk space in most cases, too.
|
jerojasro@343
|
333 \interaction{tour.reclone}
|
jerojasro@343
|
334 As an aside, it's often good practice to keep a ``pristine'' copy of a
|
jerojasro@343
|
335 remote repository around, which you can then make temporary clones of
|
jerojasro@343
|
336 to create sandboxes for each task you want to work on. This lets you
|
jerojasro@343
|
337 work on multiple tasks in parallel, each isolated from the others
|
jerojasro@343
|
338 until it's complete and you're ready to integrate it back. Because
|
jerojasro@343
|
339 local clones are so cheap, there's almost no overhead to cloning and
|
jerojasro@343
|
340 destroying repositories whenever you want.
|
jerojasro@343
|
341
|
jerojasro@343
|
342 In our \dirname{my-hello} repository, we have a file
|
jerojasro@343
|
343 \filename{hello.c} that contains the classic ``hello, world'' program.
|
jerojasro@343
|
344 Let's use the ancient and venerable \command{sed} command to edit this
|
jerojasro@343
|
345 file so that it prints a second line of output. (I'm only using
|
jerojasro@343
|
346 \command{sed} to do this because it's easy to write a scripted example
|
jerojasro@343
|
347 this way. Since you're not under the same constraint, you probably
|
jerojasro@343
|
348 won't want to use \command{sed}; simply use your preferred text editor to
|
jerojasro@343
|
349 do the same thing.)
|
jerojasro@343
|
350 \interaction{tour.sed}
|
jerojasro@343
|
351
|
jerojasro@343
|
352 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
|
jerojasro@343
|
353 about the files in the repository.
|
jerojasro@343
|
354 \interaction{tour.status}
|
jerojasro@343
|
355 The \hgcmd{status} command prints no output for some files, but a line
|
jerojasro@343
|
356 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
|
jerojasro@343
|
357 it to, \hgcmd{status} will not print any output for files that have
|
jerojasro@343
|
358 not been modified.
|
jerojasro@343
|
359
|
jerojasro@343
|
360 The ``\texttt{M}'' indicates that Mercurial has noticed that we
|
jerojasro@343
|
361 modified \filename{hello.c}. We didn't need to \emph{inform}
|
jerojasro@343
|
362 Mercurial that we were going to modify the file before we started, or
|
jerojasro@343
|
363 that we had modified the file after we were done; it was able to
|
jerojasro@343
|
364 figure this out itself.
|
jerojasro@343
|
365
|
jerojasro@343
|
366 It's a little bit helpful to know that we've modified
|
jerojasro@343
|
367 \filename{hello.c}, but we might prefer to know exactly \emph{what}
|
jerojasro@343
|
368 changes we've made to it. To do this, we use the \hgcmd{diff}
|
jerojasro@343
|
369 command.
|
jerojasro@343
|
370 \interaction{tour.diff}
|
jerojasro@343
|
371
|
jerojasro@343
|
372 \section{Recording changes in a new changeset}
|
jerojasro@343
|
373
|
jerojasro@343
|
374 We can modify files, build and test our changes, and use
|
jerojasro@343
|
375 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
|
jerojasro@343
|
376 satisfied with what we've done and arrive at a natural stopping point
|
jerojasro@343
|
377 where we want to record our work in a new changeset.
|
jerojasro@343
|
378
|
jerojasro@343
|
379 The \hgcmd{commit} command lets us create a new changeset; we'll
|
jerojasro@343
|
380 usually refer to this as ``making a commit'' or ``committing''.
|
jerojasro@343
|
381
|
jerojasro@343
|
382 \subsection{Setting up a username}
|
jerojasro@343
|
383
|
jerojasro@343
|
384 When you try to run \hgcmd{commit} for the first time, it is not
|
jerojasro@343
|
385 guaranteed to succeed. Mercurial records your name and address with
|
jerojasro@343
|
386 each change that you commit, so that you and others will later be able
|
jerojasro@343
|
387 to tell who made each change. Mercurial tries to automatically figure
|
jerojasro@343
|
388 out a sensible username to commit the change with. It will attempt
|
jerojasro@343
|
389 each of the following methods, in order:
|
jerojasro@343
|
390 \begin{enumerate}
|
jerojasro@343
|
391 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
|
jerojasro@343
|
392 command on the command line, followed by a username, this is always
|
jerojasro@343
|
393 given the highest precedence.
|
jerojasro@343
|
394 \item If you have set the \envar{HGUSER} environment variable, this is
|
jerojasro@343
|
395 checked next.
|
jerojasro@343
|
396 \item If you create a file in your home directory called
|
jerojasro@343
|
397 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
|
jerojasro@343
|
398 used next. To see what the contents of this file should look like,
|
jerojasro@343
|
399 refer to section~\ref{sec:tour-basic:username} below.
|
jerojasro@343
|
400 \item If you have set the \envar{EMAIL} environment variable, this
|
jerojasro@343
|
401 will be used next.
|
jerojasro@343
|
402 \item Mercurial will query your system to find out your local user
|
jerojasro@343
|
403 name and host name, and construct a username from these components.
|
jerojasro@343
|
404 Since this often results in a username that is not very useful, it
|
jerojasro@343
|
405 will print a warning if it has to do this.
|
jerojasro@343
|
406 \end{enumerate}
|
jerojasro@343
|
407 If all of these mechanisms fail, Mercurial will fail, printing an
|
jerojasro@343
|
408 error message. In this case, it will not let you commit until you set
|
jerojasro@343
|
409 up a username.
|
jerojasro@343
|
410
|
jerojasro@343
|
411 You should think of the \envar{HGUSER} environment variable and the
|
jerojasro@343
|
412 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
|
jerojasro@343
|
413 \emph{override} Mercurial's default selection of username. For normal
|
jerojasro@343
|
414 use, the simplest and most robust way to set a username for yourself
|
jerojasro@343
|
415 is by creating a \sfilename{.hgrc} file; see below for details.
|
jerojasro@343
|
416
|
jerojasro@343
|
417 \subsubsection{Creating a Mercurial configuration file}
|
jerojasro@343
|
418 \label{sec:tour-basic:username}
|
jerojasro@343
|
419
|
jerojasro@343
|
420 To set a user name, use your favourite editor to create a file called
|
jerojasro@343
|
421 \sfilename{.hgrc} in your home directory. Mercurial will use this
|
jerojasro@343
|
422 file to look up your personalised configuration settings. The initial
|
jerojasro@343
|
423 contents of your \sfilename{.hgrc} should look like this.
|
jerojasro@343
|
424 \begin{codesample2}
|
jerojasro@343
|
425 # This is a Mercurial configuration file.
|
jerojasro@343
|
426 [ui]
|
jerojasro@343
|
427 username = Firstname Lastname <email.address@domain.net>
|
jerojasro@343
|
428 \end{codesample2}
|
jerojasro@343
|
429 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
|
jerojasro@343
|
430 so you can read the ``\texttt{username = ...}'' line as meaning ``set
|
jerojasro@343
|
431 the value of the \texttt{username} item in the \texttt{ui} section''.
|
jerojasro@343
|
432 A section continues until a new section begins, or the end of the
|
jerojasro@343
|
433 file. Mercurial ignores empty lines and treats any text from
|
jerojasro@343
|
434 ``\texttt{\#}'' to the end of a line as a comment.
|
jerojasro@343
|
435
|
jerojasro@343
|
436 \subsubsection{Choosing a user name}
|
jerojasro@343
|
437
|
jerojasro@343
|
438 You can use any text you like as the value of the \texttt{username}
|
jerojasro@343
|
439 config item, since this information is for reading by other people,
|
jerojasro@343
|
440 but for interpreting by Mercurial. The convention that most people
|
jerojasro@343
|
441 follow is to use their name and email address, as in the example
|
jerojasro@343
|
442 above.
|
jerojasro@343
|
443
|
jerojasro@343
|
444 \begin{note}
|
jerojasro@343
|
445 Mercurial's built-in web server obfuscates email addresses, to make
|
jerojasro@343
|
446 it more difficult for the email harvesting tools that spammers use.
|
jerojasro@343
|
447 This reduces the likelihood that you'll start receiving more junk
|
jerojasro@343
|
448 email if you publish a Mercurial repository on the web.
|
jerojasro@343
|
449 \end{note}
|
jerojasro@343
|
450
|
jerojasro@343
|
451 \subsection{Writing a commit message}
|
jerojasro@343
|
452
|
jerojasro@343
|
453 When we commit a change, Mercurial drops us into a text editor, to
|
jerojasro@343
|
454 enter a message that will describe the modifications we've made in
|
jerojasro@343
|
455 this changeset. This is called the \emph{commit message}. It will be
|
jerojasro@343
|
456 a record for readers of what we did and why, and it will be printed by
|
jerojasro@343
|
457 \hgcmd{log} after we've finished committing.
|
jerojasro@343
|
458 \interaction{tour.commit}
|
jerojasro@343
|
459
|
jerojasro@343
|
460 The editor that the \hgcmd{commit} command drops us into will contain
|
jerojasro@343
|
461 an empty line, followed by a number of lines starting with
|
jerojasro@343
|
462 ``\texttt{HG:}''.
|
jerojasro@343
|
463 \begin{codesample2}
|
jerojasro@343
|
464 \emph{empty line}
|
jerojasro@343
|
465 HG: changed hello.c
|
jerojasro@343
|
466 \end{codesample2}
|
jerojasro@343
|
467 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
|
jerojasro@343
|
468 them only to tell us which files it's recording changes to. Modifying
|
jerojasro@343
|
469 or deleting these lines has no effect.
|
jerojasro@343
|
470
|
jerojasro@343
|
471 \subsection{Writing a good commit message}
|
jerojasro@343
|
472
|
jerojasro@343
|
473 Since \hgcmd{log} only prints the first line of a commit message by
|
jerojasro@343
|
474 default, it's best to write a commit message whose first line stands
|
jerojasro@343
|
475 alone. Here's a real example of a commit message that \emph{doesn't}
|
jerojasro@343
|
476 follow this guideline, and hence has a summary that is not readable.
|
jerojasro@343
|
477 \begin{codesample2}
|
jerojasro@343
|
478 changeset: 73:584af0e231be
|
jerojasro@343
|
479 user: Censored Person <censored.person@example.org>
|
jerojasro@343
|
480 date: Tue Sep 26 21:37:07 2006 -0700
|
jerojasro@343
|
481 summary: include buildmeister/commondefs. Add an exports and install
|
jerojasro@343
|
482 \end{codesample2}
|
jerojasro@343
|
483
|
jerojasro@343
|
484 As far as the remainder of the contents of the commit message are
|
jerojasro@343
|
485 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
|
jerojasro@343
|
486 interpret or care about the contents of the commit message, though
|
jerojasro@343
|
487 your project may have policies that dictate a certain kind of
|
jerojasro@343
|
488 formatting.
|
jerojasro@343
|
489
|
jerojasro@343
|
490 My personal preference is for short, but informative, commit messages
|
jerojasro@343
|
491 that tell me something that I can't figure out with a quick glance at
|
jerojasro@343
|
492 the output of \hgcmdargs{log}{--patch}.
|
jerojasro@343
|
493
|
jerojasro@343
|
494 \subsection{Aborting a commit}
|
jerojasro@343
|
495
|
jerojasro@343
|
496 If you decide that you don't want to commit while in the middle of
|
jerojasro@343
|
497 editing a commit message, simply exit from your editor without saving
|
jerojasro@343
|
498 the file that it's editing. This will cause nothing to happen to
|
jerojasro@343
|
499 either the repository or the working directory.
|
jerojasro@343
|
500
|
jerojasro@343
|
501 If we run the \hgcmd{commit} command without any arguments, it records
|
jerojasro@343
|
502 all of the changes we've made, as reported by \hgcmd{status} and
|
jerojasro@343
|
503 \hgcmd{diff}.
|
jerojasro@343
|
504
|
jerojasro@343
|
505 \subsection{Admiring our new handiwork}
|
jerojasro@343
|
506
|
jerojasro@343
|
507 Once we've finished the commit, we can use the \hgcmd{tip} command to
|
jerojasro@343
|
508 display the changeset we just created. This command produces output
|
jerojasro@343
|
509 that is identical to \hgcmd{log}, but it only displays the newest
|
jerojasro@343
|
510 revision in the repository.
|
jerojasro@343
|
511 \interaction{tour.tip}
|
jerojasro@343
|
512 We refer to the newest revision in the repository as the tip revision,
|
jerojasro@343
|
513 or simply the tip.
|
jerojasro@343
|
514
|
jerojasro@343
|
515 \section{Sharing changes}
|
jerojasro@343
|
516
|
jerojasro@343
|
517 We mentioned earlier that repositories in Mercurial are
|
jerojasro@343
|
518 self-contained. This means that the changeset we just created exists
|
jerojasro@343
|
519 only in our \dirname{my-hello} repository. Let's look at a few ways
|
jerojasro@343
|
520 that we can propagate this change into other repositories.
|
jerojasro@343
|
521
|
jerojasro@343
|
522 \subsection{Pulling changes from another repository}
|
jerojasro@343
|
523 \label{sec:tour:pull}
|
jerojasro@343
|
524
|
jerojasro@343
|
525 To get started, let's clone our original \dirname{hello} repository,
|
jerojasro@343
|
526 which does not contain the change we just committed. We'll call our
|
jerojasro@343
|
527 temporary repository \dirname{hello-pull}.
|
jerojasro@343
|
528 \interaction{tour.clone-pull}
|
jerojasro@343
|
529
|
jerojasro@343
|
530 We'll use the \hgcmd{pull} command to bring changes from
|
jerojasro@343
|
531 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
|
jerojasro@343
|
532 pulling unknown changes into a repository is a somewhat scary
|
jerojasro@343
|
533 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
|
jerojasro@343
|
534 what changes the \hgcmd{pull} command \emph{would} pull into the
|
jerojasro@343
|
535 repository, without actually pulling the changes in.
|
jerojasro@343
|
536 \interaction{tour.incoming}
|
jerojasro@343
|
537 (Of course, someone could cause more changesets to appear in the
|
jerojasro@343
|
538 repository that we ran \hgcmd{incoming} in, before we get a chance to
|
jerojasro@343
|
539 \hgcmd{pull} the changes, so that we could end up pulling changes that we
|
jerojasro@343
|
540 didn't expect.)
|
jerojasro@343
|
541
|
jerojasro@343
|
542 Bringing changes into a repository is a simple matter of running the
|
jerojasro@343
|
543 \hgcmd{pull} command, and telling it which repository to pull from.
|
jerojasro@343
|
544 \interaction{tour.pull}
|
jerojasro@343
|
545 As you can see from the before-and-after output of \hgcmd{tip}, we
|
jerojasro@343
|
546 have successfully pulled changes into our repository. There remains
|
jerojasro@343
|
547 one step before we can see these changes in the working directory.
|
jerojasro@343
|
548
|
jerojasro@343
|
549 \subsection{Updating the working directory}
|
jerojasro@343
|
550
|
jerojasro@343
|
551 We have so far glossed over the relationship between a repository and
|
jerojasro@343
|
552 its working directory. The \hgcmd{pull} command that we ran in
|
jerojasro@343
|
553 section~\ref{sec:tour:pull} brought changes into the repository, but
|
jerojasro@343
|
554 if we check, there's no sign of those changes in the working
|
jerojasro@343
|
555 directory. This is because \hgcmd{pull} does not (by default) touch
|
jerojasro@343
|
556 the working directory. Instead, we use the \hgcmd{update} command to
|
jerojasro@343
|
557 do this.
|
jerojasro@343
|
558 \interaction{tour.update}
|
jerojasro@343
|
559
|
jerojasro@343
|
560 It might seem a bit strange that \hgcmd{pull} doesn't update the
|
jerojasro@343
|
561 working directory automatically. There's actually a good reason for
|
jerojasro@343
|
562 this: you can use \hgcmd{update} to update the working directory to
|
jerojasro@343
|
563 the state it was in at \emph{any revision} in the history of the
|
jerojasro@343
|
564 repository. If you had the working directory updated to an old
|
jerojasro@343
|
565 revision---to hunt down the origin of a bug, say---and ran a
|
jerojasro@343
|
566 \hgcmd{pull} which automatically updated the working directory to a
|
jerojasro@343
|
567 new revision, you might not be terribly happy.
|
jerojasro@343
|
568
|
jerojasro@343
|
569 However, since pull-then-update is such a common thing to do,
|
jerojasro@343
|
570 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
|
jerojasro@343
|
571 option to \hgcmd{pull}.
|
jerojasro@343
|
572 \begin{codesample2}
|
jerojasro@343
|
573 hg pull -u
|
jerojasro@343
|
574 \end{codesample2}
|
jerojasro@343
|
575 If you look back at the output of \hgcmd{pull} in
|
jerojasro@343
|
576 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
|
jerojasro@343
|
577 you can see that it printed a helpful reminder that we'd have to take
|
jerojasro@343
|
578 an explicit step to update the working directory:
|
jerojasro@343
|
579 \begin{codesample2}
|
jerojasro@343
|
580 (run 'hg update' to get a working copy)
|
jerojasro@343
|
581 \end{codesample2}
|
jerojasro@343
|
582
|
jerojasro@343
|
583 To find out what revision the working directory is at, use the
|
jerojasro@343
|
584 \hgcmd{parents} command.
|
jerojasro@343
|
585 \interaction{tour.parents}
|
jerojasro@343
|
586 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
|
jerojasro@343
|
587 arrows connecting each changeset. The node that the arrow leads
|
jerojasro@343
|
588 \emph{from} in each case is a parent, and the node that the arrow
|
jerojasro@343
|
589 leads \emph{to} is its child. The working directory has a parent in
|
jerojasro@343
|
590 just the same way; this is the changeset that the working directory
|
jerojasro@343
|
591 currently contains.
|
jerojasro@343
|
592
|
jerojasro@343
|
593 To update the working directory to a particular revision, give a
|
jerojasro@343
|
594 revision number or changeset~ID to the \hgcmd{update} command.
|
jerojasro@343
|
595 \interaction{tour.older}
|
jerojasro@343
|
596 If you omit an explicit revision, \hgcmd{update} will update to the
|
jerojasro@343
|
597 tip revision, as shown by the second call to \hgcmd{update} in the
|
jerojasro@343
|
598 example above.
|
jerojasro@343
|
599
|
jerojasro@343
|
600 \subsection{Pushing changes to another repository}
|
jerojasro@343
|
601
|
jerojasro@343
|
602 Mercurial lets us push changes to another repository, from the
|
jerojasro@343
|
603 repository we're currently visiting. As with the example of
|
jerojasro@343
|
604 \hgcmd{pull} above, we'll create a temporary repository to push our
|
jerojasro@343
|
605 changes into.
|
jerojasro@343
|
606 \interaction{tour.clone-push}
|
jerojasro@343
|
607 The \hgcmd{outgoing} command tells us what changes would be pushed
|
jerojasro@343
|
608 into another repository.
|
jerojasro@343
|
609 \interaction{tour.outgoing}
|
jerojasro@343
|
610 And the \hgcmd{push} command does the actual push.
|
jerojasro@343
|
611 \interaction{tour.push}
|
jerojasro@343
|
612 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
|
jerojasro@343
|
613 working directory in the repository that it's pushing changes into.
|
jerojasro@343
|
614 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
|
jerojasro@343
|
615 option that updates the other repository's working directory.)
|
jerojasro@343
|
616
|
jerojasro@343
|
617 What happens if we try to pull or push changes and the receiving
|
jerojasro@343
|
618 repository already has those changes? Nothing too exciting.
|
jerojasro@343
|
619 \interaction{tour.push.nothing}
|
jerojasro@343
|
620
|
jerojasro@343
|
621 \subsection{Sharing changes over a network}
|
jerojasro@343
|
622
|
jerojasro@343
|
623 The commands we have covered in the previous few sections are not
|
jerojasro@343
|
624 limited to working with local repositories. Each works in exactly the
|
jerojasro@343
|
625 same fashion over a network connection; simply pass in a URL instead
|
jerojasro@343
|
626 of a local path.
|
jerojasro@343
|
627 \interaction{tour.outgoing.net}
|
jerojasro@343
|
628 In this example, we can see what changes we could push to the remote
|
jerojasro@343
|
629 repository, but the repository is understandably not set up to let
|
jerojasro@343
|
630 anonymous users push to it.
|
jerojasro@343
|
631 \interaction{tour.push.net}
|
jerojasro@343
|
632
|
jerojasro@343
|
633 %%% Local Variables:
|
jerojasro@343
|
634 %%% mode: latex
|
jerojasro@343
|
635 %%% TeX-master: "00book"
|
jerojasro@343
|
636 %%% End:
|