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