hgbook
view fr/tour-basic.tex @ 946:1f2044943861
Oops, overwrite some of my translation by adding Hugues works... Corrected.
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Mon Feb 16 18:51:52 2009 +0100 (2009-02-16) |
| parents | 3344e9987bf2 |
| children | f2670f1d13f1 |
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 Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce
282 que vous cherchez. Vous aurez probablement besoin de voir un description
283 complète du changement, ou une liste des fichiers modifiés. Si vous
284 cherchez à déterminer si ce \textit{changeset} est bien celui que vous
285 recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou
286 \hgopt{--verbose}) vous donne des informations supplémentaires.
288 Si vous voulez voir à la fois la description et le contenu d'une
289 modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).
290 Ceci affiche le contenu d'une modification comme un \emph{diff unifié}
291 \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff
292 unifié avant, consulter la section~\ref{sec:mq:patch} pour rapide
293 survol).
296 \section{Tout sur les options de commandes}
298 Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
299 étudions un moment comment elles fonctionnent de manière générale, vous
300 trouverez ça probablement utile pour la suite de notre parcours.
302 Mercurial a une manière approche directe et cohérente pour interpréter
303 les options que vous passez aux commandes. Il suit une convention commune
304 à la plupart des systèmes Unix et Linux modernes.
306 \begin{itemize}
307 \item Every option has a long name. For example, as we've already
308 seen, the \hgcmd{log} command accepts a \hgopt{log}{--rev} option.
309 \item Most options have short names, too. Instead of
310 \hgopt{log}{--rev}, we can use \hgopt{log}{-r}. (The reason that
311 some options don't have short names is that the options in question
312 are rarely used.)
313 \item Long options start with two dashes (e.g.~\hgopt{log}{--rev}),
314 while short options start with one (e.g.~\hgopt{log}{-r}).
315 \item Option naming and usage is consistent across commands. For
316 example, every command that lets you specify a changeset~ID or
317 revision number accepts both \hgopt{log}{-r} and \hgopt{log}{--rev}
318 arguments.
319 \end{itemize}
320 In the examples throughout this book, I use short options instead of
321 long. This just reflects my own preference, so don't read anything
322 significant into it.
324 Most commands that print output of some kind will print more output
325 when passed a \hggopt{-v} (or \hggopt{--verbose}) option, and less
326 when passed \hggopt{-q} (or \hggopt{--quiet}).
328 \section{Making and reviewing changes}
330 Now that we have a grasp of viewing history in Mercurial, let's take a
331 look at making some changes and examining them.
333 The first thing we'll do is isolate our experiment in a repository of
334 its own. We use the \hgcmd{clone} command, but we don't need to
335 clone a copy of the remote repository. Since we already have a copy
336 of it locally, we can just clone that instead. This is much faster
337 than cloning over the network, and cloning a local repository uses
338 less disk space in most cases, too.
339 \interaction{tour.reclone}
340 As an aside, it's often good practice to keep a ``pristine'' copy of a
341 remote repository around, which you can then make temporary clones of
342 to create sandboxes for each task you want to work on. This lets you
343 work on multiple tasks in parallel, each isolated from the others
344 until it's complete and you're ready to integrate it back. Because
345 local clones are so cheap, there's almost no overhead to cloning and
346 destroying repositories whenever you want.
348 In our \dirname{my-hello} repository, we have a file
349 \filename{hello.c} that contains the classic ``hello, world'' program.
350 Let's use the ancient and venerable \command{sed} command to edit this
351 file so that it prints a second line of output. (I'm only using
352 \command{sed} to do this because it's easy to write a scripted example
353 this way. Since you're not under the same constraint, you probably
354 won't want to use \command{sed}; simply use your preferred text editor to
355 do the same thing.)
356 \interaction{tour.sed}
358 Mercurial's \hgcmd{status} command will tell us what Mercurial knows
359 about the files in the repository.
360 \interaction{tour.status}
361 The \hgcmd{status} command prints no output for some files, but a line
362 starting with ``\texttt{M}'' for \filename{hello.c}. Unless you tell
363 it to, \hgcmd{status} will not print any output for files that have
364 not been modified.
366 The ``\texttt{M}'' indicates that Mercurial has noticed that we
367 modified \filename{hello.c}. We didn't need to \emph{inform}
368 Mercurial that we were going to modify the file before we started, or
369 that we had modified the file after we were done; it was able to
370 figure this out itself.
372 It's a little bit helpful to know that we've modified
373 \filename{hello.c}, but we might prefer to know exactly \emph{what}
374 changes we've made to it. To do this, we use the \hgcmd{diff}
375 command.
376 \interaction{tour.diff}
378 \section{Recording changes in a new changeset}
380 We can modify files, build and test our changes, and use
381 \hgcmd{status} and \hgcmd{diff} to review our changes, until we're
382 satisfied with what we've done and arrive at a natural stopping point
383 where we want to record our work in a new changeset.
385 The \hgcmd{commit} command lets us create a new changeset; we'll
386 usually refer to this as ``making a commit'' or ``committing''.
388 \subsection{Setting up a username}
390 When you try to run \hgcmd{commit} for the first time, it is not
391 guaranteed to succeed. Mercurial records your name and address with
392 each change that you commit, so that you and others will later be able
393 to tell who made each change. Mercurial tries to automatically figure
394 out a sensible username to commit the change with. It will attempt
395 each of the following methods, in order:
396 \begin{enumerate}
397 \item If you specify a \hgopt{commit}{-u} option to the \hgcmd{commit}
398 command on the command line, followed by a username, this is always
399 given the highest precedence.
400 \item If you have set the \envar{HGUSER} environment variable, this is
401 checked next.
402 \item If you create a file in your home directory called
403 \sfilename{.hgrc}, with a \rcitem{ui}{username} entry, that will be
404 used next. To see what the contents of this file should look like,
405 refer to section~\ref{sec:tour-basic:username} below.
406 \item If you have set the \envar{EMAIL} environment variable, this
407 will be used next.
408 \item Mercurial will query your system to find out your local user
409 name and host name, and construct a username from these components.
410 Since this often results in a username that is not very useful, it
411 will print a warning if it has to do this.
412 \end{enumerate}
413 If all of these mechanisms fail, Mercurial will fail, printing an
414 error message. In this case, it will not let you commit until you set
415 up a username.
417 You should think of the \envar{HGUSER} environment variable and the
418 \hgopt{commit}{-u} option to the \hgcmd{commit} command as ways to
419 \emph{override} Mercurial's default selection of username. For normal
420 use, the simplest and most robust way to set a username for yourself
421 is by creating a \sfilename{.hgrc} file; see below for details.
423 \subsubsection{Creating a Mercurial configuration file}
424 \label{sec:tour-basic:username}
426 To set a user name, use your favourite editor to create a file called
427 \sfilename{.hgrc} in your home directory. Mercurial will use this
428 file to look up your personalised configuration settings. The initial
429 contents of your \sfilename{.hgrc} should look like this.
430 \begin{codesample2}
431 # This is a Mercurial configuration file.
432 [ui]
433 username = Firstname Lastname <email.address@domain.net>
434 \end{codesample2}
435 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
436 so you can read the ``\texttt{username = ...}'' line as meaning ``set
437 the value of the \texttt{username} item in the \texttt{ui} section''.
438 A section continues until a new section begins, or the end of the
439 file. Mercurial ignores empty lines and treats any text from
440 ``\texttt{\#}'' to the end of a line as a comment.
442 \subsubsection{Choosing a user name}
444 You can use any text you like as the value of the \texttt{username}
445 config item, since this information is for reading by other people,
446 but for interpreting by Mercurial. The convention that most people
447 follow is to use their name and email address, as in the example
448 above.
450 \begin{note}
451 Mercurial's built-in web server obfuscates email addresses, to make
452 it more difficult for the email harvesting tools that spammers use.
453 This reduces the likelihood that you'll start receiving more junk
454 email if you publish a Mercurial repository on the web.
455 \end{note}
457 \subsection{Writing a commit message}
459 When we commit a change, Mercurial drops us into a text editor, to
460 enter a message that will describe the modifications we've made in
461 this changeset. This is called the \emph{commit message}. It will be
462 a record for readers of what we did and why, and it will be printed by
463 \hgcmd{log} after we've finished committing.
464 \interaction{tour.commit}
466 The editor that the \hgcmd{commit} command drops us into will contain
467 an empty line, followed by a number of lines starting with
468 ``\texttt{HG:}''.
469 \begin{codesample2}
470 \emph{empty line}
471 HG: changed hello.c
472 \end{codesample2}
473 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
474 them only to tell us which files it's recording changes to. Modifying
475 or deleting these lines has no effect.
477 \subsection{Writing a good commit message}
479 Since \hgcmd{log} only prints the first line of a commit message by
480 default, it's best to write a commit message whose first line stands
481 alone. Here's a real example of a commit message that \emph{doesn't}
482 follow this guideline, and hence has a summary that is not readable.
483 \begin{codesample2}
484 changeset: 73:584af0e231be
485 user: Censored Person <censored.person@example.org>
486 date: Tue Sep 26 21:37:07 2006 -0700
487 summary: include buildmeister/commondefs. Add an exports and install
488 \end{codesample2}
490 As far as the remainder of the contents of the commit message are
491 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
492 interpret or care about the contents of the commit message, though
493 your project may have policies that dictate a certain kind of
494 formatting.
496 My personal preference is for short, but informative, commit messages
497 that tell me something that I can't figure out with a quick glance at
498 the output of \hgcmdargs{log}{--patch}.
500 \subsection{Aborting a commit}
502 If you decide that you don't want to commit while in the middle of
503 editing a commit message, simply exit from your editor without saving
504 the file that it's editing. This will cause nothing to happen to
505 either the repository or the working directory.
507 If we run the \hgcmd{commit} command without any arguments, it records
508 all of the changes we've made, as reported by \hgcmd{status} and
509 \hgcmd{diff}.
511 \subsection{Admiring our new handiwork}
513 Once we've finished the commit, we can use the \hgcmd{tip} command to
514 display the changeset we just created. This command produces output
515 that is identical to \hgcmd{log}, but it only displays the newest
516 revision in the repository.
517 \interaction{tour.tip}
518 We refer to the newest revision in the repository as the tip revision,
519 or simply the tip.
521 \section{Sharing changes}
523 We mentioned earlier that repositories in Mercurial are
524 self-contained. This means that the changeset we just created exists
525 only in our \dirname{my-hello} repository. Let's look at a few ways
526 that we can propagate this change into other repositories.
528 \subsection{Pulling changes from another repository}
529 \label{sec:tour:pull}
531 To get started, let's clone our original \dirname{hello} repository,
532 which does not contain the change we just committed. We'll call our
533 temporary repository \dirname{hello-pull}.
534 \interaction{tour.clone-pull}
536 We'll use the \hgcmd{pull} command to bring changes from
537 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
538 pulling unknown changes into a repository is a somewhat scary
539 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
540 what changes the \hgcmd{pull} command \emph{would} pull into the
541 repository, without actually pulling the changes in.
542 \interaction{tour.incoming}
543 (Of course, someone could cause more changesets to appear in the
544 repository that we ran \hgcmd{incoming} in, before we get a chance to
545 \hgcmd{pull} the changes, so that we could end up pulling changes that we
546 didn't expect.)
548 Bringing changes into a repository is a simple matter of running the
549 \hgcmd{pull} command, and telling it which repository to pull from.
550 \interaction{tour.pull}
551 As you can see from the before-and-after output of \hgcmd{tip}, we
552 have successfully pulled changes into our repository. There remains
553 one step before we can see these changes in the working directory.
555 \subsection{Updating the working directory}
557 We have so far glossed over the relationship between a repository and
558 its working directory. The \hgcmd{pull} command that we ran in
559 section~\ref{sec:tour:pull} brought changes into the repository, but
560 if we check, there's no sign of those changes in the working
561 directory. This is because \hgcmd{pull} does not (by default) touch
562 the working directory. Instead, we use the \hgcmd{update} command to
563 do this.
564 \interaction{tour.update}
566 It might seem a bit strange that \hgcmd{pull} doesn't update the
567 working directory automatically. There's actually a good reason for
568 this: you can use \hgcmd{update} to update the working directory to
569 the state it was in at \emph{any revision} in the history of the
570 repository. If you had the working directory updated to an old
571 revision---to hunt down the origin of a bug, say---and ran a
572 \hgcmd{pull} which automatically updated the working directory to a
573 new revision, you might not be terribly happy.
575 However, since pull-then-update is such a common thing to do,
576 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
577 option to \hgcmd{pull}.
578 \begin{codesample2}
579 hg pull -u
580 \end{codesample2}
581 If you look back at the output of \hgcmd{pull} in
582 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
583 you can see that it printed a helpful reminder that we'd have to take
584 an explicit step to update the working directory:
585 \begin{codesample2}
586 (run 'hg update' to get a working copy)
587 \end{codesample2}
589 To find out what revision the working directory is at, use the
590 \hgcmd{parents} command.
591 \interaction{tour.parents}
592 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
593 arrows connecting each changeset. The node that the arrow leads
594 \emph{from} in each case is a parent, and the node that the arrow
595 leads \emph{to} is its child. The working directory has a parent in
596 just the same way; this is the changeset that the working directory
597 currently contains.
599 To update the working directory to a particular revision, give a
600 revision number or changeset~ID to the \hgcmd{update} command.
601 \interaction{tour.older}
602 If you omit an explicit revision, \hgcmd{update} will update to the
603 tip revision, as shown by the second call to \hgcmd{update} in the
604 example above.
606 \subsection{Pushing changes to another repository}
608 Mercurial lets us push changes to another repository, from the
609 repository we're currently visiting. As with the example of
610 \hgcmd{pull} above, we'll create a temporary repository to push our
611 changes into.
612 \interaction{tour.clone-push}
613 The \hgcmd{outgoing} command tells us what changes would be pushed
614 into another repository.
615 \interaction{tour.outgoing}
616 And the \hgcmd{push} command does the actual push.
617 \interaction{tour.push}
618 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
619 working directory in the repository that it's pushing changes into.
620 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
621 option that updates the other repository's working directory.)
623 What happens if we try to pull or push changes and the receiving
624 repository already has those changes? Nothing too exciting.
625 \interaction{tour.push.nothing}
627 \subsection{Sharing changes over a network}
629 The commands we have covered in the previous few sections are not
630 limited to working with local repositories. Each works in exactly the
631 same fashion over a network connection; simply pass in a URL instead
632 of a local path.
633 \interaction{tour.outgoing.net}
634 In this example, we can see what changes we could push to the remote
635 repository, but the repository is understandably not set up to let
636 anonymous users push to it.
637 \interaction{tour.push.net}
639 %%% Local Variables:
640 %%% mode: latex
641 %%% TeX-master: "00book"
642 %%% End: