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