hgbook
view fr/tour-basic.tex @ 949:233537f6a12c
Removing useless carriage return and double entry in the menu
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Mon Feb 16 23:40:10 2009 +0100 (2009-02-16) |
| parents | afdc168fa06c |
| children | f6874ae04dde |
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}
282 Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce
283 que vous cherchez. Vous aurez probablement besoin de voir un description
284 complète du changement, ou une liste des fichiers modifiés. Si vous
285 cherchez à déterminer si ce \textit{changeset} est bien celui que vous
286 recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou
287 \hgopt{--verbose}) vous donne des informations supplémentaires.
288 \interaction{tour.log-v}
290 Si vous voulez voir à la fois la description et le contenu d'une
291 modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).
292 Ceci affiche le contenu d'une modification comme un \emph{diff unifié}
293 \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff
294 unifié avant, consulter la section~\ref{sec:mq:patch} pour rapide
295 survol).
297 \interaction{tour.log-vp}
299 \section{Tout sur les options de commandes}
302 Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
303 étudions un moment comment elles fonctionnent de manière générale, vous
304 trouverez ça probablement utile pour la suite de notre parcours.
306 Mercurial a une manière approche directe et cohérente pour interpréter
307 les options que vous passez aux commandes. Il suit une convention commune
308 à la plupart des systèmes Unix et Linux modernes.
310 \begin{itemize}
311 \item Chaque option a un nom complet. Par exemple, comme nous l'avons déjà
312 vu, la command e\hgcmd{log} accepte l'option \hgopt{log}{--rev}.
313 \item La plupart des options dispose de noms abrégés, aussi. Au lieu d'utiliser
314 \hgopt{log}{--rev}, vous pouvez utiliser \hgopt{log}{-r}. (Les options qui
315 n'ont pas de noms abrégés sont généralement rarement utilisés, c'est pour ça).
316 \item Les noms complets commence par deux tirets (i.e.~\hgopt{log}{--rev}),
317 alors que les options courtes commencent avec un seul (i.e.~\hgopt{log}{-r}).
318 \item Les noms des options sont cohérent entre les commandes. Par exemple,
319 chaque commande qui accepte un \textit{changeset~ID} ou une numéro de révision
320 accepte aussi \hgopt{log}{-r} et \hgopt{log}{--rev} comme arguments.
321 %TODO: Small mistake here, shouldn't have log here... shouldn't it ?
322 \end{itemize}
324 Dans les exemples de ce libre, j'utilise les noms abrégés plutôt que les noms
325 complet. Ceci est une préférence personnelle, par une recommandation.
327 La plupart des commandes qui affiche une quelquonque sortie à l'écran,
328 afficheront plus avec l'option \hggopt{-v} (ou \hggopt{--verbose}), et
329 mois avec l'option \hggopt{-q} (ou \hggopt{--quiet}).
331 \section{Faire et vérifier des modifications}
333 Maintenant que nous avons une bonne idée de commande consulter l'historique
334 de Mercurial, regardons comment faire des modifications et les examiner.
336 La première chose que nous allons faire c'est isoler notre expérience dans
337 un dépôt à part. Nous allons utiliser la commande \hgcmd{clone}, mais nous
338 n'avons pas besoin de faire une copie de dépôt distant. Comme nous avons
339 déjà une copie locale, nous pouvons juste faire un clone de celle ci à la
340 place. C'est beaucoup plus rapide que de faire une copie à travers le
341 réseau, et un dépôt cloné localement prend moins d'espace disques aussi.
343 \interaction{tour.reclone}
345 On notera au passage qu'il est souvent considéré comme une bonne pratique
346 de conserver une copie ``immaculée'' du dépôt distant, à partir de laquelle
347 vous pourrez faire des copies locales temporaires pour créer des ``bacs à
348 sable'' pour chaque tâche sur laquelle vous souhaitez travailler. Ceci vous
349 permet de travailler sur plusieur choses en parallèle, chacune isolée les
350 unes des autres en attendant que ces tâches soient fini et que vous soyez
351 prêt à les réintégrer. Parce que les copies locales sont peu coûteuse, il
352 est très rapide de créer ou détruire des dépôts dès que vous en avez besoin.
354 %% Note: la dernière phrase n'est pas une traduction littérale, mais je
355 %% pense qu'elle exprime plus clairement en français ce que veut dire son
356 %% équivalent anglais.
358 Dans notre dépôt \dirname{my-hello}, nous avons un fichier \filename{hello.c}
359 qui contient le classique programme ``hello, world''. Nous allons utiliser
360 l'ancienne et vénérable commande \command{sed} pour l'éditer pour qu'il
361 affiche une seconde ligne à l'écran. (J'utilise \command{sed} seulement parce
362 qu'il est facile d'écrire des exemples sous formes de script ainsi. Comme
363 vous n'avez pas ces contraintes, vous n'utiliserez probablement pas \command{sed}
364 mais plutôt votre éditeur de texte favori).
366 \interaction{tour.sed}
368 La commande \hgcmd{status} de Mercurial nous dira de quels fichiers Mercurial
369 s'occupe au sein de ce dépôt.
370 \interaction{tour.status}
371 La commande \hgcmd{status} n'affiche rien sur la sortie pour quelques fichiers
372 mais une ligne commence par ``\texttt{M}'' for \filename{hello.c}. À moins que
373 vous ne lui indiquiez de le faire, \hgcmd{status} n'affichera aucune sortie
374 pour les fichiers qui n'ont pas été modifiés.
376 Le caractère ``\texttt{M}'' indique que Mercurial a remarqué que nous avions
377 modifié le fichier \filename{hello.c}. Nous n'avons pas besoin d'\emph{informer}
378 Mercurial que nous allons modifier un fichier avant de le faire, ou que nous
379 venons de le modifier, il est capable de s'en rendre compte tout seul.
381 C'est pratique de savoir que nous avons modifié \filename{hello.c}, mais il
382 serait encore plus pratique de savoir ce que nous avons modifié exactement. Pour
383 cela, nous avons la commande \hgcmd{diff}.
385 \interaction{tour.diff}
387 \section{Enregister les modifications dans un nouveau \textit{changeset}}
389 Nous pouvons modifier des fichiers, compiler et tester nos modifications,
390 et utiliser les commandes \hgcmd{status} and \hgcmd{diff} pour voir les
391 modifications effectués, jusqu'au moment où nous serons assez satisfait
392 pour décider d'enregister notre travail dans un \textit{changeset}.
394 La commande \hgcmd{commit} vous laisse créer un nouveau \textit{changeset},
395 nous désignerons généralement cette opération par ``faire un commit'' ou
396 ``commité''\footnote{NdT: De mon expérience, la plupart des francophones
397 utilisent régulièrement, à l'oral, cette expression, mais bien évidement
398 il ne s'agit pas d'un terme terminologiquement correct, ni même français.}
400 \subsection{Définir le nom d'utilisateur}
402 Quand vous exécuter la commande \hgcmd{commit} pour la première fois, elle
403 n'est pas garanti de réussir. Mercurial enregistre votre nom et votre
404 adresse avec chaque modification que vous effectuez, de manière à ce que
405 vous soyez capable (ou d'autres le soient) de savoir qui a fait quelle
406 modification. Mercurial essaye automatiquement de découvrir un nom
407 d'utilisateur qui est un minimum de sense pour effectuer l'opération
408 de \textit{commit} avec. Il va essayer chacune des méthodes suivantes,
409 dans l'ordre:
410 \begin{enumerate}
411 \item Si vous spécifiez l'option \hgopt{commit}{-u} avec la commande
412 \hgcmd{commit}, suivi d'un nom d'utilisateur, ceci aura toujours la
413 priorité sur les autres méthodes ci dessous.
414 \item Si vous avez défini une variable d'environement \envar{HGUSER},
415 c'est cette valeur qui est alors utilisée.
416 \item Si vous créer un fichier nommé \sfilename{.hgrc} dans votre
417 répertoire \textit{home}, avec une entrée \rcitem{ui}{username},
418 c'est la valeur associée qui sera utilisée. Pour voir à quoi
419 ressemble le contenu de ce fichier regardez la
420 section~\ref{sec:tour-basic:username} ci dessous.
421 \item Si vous avez défini une variable d'environement \envar{EMAIL}
422 celle ci sera utilisée ensuite.
423 \item Enfin, Mercurial interrogera votre système pour trouver votre
424 nom d'utilisateur local ainsi que le nom de la machine hôte, et il
425 un nom d'utilisateur à partir de ces composants. Comme il arrive
426 souvent que ce genre de noms soit totalement inutile, il vous
427 préviendra en affichant un message d'avertissement.
428 \end{enumerate}
430 Si tous ces méchanismes échouent, Mercurial n'exécutera pas la commande,
431 affichant un message d'erreur. Dans ce cas, il ne vous laissera pas
432 effectuer de \textit{commit} tant que vous n'aurez pas défini un nom
433 d'utilisateur.
435 Vous devriez penser à utiliser la variable d'environement \envar{HGUSER}
436 et l'option \hgopt{commit}{-u} comme moyen pour \emph{changer le nom
437 d'utilisateur} par défaut. Pour une utilisation normale, le plus simple
438 et robuste manière d'opérer est de créer un fichier \sfilename{.hgrc},
439 voir ci dessous pour les détails à ce sujet.
441 \subsubsection{Creating a Mercurial configuration file}
442 \label{sec:tour-basic:username}
444 To set a user name, use your favourite editor to create a file called
445 \sfilename{.hgrc} in your home directory. Mercurial will use this
446 file to look up your personalised configuration settings. The initial
447 contents of your \sfilename{.hgrc} should look like this.
448 \begin{codesample2}
449 # This is a Mercurial configuration file.
450 [ui]
451 username = Firstname Lastname <email.address@domain.net>
452 \end{codesample2}
453 The ``\texttt{[ui]}'' line begins a \emph{section} of the config file,
454 so you can read the ``\texttt{username = ...}'' line as meaning ``set
455 the value of the \texttt{username} item in the \texttt{ui} section''.
456 A section continues until a new section begins, or the end of the
457 file. Mercurial ignores empty lines and treats any text from
458 ``\texttt{\#}'' to the end of a line as a comment.
460 \subsubsection{Choosing a user name}
462 You can use any text you like as the value of the \texttt{username}
463 config item, since this information is for reading by other people,
464 but for interpreting by Mercurial. The convention that most people
465 follow is to use their name and email address, as in the example
466 above.
468 \begin{note}
469 Mercurial's built-in web server obfuscates email addresses, to make
470 it more difficult for the email harvesting tools that spammers use.
471 This reduces the likelihood that you'll start receiving more junk
472 email if you publish a Mercurial repository on the web.
473 \end{note}
475 \subsection{Writing a commit message}
477 When we commit a change, Mercurial drops us into a text editor, to
478 enter a message that will describe the modifications we've made in
479 this changeset. This is called the \emph{commit message}. It will be
480 a record for readers of what we did and why, and it will be printed by
481 \hgcmd{log} after we've finished committing.
482 \interaction{tour.commit}
484 The editor that the \hgcmd{commit} command drops us into will contain
485 an empty line, followed by a number of lines starting with
486 ``\texttt{HG:}''.
487 \begin{codesample2}
488 \emph{empty line}
489 HG: changed hello.c
490 \end{codesample2}
491 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
492 them only to tell us which files it's recording changes to. Modifying
493 or deleting these lines has no effect.
495 \subsection{Writing a good commit message}
497 Since \hgcmd{log} only prints the first line of a commit message by
498 default, it's best to write a commit message whose first line stands
499 alone. Here's a real example of a commit message that \emph{doesn't}
500 follow this guideline, and hence has a summary that is not readable.
501 \begin{codesample2}
502 changeset: 73:584af0e231be
503 user: Censored Person <censored.person@example.org>
504 date: Tue Sep 26 21:37:07 2006 -0700
505 summary: include buildmeister/commondefs. Add an exports and install
506 \end{codesample2}
508 As far as the remainder of the contents of the commit message are
509 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
510 interpret or care about the contents of the commit message, though
511 your project may have policies that dictate a certain kind of
512 formatting.
514 My personal preference is for short, but informative, commit messages
515 that tell me something that I can't figure out with a quick glance at
516 the output of \hgcmdargs{log}{--patch}.
518 \subsection{Aborting a commit}
520 If you decide that you don't want to commit while in the middle of
521 editing a commit message, simply exit from your editor without saving
522 the file that it's editing. This will cause nothing to happen to
523 either the repository or the working directory.
525 If we run the \hgcmd{commit} command without any arguments, it records
526 all of the changes we've made, as reported by \hgcmd{status} and
527 \hgcmd{diff}.
529 \subsection{Admiring our new handiwork}
531 Once we've finished the commit, we can use the \hgcmd{tip} command to
532 display the changeset we just created. This command produces output
533 that is identical to \hgcmd{log}, but it only displays the newest
534 revision in the repository.
535 \interaction{tour.tip}
536 We refer to the newest revision in the repository as the tip revision,
537 or simply the tip.
539 \section{Sharing changes}
541 We mentioned earlier that repositories in Mercurial are
542 self-contained. This means that the changeset we just created exists
543 only in our \dirname{my-hello} repository. Let's look at a few ways
544 that we can propagate this change into other repositories.
546 \subsection{Pulling changes from another repository}
547 \label{sec:tour:pull}
549 To get started, let's clone our original \dirname{hello} repository,
550 which does not contain the change we just committed. We'll call our
551 temporary repository \dirname{hello-pull}.
552 \interaction{tour.clone-pull}
554 We'll use the \hgcmd{pull} command to bring changes from
555 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
556 pulling unknown changes into a repository is a somewhat scary
557 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
558 what changes the \hgcmd{pull} command \emph{would} pull into the
559 repository, without actually pulling the changes in.
560 \interaction{tour.incoming}
561 (Of course, someone could cause more changesets to appear in the
562 repository that we ran \hgcmd{incoming} in, before we get a chance to
563 \hgcmd{pull} the changes, so that we could end up pulling changes that we
564 didn't expect.)
566 Bringing changes into a repository is a simple matter of running the
567 \hgcmd{pull} command, and telling it which repository to pull from.
568 \interaction{tour.pull}
569 As you can see from the before-and-after output of \hgcmd{tip}, we
570 have successfully pulled changes into our repository. There remains
571 one step before we can see these changes in the working directory.
573 \subsection{Updating the working directory}
575 We have so far glossed over the relationship between a repository and
576 its working directory. The \hgcmd{pull} command that we ran in
577 section~\ref{sec:tour:pull} brought changes into the repository, but
578 if we check, there's no sign of those changes in the working
579 directory. This is because \hgcmd{pull} does not (by default) touch
580 the working directory. Instead, we use the \hgcmd{update} command to
581 do this.
582 \interaction{tour.update}
584 It might seem a bit strange that \hgcmd{pull} doesn't update the
585 working directory automatically. There's actually a good reason for
586 this: you can use \hgcmd{update} to update the working directory to
587 the state it was in at \emph{any revision} in the history of the
588 repository. If you had the working directory updated to an old
589 revision---to hunt down the origin of a bug, say---and ran a
590 \hgcmd{pull} which automatically updated the working directory to a
591 new revision, you might not be terribly happy.
593 However, since pull-then-update is such a common thing to do,
594 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
595 option to \hgcmd{pull}.
596 \begin{codesample2}
597 hg pull -u
598 \end{codesample2}
599 If you look back at the output of \hgcmd{pull} in
600 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
601 you can see that it printed a helpful reminder that we'd have to take
602 an explicit step to update the working directory:
603 \begin{codesample2}
604 (run 'hg update' to get a working copy)
605 \end{codesample2}
607 To find out what revision the working directory is at, use the
608 \hgcmd{parents} command.
609 \interaction{tour.parents}
610 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
611 arrows connecting each changeset. The node that the arrow leads
612 \emph{from} in each case is a parent, and the node that the arrow
613 leads \emph{to} is its child. The working directory has a parent in
614 just the same way; this is the changeset that the working directory
615 currently contains.
617 To update the working directory to a particular revision, give a
618 revision number or changeset~ID to the \hgcmd{update} command.
619 \interaction{tour.older}
620 If you omit an explicit revision, \hgcmd{update} will update to the
621 tip revision, as shown by the second call to \hgcmd{update} in the
622 example above.
624 \subsection{Pushing changes to another repository}
626 Mercurial lets us push changes to another repository, from the
627 repository we're currently visiting. As with the example of
628 \hgcmd{pull} above, we'll create a temporary repository to push our
629 changes into.
630 \interaction{tour.clone-push}
631 The \hgcmd{outgoing} command tells us what changes would be pushed
632 into another repository.
633 \interaction{tour.outgoing}
634 And the \hgcmd{push} command does the actual push.
635 \interaction{tour.push}
636 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
637 working directory in the repository that it's pushing changes into.
638 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
639 option that updates the other repository's working directory.)
641 What happens if we try to pull or push changes and the receiving
642 repository already has those changes? Nothing too exciting.
643 \interaction{tour.push.nothing}
645 \subsection{Sharing changes over a network}
647 The commands we have covered in the previous few sections are not
648 limited to working with local repositories. Each works in exactly the
649 same fashion over a network connection; simply pass in a URL instead
650 of a local path.
651 \interaction{tour.outgoing.net}
652 In this example, we can see what changes we could push to the remote
653 repository, but the repository is understandably not set up to let
654 anonymous users push to it.
655 \interaction{tour.push.net}
657 %%% Local Variables:
658 %%% mode: latex
659 %%% TeX-master: "00book"
660 %%% End: