hgbook
view fr/tour-basic.tex @ 950:f6874ae04dde
Relecture orthographique et terminologique
| author | "Hugues Frachon" <huguesfrachon@gmail.com> |
|---|---|
| date | Tue Feb 17 18:53:33 2009 +0100 (2009-02-17) |
| parents | 233537f6a12c |
| children | de3b3aaaa159 |
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. Vous pouvez renommer ou effacer ce répertoire
124 '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 juste 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ée 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 libres
149 d'expérimenter avec ce dépôt, confiants dans le fait qu'il s'agit d'un
150 ``bac à sable'' qui n'affectera personne d'autre.
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é \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 seuls propres à Mercurial. Tous les autres fichiers et répertoires 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 tous les fichiers et les répertoires qui coexistent
165 avec lui, sont désignés 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écimale. 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éé 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éé, ainsi que le \textit{timezone} dans laquelle il a été créé. %%%TODO: Translate 'timezone' properly
197 (La date et l'heure sont locales à cette \textit{timezone}, elles indiquent
198 donc quelle date et quelle il était pour la personne qui a créé ce %%%TODO: je suppose (quelle "heure")
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}%%%TODO: je propose : "discussion" (3 noms communs)
223 Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique
224 est la source de bien des erreurs terminologiques (pourquoi utiliser un
225 seul terme quand quatre feront l'affaire ?), la gestion de version a une
226 variété de mots 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 %%%TODO: ça ne veut rien dire: il faut supprimer une des personnes : soit "quelqu'un",
229 % soit "à d'autres personnes"
230 vous constaterez que souvent le mot ``\textit{changeset}'' est compressé simplement
231 en ``change'' ou (à l'écrit) ``cset'', et même parfois un
232 \textit{changeset} simplement ``révision'', abrégé en ``rev''.
234 Bien que le \emph{mot} que vous utilisez pour désigner le concept de
235 \textit{changeset} importe peu, l'\emph{identifiant} que vous utilisez
236 pour désigner un \emph{spécifique} \textit{spécifique} a une grande
237 importance. Rappelez vous que le \textit{changeset} affiché par la
238 commande \hgcmd{log} identifie un \textit{changeset} à la fois avec
239 un numéro de révision et une séquence hexadécimale.
241 \begin{itemize}
242 \item Le numéro de révision est \emph{seulement valable dans ce dépôt},
243 \item alors que la séquence hexadécimale est un \emph{identifiant
244 permanent, et invariant } qui pourra toujours être associé au
245 \textit{changeset} exact de \emph{chaque} copie de votre dépôt.
246 \end{itemize}
248 La distinction est importante. Si vous envoyez un email à quelqu'un en
249 parlant de la ``révision 33'', il est très probable que sa révision~33
250 \emph{ne sera pas la même} que la votre. La raison de ceci est que le
251 numéro de révision dépend de l'ordre dans lequel les modifications sont
252 arrivées dans le dépôt, et il n'y a aucune garantie que les mêmes changements
253 soient arrivés dans le même ordre dans différents dépôts. Trois modifications
254 $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans
255 un autre comme $1,0,2$.
257 Mercurial utilise les numéro de révision uniquement comme des raccourcis
258 pratiques. Si vous devez disctuer d'un \textit{changeset} avec quelqu'un,
259 our faire un enregistrement d'un \textit{changeset} pour une quelquonque %%%TODO: our : "pour" ou "ou"
260 raison (par exemple, un rapport de \textit{bug}), utilisez la séquence
261 hexadécimale.
263 \subsection{Afficher une révision spécifique}
265 Pour réduire la sortie de \hgcmd{log} à une seule révision, utilisez
266 l'option \hgopt{log}{-r} (ou \hgopt{log}{--rev}). Vous pouvez utiliser
267 le numéro de révision ou la séquence hexadécimale comme identifiant, et
268 vous demandez autant de révisions que vous le souhaitez.
269 \interaction{tour.log-r}
271 Si vous voulez voir l'historique de plusieurs révisions sans avoir à
272 les énumérer, vous pouvez utiliser la \emph{\textit{range notation}}
273 \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le
274 laisse en anglais} qui vous permet d'exprimer l'idée ``je veux toutes
275 les révisions entre $a$ et $b$, inclus''.
276 \interaction{tour.log.range}
277 Mercurial respecte aussi l'ordre dans lequel vous spécifiez les
278 révisions, ainsi \hgcmdargs{log}{-r 2:4} affichera $2,3,4$ alors que
279 \hgcmdargs{log}{-r 4:2} affichera $4,3,2$.
281 \subsection{Informations détaillées}
284 Si le résumé affiché par \hgcmd{log} est utile si vous savez déjà ce %%%TODO: je pense que le premier "si" est de trop
285 que vous cherchez. Vous aurez probablement besoin de voir un description
286 complète du changement, ou une liste des fichiers modifiés. Si vous
287 cherchez à déterminer si ce \textit{changeset} est bien celui que vous%%%TODO: les propositions sont mal construites : après un "si...." il faut une proposition sans "si... donc ici : "si ... recherchez", ben quoi ?
288 recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou
289 \hgopt{--verbose}) vous donne des informations supplémentaires.
290 \interaction{tour.log-v}
292 Si vous voulez voir à la fois la description et le contenu d'une
293 modification, ajouter l'option \hgopt{log}{-p} (ou \hgopt{log}{--patch}).
294 Ceci affiche le contenu d'une modification comme un \emph{diff unifié}
295 \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff
296 unifié avant, consultez la section~\ref{sec:mq:patch} pour un rapide
297 survol).
299 \interaction{tour.log-vp}
301 \section{Tout sur les options de commandes}
304 Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
305 étudions un moment comment elles fonctionnent de manière générale. Vous
306 trouverez ça probablement utile pour la suite de notre parcours.
308 Mercurial a une manière approche directe et cohérente pour interpréter %%%TODO: une manière d'approche ?
309 les options que vous passez aux commandes. Il suit une convention commune
310 à la plupart des systèmes Unix et Linux modernes.
312 \begin{itemize}
313 \item Chaque option a un nom complet. Par exemple, comme nous l'avons déjà
314 vu, la command e\hgcmd{log} accepte l'option \hgopt{log}{--rev}.%%%TODO: commande ou command e\hgcmd...?
315 \item La plupart des options disposent de noms abrégés. Aussi, au lieu d'utiliser
316 \hgopt{log}{--rev}, vous pouvez utiliser \hgopt{log}{-r}. (Les options qui
317 n'ont pas de noms abrégés sont généralement rarement utilisées, c'est pour ça).
318 \item Les noms complets commencent par deux tirets (i.e.~\hgopt{log}{--rev}),
319 alors que les options courtes commencent avec un seul (i.e.~\hgopt{log}{-r}).
320 \item Les noms des options sont cohérents entre les commandes. Par exemple,
321 chaque commande qui accepte un \textit{changeset~ID} ou une numéro de révision
322 accepte aussi \hgopt{log}{-r} et \hgopt{log}{--rev} comme arguments.
323 %TODO: Small mistake here, shouldn't have log here... shouldn't it ?
324 \end{itemize}
326 Dans les exemples de ce livre, j'utilise les noms abrégés plutôt que les noms
327 complets. Ceci est une préférence personnelle, pas une recommandation.
329 La plupart des commandes qui affichent une quelquonque sortie à l'écran,
330 afficheront plus avec l'option \hggopt{-v} (ou \hggopt{--verbose}), et
331 moins avec l'option \hggopt{-q} (ou \hggopt{--quiet}).
333 \section{Faire et vérifier des modifications}
335 Maintenant que nous avons une bonne idée des commandes pour consulter
336 l'historique de Mercurial, regardons comment faire des modifications et
337 les examiner.
340 La première chose que nous allons faire c'est isoler notre expérience dans
341 un dépôt à part. Nous allons utiliser la commande \hgcmd{clone}, mais nous
342 n'avons pas besoin de faire une copie de dépôt distant. Comme nous avons
343 déjà une copie locale, nous pouvons juste faire un clone de celle ci à la
344 place. C'est beaucoup plus rapide que de faire une copie à travers le
345 réseau, et un dépôt cloné localement prend moins d'espace disque aussi.
347 \interaction{tour.reclone}
349 On notera au passage qu'il est souvent considéré comme une bonne pratique
350 de conserver une copie ``immaculée'' du dépôt distant, à partir de laquelle
351 vous pourrez faire des copies locales temporaires pour créer des ``bacs à
352 sable'' pour chaque tâche sur laquelle vous souhaitez travailler. Ceci vous
353 permet de travailler sur plusieurs choses en parallèle, chacune isolée les
354 unes des autres en attendant que ces tâches soient finies et que vous soyez
355 prêt à les réintégrer. Parce que les copies locales sont peu coûteuses, il
356 est très rapide de créer ou détruire des dépôts dès que vous en avez besoin.
358 %% Note: la dernière phrase n'est pas une traduction littérale, mais je
359 %% pense qu'elle exprime plus clairement en français ce que veut dire son
360 %% équivalent anglais.
362 Dans notre dépôt \dirname{my-hello}, nous avons un fichier \filename{hello.c}
363 qui contient le classique programme ``hello, world''. Nous allons utiliser
364 l'ancienne et vénérable commande \command{sed} pour l'éditer pour qu'il
365 affiche une seconde ligne à l'écran. (J'utilise \command{sed} seulement parce
366 qu'il est facile d'écrire des exemples sous forme de script ainsi. Comme
367 vous n'avez pas ces contraintes, vous n'utiliserez probablement pas \command{sed}
368 mais plutôt votre éditeur de texte favori).
370 \interaction{tour.sed}
372 La commande \hgcmd{status} de Mercurial nous dira de quels fichiers Mercurial
373 s'occupe au sein de ce dépôt.
374 \interaction{tour.status}
375 La commande \hgcmd{status} n'affiche rien sur la sortie pour quelques fichiers
376 mais une ligne commence par ``\texttt{M}'' for \filename{hello.c}. À moins que
377 vous ne lui indiquiez de le faire, \hgcmd{status} n'affichera aucune sortie
378 pour les fichiers qui n'ont pas été modifiés.
380 Le caractère ``\texttt{M}'' indique que Mercurial a remarqué que nous avions
381 modifié le fichier \filename{hello.c}. Nous n'avons pas besoin d'\emph{informer}
382 Mercurial que nous allons modifier un fichier avant de le faire, ou que nous
383 venons de le modifier, il est capable de s'en rendre compte tout seul.
385 C'est pratique de savoir que nous avons modifié \filename{hello.c}, mais il
386 serait encore plus pratique de savoir ce que nous avons modifié exactement. Pour
387 cela, nous avons la commande \hgcmd{diff}.
389 \interaction{tour.diff}
391 \section{Enregister les modifications dans un nouveau \textit{changeset}}
393 Nous pouvons modifier des fichiers, compiler et tester nos modifications,
394 et utiliser les commandes \hgcmd{status} and \hgcmd{diff} pour voir les
395 modifications effectuées, jusqu'au moment où nous serons assez satisfaits
396 pour décider d'enregistrer notre travail dans un \textit{changeset}.
398 La commande \hgcmd{commit} vous laisse créer un nouveau \textit{changeset},
399 nous désignerons généralement cette opération par ``faire un commit'' ou
400 ``commiter''\footnote{NdT: De mon expérience, la plupart des francophones
401 utilisent régulièrement, à l'oral, cette expression, mais bien évidement
402 il ne s'agit pas d'un terme terminologiquement correct, ni même français.}
404 \subsection{Définir le nom d'utilisateur}
406 Quand vous exécutez la commande \hgcmd{commit} pour la première fois, elle
407 n'est pas garantie de réussir. Mercurial enregistre votre nom et votre
408 adresse avec chaque modification que vous effectuez, de manière à ce que
409 vous soyez capable (ou d'autres le soient) de savoir qui a fait quelle
410 modification. Mercurial essaye automatiquement de découvrir un nom
411 d'utilisateur qui ait un minimum de sens pour effectuer l'opération
412 de \textit{commit} avec. Il va essayer chacune des méthodes suivantes,
413 dans l'ordre:
414 \begin{enumerate}
415 \item Si vous spécifiez l'option \hgopt{commit}{-u} avec la commande
416 \hgcmd{commit}, suivi d'un nom d'utilisateur, ceci aura toujours la
417 priorité sur les autres méthodes ci dessous.
418 \item Si vous avez défini une variable d'environement \envar{HGUSER},
419 c'est cette valeur qui est alors utilisée.
420 \item Si vous créez un fichier nommé \sfilename{.hgrc} dans votre
421 répertoire \textit{home}, avec une entrée \rcitem{ui}{username},
422 c'est la valeur associée qui sera utilisée. Pour voir à quoi
423 ressemble le contenu de ce fichier regardez la
424 section~\ref{sec:tour-basic:username} ci dessous.
425 \item Si vous avez défini une variable d'environement \envar{EMAIL}
426 celle ci sera utilisée ensuite.
427 \item Enfin, Mercurial interrogera votre système pour trouver votre
428 nom d'utilisateur local ainsi que le nom de la machine hôte, et il
429 %%%FIXME : et il quoi ? un nom...
430 un nom d'utilisateur à partir de ces composants. Comme il arrive
431 souvent que ce genre de noms soit totalement inutile, il vous
432 préviendra en affichant un message d'avertissement.
433 \end{enumerate}
435 Si tous ces mécanismes échouent, Mercurial n'exécutera pas la commande,
436 affichant un message d'erreur. Dans ce cas, il ne vous laissera pas
437 effectuer de \textit{commit} tant que vous n'aurez pas défini un nom
438 d'utilisateur.
440 Vous devriez penser à utiliser la variable d'environement \envar{HGUSER}
441 et l'option \hgopt{commit}{-u} comme moyen pour \emph{changer le nom
442 d'utilisateur} par défaut. Pour une utilisation normale, la plus simple
443 et robuste manière d'opérer est de créer un fichier \sfilename{.hgrc},
444 voir ci dessous pour les détails à ce sujet.
446 \subsubsection{Créer un fichier de configuration pour Mercurial}
447 \label{sec:tour-basic:username}
449 Pour définir un nom d'utilisateur, utiliser votre éditeur de texte favori
450 pour créer un fichier \sfilename{.hgrc} dans votre répertoire \textit{home}.
451 Mercurial va utiliser ce fichier pour retrouver votre configuration personnelle.
452 Le contenu initial devrait ressembler à ceci:
453 \begin{codesample2}
454 # This is a Mercurial configuration file.
455 [ui]
456 username = Firstname Lastname <email.address@domain.net>
457 \end{codesample2}
458 La ligne avec \texttt{[ui]} commence une \emph{section} du fichier de
459 configuration, ainsi la ligne ``\texttt{username = ...}'' signifie ``
460 définir la valeur de l'élément \texttt{username} dans la section
461 \texttt{ui}''. Une section continue jusqu'à ce qu'une nouvelle
462 commence, ou que la fin du fichier soit atteinte. Mercurial ignore
463 les lignes vide et traite tout texte
464 file. Mercurial ignores empty lines and treats any text from
465 ``\texttt{\#}'' to the end of a line as a comment.
467 \subsubsection{Choosing a user name}
469 You can use any text you like as the value of the \texttt{username}
470 config item, since this information is for reading by other people,
471 but for interpreting by Mercurial. The convention that most people
472 follow is to use their name and email address, as in the example
473 above.
475 \begin{note}
476 Mercurial's built-in web server obfuscates email addresses, to make
477 it more difficult for the email harvesting tools that spammers use.
478 This reduces the likelihood that you'll start receiving more junk
479 email if you publish a Mercurial repository on the web.
480 \end{note}
482 \subsection{Writing a commit message}
484 When we commit a change, Mercurial drops us into a text editor, to
485 enter a message that will describe the modifications we've made in
486 this changeset. This is called the \emph{commit message}. It will be
487 a record for readers of what we did and why, and it will be printed by
488 \hgcmd{log} after we've finished committing.
489 \interaction{tour.commit}
491 The editor that the \hgcmd{commit} command drops us into will contain
492 an empty line, followed by a number of lines starting with
493 ``\texttt{HG:}''.
494 \begin{codesample2}
495 \emph{empty line}
496 HG: changed hello.c
497 \end{codesample2}
498 Mercurial ignores the lines that start with ``\texttt{HG:}''; it uses
499 them only to tell us which files it's recording changes to. Modifying
500 or deleting these lines has no effect.
502 \subsection{Writing a good commit message}
504 Since \hgcmd{log} only prints the first line of a commit message by
505 default, it's best to write a commit message whose first line stands
506 alone. Here's a real example of a commit message that \emph{doesn't}
507 follow this guideline, and hence has a summary that is not readable.
508 \begin{codesample2}
509 changeset: 73:584af0e231be
510 user: Censored Person <censored.person@example.org>
511 date: Tue Sep 26 21:37:07 2006 -0700
512 summary: include buildmeister/commondefs. Add an exports and install
513 \end{codesample2}
515 As far as the remainder of the contents of the commit message are
516 concerned, there are no hard-and-fast rules. Mercurial itself doesn't
517 interpret or care about the contents of the commit message, though
518 your project may have policies that dictate a certain kind of
519 formatting.
521 My personal preference is for short, but informative, commit messages
522 that tell me something that I can't figure out with a quick glance at
523 the output of \hgcmdargs{log}{--patch}.
525 \subsection{Aborting a commit}
527 If you decide that you don't want to commit while in the middle of
528 editing a commit message, simply exit from your editor without saving
529 the file that it's editing. This will cause nothing to happen to
530 either the repository or the working directory.
532 If we run the \hgcmd{commit} command without any arguments, it records
533 all of the changes we've made, as reported by \hgcmd{status} and
534 \hgcmd{diff}.
536 \subsection{Admiring our new handiwork}
538 Once we've finished the commit, we can use the \hgcmd{tip} command to
539 display the changeset we just created. This command produces output
540 that is identical to \hgcmd{log}, but it only displays the newest
541 revision in the repository.
542 \interaction{tour.tip}
543 We refer to the newest revision in the repository as the tip revision,
544 or simply the tip.
546 \section{Sharing changes}
548 We mentioned earlier that repositories in Mercurial are
549 self-contained. This means that the changeset we just created exists
550 only in our \dirname{my-hello} repository. Let's look at a few ways
551 that we can propagate this change into other repositories.
553 \subsection{Pulling changes from another repository}
554 \label{sec:tour:pull}
556 To get started, let's clone our original \dirname{hello} repository,
557 which does not contain the change we just committed. We'll call our
558 temporary repository \dirname{hello-pull}.
559 \interaction{tour.clone-pull}
561 We'll use the \hgcmd{pull} command to bring changes from
562 \dirname{my-hello} into \dirname{hello-pull}. However, blindly
563 pulling unknown changes into a repository is a somewhat scary
564 prospect. Mercurial provides the \hgcmd{incoming} command to tell us
565 what changes the \hgcmd{pull} command \emph{would} pull into the
566 repository, without actually pulling the changes in.
567 \interaction{tour.incoming}
568 (Of course, someone could cause more changesets to appear in the
569 repository that we ran \hgcmd{incoming} in, before we get a chance to
570 \hgcmd{pull} the changes, so that we could end up pulling changes that we
571 didn't expect.)
573 Bringing changes into a repository is a simple matter of running the
574 \hgcmd{pull} command, and telling it which repository to pull from.
575 \interaction{tour.pull}
576 As you can see from the before-and-after output of \hgcmd{tip}, we
577 have successfully pulled changes into our repository. There remains
578 one step before we can see these changes in the working directory.
580 \subsection{Updating the working directory}
582 We have so far glossed over the relationship between a repository and
583 its working directory. The \hgcmd{pull} command that we ran in
584 section~\ref{sec:tour:pull} brought changes into the repository, but
585 if we check, there's no sign of those changes in the working
586 directory. This is because \hgcmd{pull} does not (by default) touch
587 the working directory. Instead, we use the \hgcmd{update} command to
588 do this.
589 \interaction{tour.update}
591 It might seem a bit strange that \hgcmd{pull} doesn't update the
592 working directory automatically. There's actually a good reason for
593 this: you can use \hgcmd{update} to update the working directory to
594 the state it was in at \emph{any revision} in the history of the
595 repository. If you had the working directory updated to an old
596 revision---to hunt down the origin of a bug, say---and ran a
597 \hgcmd{pull} which automatically updated the working directory to a
598 new revision, you might not be terribly happy.
600 However, since pull-then-update is such a common thing to do,
601 Mercurial lets you combine the two by passing the \hgopt{pull}{-u}
602 option to \hgcmd{pull}.
603 \begin{codesample2}
604 hg pull -u
605 \end{codesample2}
606 If you look back at the output of \hgcmd{pull} in
607 section~\ref{sec:tour:pull} when we ran it without \hgopt{pull}{-u},
608 you can see that it printed a helpful reminder that we'd have to take
609 an explicit step to update the working directory:
610 \begin{codesample2}
611 (run 'hg update' to get a working copy)
612 \end{codesample2}
614 To find out what revision the working directory is at, use the
615 \hgcmd{parents} command.
616 \interaction{tour.parents}
617 If you look back at figure~\ref{fig:tour-basic:history}, you'll see
618 arrows connecting each changeset. The node that the arrow leads
619 \emph{from} in each case is a parent, and the node that the arrow
620 leads \emph{to} is its child. The working directory has a parent in
621 just the same way; this is the changeset that the working directory
622 currently contains.
624 To update the working directory to a particular revision, give a
625 revision number or changeset~ID to the \hgcmd{update} command.
626 \interaction{tour.older}
627 If you omit an explicit revision, \hgcmd{update} will update to the
628 tip revision, as shown by the second call to \hgcmd{update} in the
629 example above.
631 \subsection{Pushing changes to another repository}
633 Mercurial lets us push changes to another repository, from the
634 repository we're currently visiting. As with the example of
635 \hgcmd{pull} above, we'll create a temporary repository to push our
636 changes into.
637 \interaction{tour.clone-push}
638 The \hgcmd{outgoing} command tells us what changes would be pushed
639 into another repository.
640 \interaction{tour.outgoing}
641 And the \hgcmd{push} command does the actual push.
642 \interaction{tour.push}
643 As with \hgcmd{pull}, the \hgcmd{push} command does not update the
644 working directory in the repository that it's pushing changes into.
645 (Unlike \hgcmd{pull}, \hgcmd{push} does not provide a \texttt{-u}
646 option that updates the other repository's working directory.)
648 What happens if we try to pull or push changes and the receiving
649 repository already has those changes? Nothing too exciting.
650 \interaction{tour.push.nothing}
652 \subsection{Sharing changes over a network}
654 The commands we have covered in the previous few sections are not
655 limited to working with local repositories. Each works in exactly the
656 same fashion over a network connection; simply pass in a URL instead
657 of a local path.
658 \interaction{tour.outgoing.net}
659 In this example, we can see what changes we could push to the remote
660 repository, but the repository is understandably not set up to let
661 anonymous users push to it.
662 \interaction{tour.push.net}
664 %%% Local Variables:
665 %%% mode: latex
666 %%% TeX-master: "00book"
667 %%% End: