hgbook
view fr/tour-basic.tex @ 945:5016d2b44950
Oops, overwrite some of my translation by adding Hugues works... Corrected.
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Mon Feb 16 18:44:54 2009 +0100 (2009-02-16) |
| parents | 73aae11ba719 |
| children | 1f2044943861 |
line source
1 \chapter{Un rapide tour de Mercurial}
2 \label{chap:tour-basic}
4 \section{Installer Mercurial sur votre système}
5 \label{sec:tour:install}
7 Des paquetages binaires de Mercurial sont disponibles pour la plupart
8 des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate
9 de Mercurial sur votre ordinateur.
11 \subsection{Linux}
13 Parce que chaque distribution de Linux a ses propres outils de gestion
14 de paquets, politiques et rythmes de développements, il est difficile de
15 donner un ensemble d'instructions fixes pour installer les binaires de
16 Mercurial. La version de Mercurial avec laquelle vous vous retrouverez
17 dépendra grandement de l'activité de la personne en charge du paquetage
18 pour la distribution.
20 Pour rester simple, je me concentrerai sur l'installation de Mercurial
21 en ligne de commande, sous les plus courantes des distributions. La
22 plupart des distributions fournissent des gestionnaires graphiques de
23 paquetage qui vous permettront d'installer Mercurial en quelques clicks.
24 Le paquetage devrait se nommer \textit{mercurial}.
26 \begin{itemize}
27 \item[Debian]
28 \begin{codesample4}
29 apt-get install mercurial
30 \end{codesample4}
32 \item[Fedora Core]
33 \begin{codesample4}
34 yum install mercurial
35 \end{codesample4}
37 \item[Gentoo]
38 \begin{codesample4}
39 emerge mercurial
40 \end{codesample4}
42 \item[OpenSUSE]
43 \begin{codesample4}
44 yum install mercurial
45 \end{codesample4}
47 \item[Ubuntu] Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian.
48 Pour l'installer, exécute simplement les commandes suivantes:
49 \begin{codesample4}
50 apt-get install mercurial
51 \end{codesample4}
52 Les paquetages Ubuntu pour Mercurial ont tendance à être un peu en retard
53 par rapport au paquetage Debian (au moment de l'écriture de ce livre, il
54 faut compter un peu près un retard de 7 mois), ce qui signifie que parfois
55 sur Ubuntu, vous risquez de rencontrer des problèmes qui ont été corrigés
56 depuis longtemps dans les paquetages Debian.
57 \end{itemize}
59 \subsection{Solaris}
61 SunFreeWare, à \url{http://www.saufreeware.com}, est une bonne source
62 pour trouver un vaste nombre de paquets précompilés pour 32 ou 64 bits
63 Intel et les architecture Sparc, dont les versions courantes de Mercurial.
65 \subsection{Mac OS X}
67 Lee Cantey publie un installeur de Mercurial pour Mac OS~X sur le site
68 \url{http://mercurial.berkwood.com}. Ce paquetage fonctionne sur les
69 architectures Intel-~et PowerPCC. Avant de vous en servir, vous devez
70 installer une version Universel MacPython~\cite{web:macpython}. C'est
71 assez facile à faire : suivez simplement les instructions sur le site
72 de Lee.
74 Il est aussi possible d'installer Mercurial en utilisant Fink ou MacPorts,
75 deux outils de gestion de paquetage libres pour Mac OS X. Si vous avez
76 Fink, utiliser \command{sudo fink install mercurial-py25}. Si vous avez
77 acPorts, \command{sudo port install mercurial}.
79 \subsection{Windows}
81 Lee Cantey publie aussi un installeur de Mercurial pour Windows sur le site
82 \url{http://mercurial.berkwood.com}. Ce paquetage n'a aucune dépendance
83 externe, il fonctionne ``tout court''.
85 \begin{note}
86 Le version de Windows de Mercurial ne convertie pas automatiquement
87 les retour chariot Windows et Unix. Si vous désirez partager votre
88 travail avec des utilisateurs Unix, vous devez faire un peu de configuration
89 supllémentaire. XXX En dire plus.
90 \end{note}
92 \section{Commencer à utiliser Mercurial}
94 Pour commencer, nous utiliserons la commande \hgcmd{version} pour vérifier
95 si Mercurial est installé proprement. Les informations affichées sur la
96 version ne sont pas réellement importante en soit, c'est surtout de savoir
97 si elles s'affichent qui nous intéresse.
98 \interaction{tour.version}
100 \subsection{L'aide intégrée}
102 Mercurial fournit un système d'aide intégré, ce qui est inestimable quand
103 vous vous retrouvez coincé à essayer de vous rappeler comment lancer telle
104 ou telle commande.
105 Si c'est le cas, exécuter simplement \hgcmd{help}; il vous aidera à imprimer
106 une brève liste de commandes, avec une description de ce qu'elles font. Si vous
107 demandez de l'aide sur une commande spécifique (voir ci dessous), il affichera
108 des informations plus détaillées.
109 \interaction{tour.help}
110 Pour un niveau d'informations encore plus détaillées (ce dont vous aurez rarement
111 besoin), exécuter \hgcmdargs{help}{\hggopt{-v}}. L'option \hggopt{-v} est
112 l'abréviation de \hggopt{--verbose}, et indique à Mercurial d'afficher plus
113 d'informations que d'habitude.
115 \section{Travailler avec un dépot}
117 Avec Mercurial, tout se déroule au sein du \emph{dépot}\footnote{NdT: Dépôt est
118 la traduction que j'ai retenue pour tout l'ouvrage du terme anglais \textit{repository}}.
119 Le dépôt d'un projet contient tous les fichiers qui ``appartiennent'' au projet.
121 Il n'y a rien de particulièrement magique au sujet de ce dépot, c'est
122 simplement une arboresence sur votre système de fichiers que Mercurial
123 traite de manière spéciale. Si vous pouvez renommer ou effacer ce répertoire
124 à n'importe quel moment, en utilisant la ligne de commande ou votre
125 explorateur de fichiers.
127 \subsection{Faire une copie locale de votre dépot}
129 \emph{Copier} un dépôt est just un peu spécial. Bien que vous
130 puissiez utiliser une commande habituelle de copie pour copier
131 votre dépôt, il vaut mieux utiliser une commande fournie par
132 Mercurial. Cette commande est appelée \hgcmd{clone}, car elle
133 crée une copie identique d'un dépôt existant.
134 \interaction{tour.clone}
135 Si votre opération de clonage réussit, vous devriez maintenant
136 avoir un répertoire local appelé \dirname{hello}. Ce répertoire
137 contiendra quelques fichiers.
138 \interaction{tour.ls}
139 Ces fichiers ont le même contenu et historique dans votre dépôt
140 qu'ils ont dans le dépôt que vous avez cloné.
142 Chaque dépôt Mercurial est complet, autonome et indépendant. Il
143 contient sa propre copie privé des fichiers du projet et de leurs
144 historiques. Le clone d'un dépôt se souvient de la localisation du
145 dépôt à partir duquel il a été clôné, mais il ne communique pas avec
146 ce dernier, ou un autre, à moins que vous ne lui demandiez.
148 Ce que tout ceci signifie pour le moment est que nous sommes libre
149 d'expérimenter avec ce dépôt, confiant dans le fait qu'il s'agit d'un
150 ``bac à sable'' qui n'affectera personne d'autres.
152 \subsection{Quel est le contenu d'un dépôt ?}
154 Prêtons plus attention un instant au contenu d'un dépôt. Nous voyons
155 qu'il contient un répertoire nommée \dirname{.hg}. C'est ici que Mercurial
156 conserve toutes ses métadonnées.
157 \interaction{tour.ls-a}
159 Le contenu du répertoire \dirname{.hg} et ses sous répertoires sont les
160 seules propre à Mercurial. Tout les autres fichiers et répertoire dans
161 le répertoire sont à vous, et vous pouvez faire ce que vous en voulez.
163 Pour introduire un peu de terminologie, le répertoire \dirname{.hg} est
164 un ``vrai'' dépôt, et tout les fichiers et les répertoires qui coexistent
165 avec lui, sont désigné sous le nom de \emph{espace de travail}\footnote{NdT:
166 \textit{working directory}}. Une manière facile de se rappeler cette
167 distinction est de retenir que le \emph{dépôt} contient l'\emph{historique}
168 de votre projet, alors que l'\emph{espace de travail} contient une \emph{copie
169 précise}\footnote{NdT: Ce terme est une traduction du terme anglais
170 \textit{snapshot}. Il est traduit ici pour faciliter la lecture, mais ne sera
171 plus traduit par la suite.} de votre projet à un certain point de son
172 historique.
174 \section{Une ballade dans l'historique}
176 Une des premières choses que vous aurez envie de faire avec un nouveau
177 dépôt, sera de comprendre son historique. La commande \hgcmd{log} vous
178 donne une vue de l'historique.
179 \interaction{tour.log}
180 Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
181 révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
182 appelons chacun de ces évènements enregistrés un \emph{changeset}, parce
183 qu'il contient un ensemble de mofications sur plusieurs fichiers.
185 La commande \hgcmd{log} affiche ainsi ces informations:
186 \begin{itemize}
187 \item[\texttt{changeset}] Ce champ contient un nombre, séparé par une
188 virgule, d'une chaine hexadécimal. Il s'agit en effet d'\emph{identifiants}
189 pour un \textit{changeset}. Il y a deux identifiants car le numéro de
190 la révision est plus court et plus à facile à saisir qu'une séquence
191 hexadécimale.
192 \item[\texttt{utilisateur}] L'identité de la personne qui a crée ce
193 \textit{changeset}. C'est un champ libre de forme, mais la plupart du
194 temps il contient le nom et l'email de la personne.
195 \item[\texttt{date}] La date et l'heure à laquelle le \textit{changeset}
196 a été crée, ainsi que le \textit{timezone} dans laquelle il a été crée. %%%TODO: Translate 'timezone' properly
197 (La date et l'heure sont locals à cette \textit{timezone}, ils indiquent
198 donc quelle date et quelle il était pour la personne qui a crée ce
199 \textit{changeset}.)
200 \item[\texttt{résumé}] La première du message que le créateur a associée à
201 son \textit{changeset} pour le décrire.
202 \end{itemize}
204 Par défaut, la commande \hgcmd{log} n'affiche qu'un résumé, il manque
205 beaucoup de détails.
208 La figure~\ref{fig:tour-basic:history} fournit un représentation graphique
209 de l'historique du dépôt \dirname{hello}, pour rendre plus facile de voir
210 dans quelle direction l'historique se ``déroule''\footnote{NdT: \textit{flowing in}.}.
211 Nous reviendrons régulièrement à cette représentation dans ce chapitre et
212 ceux qui suivent.
214 \begin{figure}[ht]
215 \centering
216 \grafix{tour-history}
217 \caption{Représentation graphique du dépôt \dirname{hello} }
218 \label{fig:tour-basic:history}
219 \end{figure}
221 \subsection{Changesets, révisions, et discuter avec les autres}
223 Comme l'anglais est réputé pour un langage maladroit, et que l'informatique
224 est la source de bien des erreurs terminologique (pourquoi utiliser un
225 seul terme quand quatre feront l'affaire ?), la gestion de version a une
226 variété de mot et de phrases qui veulent dire la même chose. Si vous
227 parlez à quelqu'un de l'historique de Mercurial à d'autres personnes,
228 vous constaterez que souvent le mot ``\textit{changeset}'' est compressé
229 en juste ``change'' ou (à l'écrit) ``cset'', et même parfois un
230 \textit{changeset} simplement ``révision'', abrégé en ``rev''.
232 Bien que le \emph{mot} que vous utilisez pour désigner le concept de
233 \textit{changeset} importe peu, l'\emph{identifiant} que vous utilisez
234 pour désigner un \emph{spécifique} \textit{spécifique} a une grande
235 importance. Rappelez vous que le \textit{changeset} affiché par la
236 commande \hgcmd{log} identifie un \textit{changeset} à la fois avec
237 un numéro de révision et une séquence hexadécimale.
239 \begin{itemize}
240 \item Le numéro de révision est \emph{seulement valable dans ce dépôt},
241 \item alors que la séquence hexadécimale est un \emph{identifiant
242 permanent, et immutable } qui pourra toujours être associé à %%%TODO: Immutable ? Is this french ?
243 \textit{changeset} exacte de \emph{chaque} copie de votre dépôt.
244 \end{itemize}
246 La distinction est importante. Si vous envoyez un email à quelqu'un en
247 parlant de la ``révision 33'', il est très probable que sa révision~33
248 \emph{ne sera pas la même} que la votre. La raison de ceci est que le
249 numéro de révision dépend de l'ordre dans lequel les modifications sont
250 arrivés dans le dépôt, et il n'y a aucune garantie que les mêmes changements
251 soient arrivés dans le même ordre dans différents dépôts. Trois modifications
252 $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans
253 un autre comme $1,0,2$.
255 Mercurial utilise les numéro de révision uniquement comme des raccourcis
256 pratique. Si vous devez disctuer d'un \textit{changeset} avec quelqu'un,
257 our faire un enregistrement d'un \textit{changeset} pour une quelquonque
258 raison (par exemple, un rapport de \textit{bug}), utilisez la séquence
259 hexadécimale.
261 \subsection{Afficher une révision spécifique}
263 Pour réduire la sortie de \hgcmd{log} à une seule révision, utilisez
264 l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiser
265 le numéro de révision ou la séquence hexadécimal comme identifiant, et
266 vous demandez autant de révisions que vous le souhaitez.
267 \interaction{tour.log-r}
269 Si vous voulez voir l'historique de plusieurs révisions sans avoir à
270 les énumérer, vous pouvez utiliser la \emph{\textit{range notation}}
271 \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le
272 laisse en anglais} qui vous permet d'exprimer l'idée ``je veux toutes
273 les révisions entre $a$ et $b$, inclus''.
274 \interaction{tour.log.range}
275 Mercurial respecte aussi l'ordre dans lequel vous spécifier les
276 révisions, ainsi \hgcmdargs{log}{-r 2:4} affichera $2,3,4$ alors que
277 \hgcmdargs{log}{-r 4:2} affichera $4,3,2$.
279 \subsection{Informations détaillées}
281 While the summary information printed by \hgcmd{log} is useful if you
282 already know what you're looking for, you may need to see a complete
283 description of the change, or a list of the files changed, if you're
284 trying to decide whether a changeset is the one you're looking for.
285 The \hgcmd{log} command's \hggopt{-v} (or \hggopt{--verbose})
286 option gives you this extra detail.
287 \interaction{tour.log-v}
289 If you want to see both the description and content of a change, add
290 the \hgopt{log}{-p} (or \hgopt{log}{--patch}) option. This displays
291 the content of a change as a \emph{unified diff} (if you've never seen
292 a unified diff before, see section~\ref{sec:mq:patch} for an overview).
293 \interaction{tour.log-vp}
295 \section{All about command options}
297 Let's take a brief break from exploring Mercurial commands to discuss
298 a pattern in the way that they work; you may find this useful to keep
299 in mind as we continue our tour.
301 Mercurial has a consistent and straightforward approach to dealing
302 with the options that you can pass to commands. It follows the
303 conventions for options that are common to modern Linux and Unix
304 systems.
305 \begin{itemize}
306 \item Every option has a long name. For example, as we've already
307 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
308 \item Most options have short names, too. Instead of
309 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
310 some options don't have short names is that the options in question
311 are rarely used.)
312 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
313 while short options start with one (e.g.~\hgopt{log}{-r}).
314 \item Option naming and usage is consistent across commands. For
315 example, every command that lets you specify a changeset~ID or
316 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
317 arguments.
318 \end{itemize}
319 In the examples throughout this book, I use short options instead of
320 long. This just reflects my own preference, so don't read anything
321 significant into it.
323 Most commands that print output of some kind will print more output
324 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
325 when passed \hggopt{-q} (or \hggopt{--quiet}).
327 \section{Making and reviewing changes}
329 Now that we have a grasp of viewing history in Mercurial, let's take a
330 look at making some changes and examining them.
332 The first thing we'll do is isolate our experiment in a repository of
333 its own. We use the \hgcmd{clone} command, but we don't need to
334 clone a copy of the remote repository. Since we already have a copy
335 of it locally, we can just clone that instead. This is much faster
336 than cloning over the network, and cloning a local repository uses
337 less disk space in most cases, too.
338 \interaction{tour.reclone}
339 As an aside, it's often good practice to keep a ``pristine'' copy of a
340 remote repository around, which you can then make temporary clones of
341 to create sandboxes for each task you want to work on. This lets you
342 work on multiple tasks in parallel, each isolated from the others
343 until it's complete and you're ready to integrate it back. Because
344 local clones are so cheap, there's almost no overhead to cloning and
345 destroying repositories whenever you want.
347 In our \dirname{my-hello} repository, we have a file
348 \filename{hello.c} that contains the classic ``hello, world'' program.
349 Let's use the ancient and venerable \command{sed} command to edit this
350 file so that it prints a second line of output. (I'm only using
351 \command{sed} to do this because it's easy to write a scripted example
352 this way. Since you're not under the same constraint, you probably
353 won't want to use \command{sed}; simply use your preferred text editor to
354 do the same thing.)
355 \interaction{tour.sed}
357 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
358 about the files in the repository.
359 \interaction{tour.status}
360 The \hgcmd{status} command prints no output for some files, but a line
361 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
362 it to, \hgcmd{status} will not print any output for files that have
363 not been modified.
365 The ``\texttt{M}'' indicates that Mercurial has noticed that we
366 modified \filename{hello.c}. We didn't need to \emph{inform}
367 Mercurial that we were going to modify the file before we started, or
368 that we had modified the file after we were done; it was able to
369 figure this out itself.
371 It's a little bit helpful to know that we've modified
372 \filename{hello.c}, but we might prefer to know exactly \emph{what}
373 changes we've made to it. To do this, we use the \hgcmd{diff}
374 command.
375 \interaction{tour.diff}
377 \section{Recording changes in a new changeset}
379 We can modify files, build and test our changes, and use
380 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
381 satisfied with what we've done and arrive at a natural stopping point
382 where we want to record our work in a new changeset.
384 The \hgcmd{commit} command lets us create a new changeset; we'll
385 usually refer to this as ``making a commit'' or ``committing''.
387 \subsection{Setting up a username}
389 When you try to run \hgcmd{commit} for the first time, it is not
390 guaranteed to succeed. Mercurial records your name and address with
391 each change that you commit, so that you and others will later be able
392 to tell who made each change. Mercurial tries to automatically figure
393 out a sensible username to commit the change with. It will attempt
394 each of the following methods, in order:
395 \begin{enumerate}
396 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
397 command on the command line, followed by a username, this is always
398 given the highest precedence.
399 \item If you have set the \envar{HGUSER} environment variable, this is
400 checked next.
401 \item If you create a file in your home directory called
402 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
403 used next. To see what the contents of this file should look like,
404 refer to section~\ref{sec:tour-basic:username} below.
405 \item If you have set the \envar{EMAIL} environment variable, this
406 will be used next.
407 \item Mercurial will query your system to find out your local user
408 name and host name, and construct a username from these components.
409 Since this often results in a username that is not very useful, it
410 will print a warning if it has to do this.
411 \end{enumerate}
412 If all of these mechanisms fail, Mercurial will fail, printing an
413 error message. In this case, it will not let you commit until you set
414 up a username.
416 You should think of the \envar{HGUSER} environment variable and the
417 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
418 \emph{override} Mercurial's default selection of username. For normal
419 use, the simplest and most robust way to set a username for yourself
420 is by creating a \sfilename{.hgrc} file; see below for details.
422 \subsubsection{Creating a Mercurial configuration file}
423 \label{sec:tour-basic:username}
425 To set a user name, use your favourite editor to create a file called
426 \sfilename{.hgrc} in your home directory. Mercurial will use this
427 file to look up your personalised configuration settings. The initial
428 contents of your \sfilename{.hgrc} should look like this.
429 \begin{codesample2}
430 # This is a Mercurial configuration file.
431 [ui]
432 username = Firstname Lastname <email.address@domain.net>
433 \end{codesample2}
434 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
435 so you can read the ``\texttt{username = ...}'' line as meaning ``set
436 the value of the \texttt{username} item in the \texttt{ui} section''.
437 A section continues until a new section begins, or the end of the
438 file. Mercurial ignores empty lines and treats any text from
439 ``\texttt{\#}'' to the end of a line as a comment.
441 \subsubsection{Choosing a user name}
443 You can use any text you like as the value of the \texttt{username}
444 config item, since this information is for reading by other people,
445 but for interpreting by Mercurial. The convention that most people
446 follow is to use their name and email address, as in the example
447 above.
449 \begin{note}
450 Mercurial's built-in web server obfuscates email addresses, to make
451 it more difficult for the email harvesting tools that spammers use.
452 This reduces the likelihood that you'll start receiving more junk
453 email if you publish a Mercurial repository on the web.
454 \end{note}
456 \subsection{Writing a commit message}
458 When we commit a change, Mercurial drops us into a text editor, to
459 enter a message that will describe the modifications we've made in
460 this changeset. This is called the \emph{commit message}. It will be
461 a record for readers of what we did and why, and it will be printed by
462 \hgcmd{log} after we've finished committing.
463 \interaction{tour.commit}
465 The editor that the \hgcmd{commit} command drops us into will contain
466 an empty line, followed by a number of lines starting with
467 ``\texttt{HG:}''.
468 \begin{codesample2}
469 \emph{empty line}
470 HG: changed hello.c
471 \end{codesample2}
472 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
473 them only to tell us which files it's recording changes to. Modifying
474 or deleting these lines has no effect.
476 \subsection{Writing a good commit message}
478 Since \hgcmd{log} only prints the first line of a commit message by
479 default, it's best to write a commit message whose first line stands
480 alone. Here's a real example of a commit message that \emph{doesn't}
481 follow this guideline, and hence has a summary that is not readable.
482 \begin{codesample2}
483 changeset: 73:584af0e231be
484 user: Censored Person <censored.person@example.org>
485 date: Tue Sep 26 21:37:07 2006 -0700
486 summary: include buildmeister/commondefs. Add an exports and install
487 \end{codesample2}
489 As far as the remainder of the contents of the commit message are
490 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
491 interpret or care about the contents of the commit message, though
492 your project may have policies that dictate a certain kind of
493 formatting.
495 My personal preference is for short, but informative, commit messages
496 that tell me something that I can't figure out with a quick glance at
497 the output of \hgcmdargs{log}{--patch}.
499 \subsection{Aborting a commit}
501 If you decide that you don't want to commit while in the middle of
502 editing a commit message, simply exit from your editor without saving
503 the file that it's editing. This will cause nothing to happen to
504 either the repository or the working directory.
506 If we run the \hgcmd{commit} command without any arguments, it records
507 all of the changes we've made, as reported by \hgcmd{status} and
508 \hgcmd{diff}.
510 \subsection{Admiring our new handiwork}
512 Once we've finished the commit, we can use the \hgcmd{tip} command to
513 display the changeset we just created. This command produces output
514 that is identical to \hgcmd{log}, but it only displays the newest
515 revision in the repository.
516 \interaction{tour.tip}
517 We refer to the newest revision in the repository as the tip revision,
518 or simply the tip.
520 \section{Sharing changes}
522 We mentioned earlier that repositories in Mercurial are
523 self-contained. This means that the changeset we just created exists
524 only in our \dirname{my-hello} repository. Let's look at a few ways
525 that we can propagate this change into other repositories.
527 \subsection{Pulling changes from another repository}
528 \label{sec:tour:pull}
530 To get started, let's clone our original \dirname{hello} repository,
531 which does not contain the change we just committed. We'll call our
532 temporary repository \dirname{hello-pull}.
533 \interaction{tour.clone-pull}
535 We'll use the \hgcmd{pull} command to bring changes from
536 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
537 pulling unknown changes into a repository is a somewhat scary
538 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
539 what changes the \hgcmd{pull} command \emph{would} pull into the
540 repository, without actually pulling the changes in.
541 \interaction{tour.incoming}
542 (Of course, someone could cause more changesets to appear in the
543 repository that we ran \hgcmd{incoming} in, before we get a chance to
544 \hgcmd{pull} the changes, so that we could end up pulling changes that we
545 didn't expect.)
547 Bringing changes into a repository is a simple matter of running the
548 \hgcmd{pull} command, and telling it which repository to pull from.
549 \interaction{tour.pull}
550 As you can see from the before-and-after output of \hgcmd{tip}, we
551 have successfully pulled changes into our repository. There remains
552 one step before we can see these changes in the working directory.
554 \subsection{Updating the working directory}
556 We have so far glossed over the relationship between a repository and
557 its working directory. The \hgcmd{pull} command that we ran in
558 section~\ref{sec:tour:pull} brought changes into the repository, but
559 if we check, there's no sign of those changes in the working
560 directory. This is because \hgcmd{pull} does not (by default) touch
561 the working directory. Instead, we use the \hgcmd{update} command to
562 do this.
563 \interaction{tour.update}
565 It might seem a bit strange that \hgcmd{pull} doesn't update the
566 working directory automatically. There's actually a good reason for
567 this: you can use \hgcmd{update} to update the working directory to
568 the state it was in at \emph{any revision} in the history of the
569 repository. If you had the working directory updated to an old
570 revision---to hunt down the origin of a bug, say---and ran a
571 \hgcmd{pull} which automatically updated the working directory to a
572 new revision, you might not be terribly happy.
574 However, since pull-then-update is such a common thing to do,
575 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
576 option to \hgcmd{pull}.
577 \begin{codesample2}
578 hg pull -u
579 \end{codesample2}
580 If you look back at the output of \hgcmd{pull} in
581 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
582 you can see that it printed a helpful reminder that we'd have to take
583 an explicit step to update the working directory:
584 \begin{codesample2}
585 (run 'hg update' to get a working copy)
586 \end{codesample2}
588 To find out what revision the working directory is at, use the
589 \hgcmd{parents} command.
590 \interaction{tour.parents}
591 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
592 arrows connecting each changeset. The node that the arrow leads
593 \emph{from} in each case is a parent, and the node that the arrow
594 leads \emph{to} is its child. The working directory has a parent in
595 just the same way; this is the changeset that the working directory
596 currently contains.
598 To update the working directory to a particular revision, give a
599 revision number or changeset~ID to the \hgcmd{update} command.
600 \interaction{tour.older}
601 If you omit an explicit revision, \hgcmd{update} will update to the
602 tip revision, as shown by the second call to \hgcmd{update} in the
603 example above.
605 \subsection{Pushing changes to another repository}
607 Mercurial lets us push changes to another repository, from the
608 repository we're currently visiting. As with the example of
609 \hgcmd{pull} above, we'll create a temporary repository to push our
610 changes into.
611 \interaction{tour.clone-push}
612 The \hgcmd{outgoing} command tells us what changes would be pushed
613 into another repository.
614 \interaction{tour.outgoing}
615 And the \hgcmd{push} command does the actual push.
616 \interaction{tour.push}
617 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
618 working directory in the repository that it's pushing changes into.
619 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
620 option that updates the other repository's working directory.)
622 What happens if we try to pull or push changes and the receiving
623 repository already has those changes? Nothing too exciting.
624 \interaction{tour.push.nothing}
626 \subsection{Sharing changes over a network}
628 The commands we have covered in the previous few sections are not
629 limited to working with local repositories. Each works in exactly the
630 same fashion over a network connection; simply pass in a URL instead
631 of a local path.
632 \interaction{tour.outgoing.net}
633 In this example, we can see what changes we could push to the remote
634 repository, but the repository is understandably not set up to let
635 anonymous users push to it.
636 \interaction{tour.push.net}
638 %%% Local Variables:
639 %%% mode: latex
640 %%% TeX-master: "00book"
641 %%% End: