hgbook
view fr/ch02-tour-basic.xml @ 964:6b680d569bb4
deleting a bunch of files not longer necessary to build the documentation.
Adding missing newly files needed to build the documentation
Adding missing newly files needed to build the documentation
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Sun Aug 16 04:58:01 2009 +0200 (2009-08-16) |
| parents | |
| children | 1df99de46e39 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter>
4 <title>Un rapide tour de Mercurial</title>
5 <para>\label{chap:tour-basic}</para>
7 <sect1>
8 <title>Installer Mercurial sur votre système</title>
9 <para>\label{sec:tour:install}</para>
11 <para>Des paquetages binaires de Mercurial sont disponibles pour la plupart
12 des systèmes d'exploitation, ce qui rend facile l'utilisation immédiate
13 de Mercurial sur votre ordinateur.</para>
15 <sect2>
16 <title>Linux</title>
18 <para>Parce que chaque distribution de Linux a ses propres outils de gestion
19 de paquets, politiques et rythmes de développements, il est difficile de
20 donner un ensemble d'instructions uniques pour installer les binaires de
21 Mercurial. La version de Mercurial avec laquelle vous vous retrouverez
22 dépendra grandement de l'activité de la personne en charge du paquetage
23 pour la distribution.</para>
25 <para>Pour rester simple, je me concentrerai sur l'installation de Mercurial
26 en ligne de commande, sous les distributions les plus courantes. La
27 plupart des distributions fournissent des gestionnaires graphiques de
28 paquetage qui vous permettront d'installer Mercurial en quelques clicks.
29 Le paquetage devrait se nommer \textit{mercurial}.</para>
31 <itemizedlist>
32 <listitem><para>Debian:</para>
33 </listitem><programlisting>
34 <listitem><para> apt-get install mercurial</para>
35 </listitem></programlisting></para>
36 </listitem>
37 <listitem><para>Fedora Core:
38 </para>
39 </listitem><programlisting>
40 <listitem><para> yum install mercurial
41 </para>
42 </listitem></programlisting>
44 </para>
45 </listitem>
46 <listitem><para>Gentoo:
47 </para>
48 </listitem><programlisting>
49 <listitem><para> emerge mercurial
50 </para>
51 </listitem></programlisting>
53 </para>
54 </listitem>
55 <listitem><para>OpenSUSE:
56 </para>
57 </listitem><programlisting>
58 <listitem><para> yum install mercurial
59 </para>
60 </listitem></programlisting>
62 </para>
63 </listitem>
64 <listitem><para>Ubuntu: Le paquetage de Mercurial d'Ubuntu est construit sur celui de Debian.
65 Pour l'installer, exécutez simplement les commandes suivantes:
66 </para>
67 </listitem><programlisting>
68 <listitem><para> apt-get install mercurial
69 </para>
70 </listitem></programlisting>
71 <listitem><para> Les paquetages Ubuntu pour Mercurial ont tendance à être un peu en retard
72 par rapport au paquetage Debian (au moment de l'écriture de ce livre, il
73 faut compter à peu près un retard de 7 mois), ce qui signifie que parfois
74 sur Ubuntu, vous risquez de rencontrer des problèmes qui ont été corrigés
75 depuis longtemps dans les paquetages Debian.
76 </para>
77 </listitem></itemizedlist>
79 </sect2>
80 <sect2>
81 <title>Solaris</title>
83 <para>SunFreeWare, à <ulink url="http://www.saufreeware.com">http://www.saufreeware.com</ulink>, est une bonne source
84 pour trouver un vaste nombre de paquets précompilés pour 32 ou 64 bits
85 Intel et les architecture Sparc, dont les versions courantes de Mercurial.
86 </para>
88 </sect2>
89 <sect2>
90 <title>Mac OS X</title>
92 <para>Lee Cantey publie un installateur de Mercurial pour Mac OS X sur le site
93 <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. Ce paquetage fonctionne sur les
94 architectures Intel- et PowerPC. Avant de vous en servir, vous devez
95 installer une version Universelle MacPython <citation>web:macpython</citation>. C'est
96 assez facile à faire : suivez simplement les instructions sur le site
97 de Lee.
98 </para>
100 <para>Il est aussi possible d'installer Mercurial en utilisant Fink ou MacPorts,
101 deux outils de gestion de paquetage libres pour Mac OS X. Si vous avez
102 Fink, utilisez <command>sudo fink install mercurial-py25</command>. Si vous avez
103 MacPorts, <command>sudo port install mercurial</command>.
104 </para>
106 </sect2>
107 <sect2>
108 <title>Windows</title>
110 <para>Lee Cantey publie aussi un installateur de Mercurial pour Windows sur le site
111 <ulink url="http://mercurial.berkwood.com">http://mercurial.berkwood.com</ulink>. Ce paquetage n'a aucune dépendance
112 externe, il fonctionne <quote>tout court</quote>.
113 </para>
115 <note>
116 <para> La version de Windows de Mercurial ne convertie pas automatiquement
117 les retours chariot Windows et Unix. Si vous désirez partager votre
118 travail avec des utilisateurs Unix, vous devez faire un peu de configuration
119 supplémentaire. XXX En dire plus.
120 </para>
121 </note>
123 </sect2>
124 </sect1>
125 <sect1>
126 <title>Commencer à utiliser Mercurial</title>
128 <para>Pour commencer, nous utiliserons la commande <command role="hg-cmd">hg version</command> pour vérifier
129 si Mercurial est installé proprement. Les informations affichées sur la
130 version ne sont pas réellement importantes en soit, c'est surtout de savoir
131 si elles s'affichent qui nous intéresse.
132 <!-- &interaction.tour.version; -->
133 </para>
135 <sect2>
136 <title>L'aide intégrée</title>
138 <para>Mercurial fournit un système d'aide intégré, ce qui est inestimable quand
139 vous vous retrouvez coincé à essayer de vous rappeler comment lancer telle
140 ou telle commande.
141 Si c'est le cas, exécutez simplement <command role="hg-cmd">hg help</command>; il vous aidera à imprimer
142 une brève liste de commandes, avec une description de ce qu'elles font. Si vous
143 demandez de l'aide sur une commande spécifique (voir ci-dessous), il affichera
144 des informations plus détaillées.
145 <!-- &interaction.tour.help; -->
146 Pour un niveau d'informations encore plus détaillées (ce dont vous aurez rarement
147 besoin), exécuter <command role="hg-cmd">hg help <option role="hg-opt-global">-v</option></command>. L'option <option role="hg-opt-global">-v</option> est
148 l'abréviation de <option role="hg-opt-global">--verbose</option>, et indique à Mercurial d'afficher plus
149 d'informations que d'habitude.
150 </para>
152 </sect2>
153 </sect1>
154 <sect1>
155 <title>Travailler avec un dépôt</title>
157 <para>Avec Mercurial, tout se déroule au sein du <emphasis>dépôt</emphasis>\footnote{NdT: Dépôt est
158 la traduction que j'ai retenue pour tout l'ouvrage du terme anglais \textit{repository}}.
159 Le dépôt d'un projet contient tous les fichiers qui <quote>appartiennent</quote> au projet.
160 </para>
162 <para>Il n'y a rien de particulièrement magique au sujet de ce dépôt, c'est
163 simplement une arborescence sur votre système de fichiers que Mercurial
164 traite de manière spéciale. Vous pouvez renommer ou effacer ce répertoire
165 à n'importe quel moment, en utilisant la ligne de commande ou votre
166 explorateur de fichiers.
167 </para>
169 <sect2>
170 <title>Faire une copie locale de votre dépôt</title>
172 <para><emphasis>Copier</emphasis> un dépôt est juste un peu spécial. Bien que vous
173 puissiez utiliser une commande habituelle de copie pour copier
174 votre dépôt, il vaut mieux utiliser une commande fournie par
175 Mercurial. Cette commande est appelée <command role="hg-cmd">hg clone</command>, car elle
176 crée une copie identique à un dépôt existant.
177 <!-- &interaction.tour.clone; -->
178 Si votre opération de clonage réussit, vous devriez maintenant
179 avoir un répertoire local appelé <filename class="directory">hello</filename>. Ce répertoire
180 contiendra quelques fichiers.
181 <!-- &interaction.tour.ls; -->
182 Ces fichiers ont le même contenu et historique dans votre dépôt
183 qu'ils ont dans le dépôt que vous avez cloné.
184 </para>
186 <para>Chaque dépôt Mercurial est complet, autonome et indépendant. Il
187 contient sa propre copie privée des fichiers du projet et de leur
188 historique. Le clone d'un dépôt se souvient de la localisation du
189 dépôt à partir duquel il a été clôné, mais il ne communique pas avec
190 ce dernier, ou un autre, à moins que vous ne lui demandiez.
191 </para>
193 <para>Ce que tout ceci signifie pour le moment est que nous sommes libres
194 d'expérimenter avec ce dépôt, confiants dans le fait qu'il s'agit d'un
195 <quote>bac à sable</quote> qui n'affectera personne d'autre.
196 </para>
198 </sect2>
199 <sect2>
200 <title>Quel est le contenu d'un dépôt ?</title>
202 <para>Prêtons plus attention un instant au contenu d'un dépôt. Nous voyons
203 qu'il contient un répertoire nommé <filename class="directory">.hg</filename>. C'est ici que Mercurial
204 conserve toutes ses métadonnées.
205 <!-- &interaction.tour.ls-a; -->
206 </para>
208 <para>Le contenu du répertoire <filename class="directory">.hg</filename> et ses sous répertoires sont les
209 seuls propres à Mercurial. Tous les autres fichiers et répertoires dans
210 le dépôt sont à vous, et vous pouvez en faire ce que vous voulez.
211 </para>
213 <para>Pour introduire un peu de terminologie, le répertoire <filename class="directory">.hg</filename> est
214 un <quote>vrai</quote> dépôt, et tous les fichiers et les répertoires qui coexistent
215 avec lui, sont désignés sous le nom <emphasis>espace de travail</emphasis>\footnote{NdT:
216 \textit{working directory}}. Une manière facile de se rappeler cette
217 distinction est de retenir que le <emphasis>dépôt</emphasis> contient l'<emphasis>historique</emphasis>
218 de votre projet, alors que l'<emphasis>espace de travail</emphasis> contient une \emph{copie
219 ponctuelle}\footnote{NdT: Ce terme est une traduction du terme anglais
220 \textit{snapshot}. Il est traduit ici pour faciliter la lecture, mais ne sera
221 plus traduit par la suite.} de votre projet à un certain point de son
222 historique.
223 </para>
225 </sect2>
226 </sect1>
227 <sect1>
228 <title>Une ballade dans l'historique</title>
230 <para>Une des premières choses que vous aurez envie de faire avec un nouveau
231 dépôt, sera de comprendre son historique. La commande <command role="hg-cmd">hg log</command> vous
232 donne une vue de l'historique.
233 <!-- &interaction.tour.log; -->
234 Par défaut, cette commande affiche à l'écran un bref paragraphe pour chaque
235 révision enregistrée pour ce projet. Dans la terminologie de Mercurial, nous
236 appelons chacun de ces évènements enregistrés un <emphasis>changeset</emphasis>, parce
237 qu'il contient un ensemble de modifications sur plusieurs fichiers.
238 </para>
240 <para>La commande <command role="hg-cmd">hg log</command> affiche ainsi ces informations:
241 </para>
242 <itemizedlist>
243 <listitem><para><literal>changeset</literal>: Ce champ contient un nombre, séparé par deux points
244 (:), d'une chaine hexadécimale. Il s'agit en fait d'<emphasis>identifiants</emphasis>
245 d'un \textit{changeset}. Il y a deux identifiants car le numéro de
246 la révision est plus court et plus à facile à saisir qu'une séquence
247 hexadécimale.
248 </para>
249 </listitem>
250 <listitem><para><literal>user</literal>: L'identité de la personne qui a créée ce %%% laisser le terme anglais car il sera affiché
251 \textit{changeset}. C'est un champ libre de forme, mais la plupart du
252 temps il contient le nom et l'email de la personne.
253 </para>
254 </listitem>
255 <listitem><para><literal>date</literal>: La date et l'heure à laquelle le \textit{changeset}
256 a été créé, ainsi que le \textit{fuseau horaire} dans laquelle il a été créé. %%%TODO: Translate 'timezone' properly : FUSEAU
257 (La date et l'heure sont locales à ce \textit{fuseau}, elles indiquent
258 donc quelle date et heure il était pour la personne qui a créé ce %%%TODO: je suppose (quelle "heure") OUI
259 \textit{changeset}.)
260 </para>
261 </listitem>
262 <listitem><para><literal>résumé</literal>: La première du message que le créateur a associé à
263 son \textit{changeset} pour le décrire.
264 </para>
265 </listitem></itemizedlist>
267 <para>Par défaut, la commande <command role="hg-cmd">hg log</command> n'affiche qu'un résumé, il manque
268 beaucoup de détails.
269 </para>
271 <para>La figure <xref linkend="fig:tour-basic:history"/> fournit une représentation graphique
272 de l'historique du dépôt <filename class="directory">hello</filename>, pour rendre plus facile de voir
273 dans quelle direction l'historique se <quote>déroule</quote>\footnote{NdT: \textit{flowing in}.}.
274 Nous reviendrons régulièrement sur cette représentation dans ce chapitre et
275 ceux qui suivent.
276 </para>
278 <informalfigure>
280 <para> <mediaobject><imageobject><imagedata fileref="tour-history"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject>
281 <caption><para>Représentation graphique du dépôt <filename class="directory">hello</para></caption> </filename>
282 \label{fig:tour-basic:history}
283 </para>
284 </informalfigure>
286 <sect2>
287 <title>Changesets, révisions, et discuter avec les autres</title>
288 <para>%%% je propose "colaboration"
289 </para>
291 <para>Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique
292 est la source de bien des erreurs de terminologies (pourquoi utiliser un
293 seul terme quand quatre feront l'affaire ?), la gestion de version a une
294 variété de mots et de phrases qui veulent dire la même chose. Si vous
295 discutez d'historique de Mercurial avec d'autres personnes,
296 %%%TODO: ça ne veut rien dire: il faut supprimer une des personnes : soit "quelqu'un",
297 % soit "à d'autres personnes"
298 vous constaterez que souvent le mot <quote>\textit{changeset}</quote> est contracté simplement
299 en <quote>change</quote> ou (à l'écrit) <quote>cset</quote>, et même parfois un
300 \textit{changeset} simplement <quote>révision</quote>, abrégé en <quote>rev</quote>.
301 </para>
303 <para>Bien que le <emphasis>mot</emphasis> que vous utilisez pour désigner le concept de
304 \textit{changeset} importe peu, l'<emphasis>identifiant</emphasis> que vous utilisez
305 pour désigner un <emphasis>changeset</emphasis> \textit{spécifique} a une grande
306 importance. Rappelez vous que le champ \textit{changeset} affiché par la
307 commande <command role="hg-cmd">hg log</command> identifie un \textit{changeset} à la fois avec
308 un numéro de révision et une séquence hexadécimale.
309 </para>
311 <itemizedlist>
312 <listitem><para>Le numéro de révision est <emphasis>seulement valable dans ce dépôt</emphasis>,
313 </para>
314 </listitem>
315 <listitem><para>alors que la séquence hexadécimale est un \emph{identifiant
316 permanent, et invariant } qui pourra toujours être associé au
317 \textit{changeset} exact de <emphasis>chaque</emphasis> copie de votre dépôt.
318 </para>
319 </listitem></itemizedlist>
321 <para>La distinction est importante. Si vous envoyez un email à quelqu'un en
322 parlant de la <quote>révision 33</quote>, il est très probable que sa révision 33
323 <emphasis>ne sera pas la même</emphasis> que la votre. La raison de ceci est que le
324 numéro de révision dépend de l'ordre dans lequel les modifications sont
325 arrivées dans le dépôt, et il n'y a aucune garantie que les mêmes changements
326 soient arrivés dans le même ordre dans différents dépôts. Trois modifications
327 $a,b,c$ peuvent aisément apparaitre dans un dépôt comme $0,1,2$, et dans
328 un autre comme $1,0,2$.
329 </para>
331 <para>Mercurial utilise les numéros de révision uniquement comme des raccourcis
332 pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un,
333 ou identifer un \textit{changeset} pour une quelquonque %%%TODO: our : "pour" ou "ou"
334 raison (par exemple, un rapport de \textit{bug}), utilisez la séquence
335 hexadécimale.
336 </para>
338 </sect2>
339 <sect2>
340 <title>Afficher une révision spécifique</title>
342 <para>Pour réduire la sortie de <command role="hg-cmd">hg log</command> à une seule révision, utilisez
343 l'option <option role="hg-opt-log">-r</option> (ou <option role="hg-opt-log">--rev</option>). Vous pouvez utiliser
344 le numéro de révision ou la séquence hexadécimale comme identifiant, et
345 demander autant de révisions que vous le souhaitez.
346 <!-- &interaction.tour.log-r; -->
347 </para>
349 <para>Si vous voulez voir l'historique de plusieurs révisions sans avoir à
350 les énumérer, vous pouvez utiliser la <emphasis>\textit{range notation</emphasis>}
351 \footnote{NdT: Il n'est pas aisé de traduire ce terme, donc je le %%%TODO : intervalle de numérotation ?
352 laisse en anglais} qui vous permet d'exprimer l'idée <quote>je veux toutes
353 les révisions entre $a$ et $b$, inclus</quote>.
354 <!-- &interaction.tour.log.range; -->
355 Mercurial respecte aussi l'ordre dans lequel vous spécifiez les
356 révisions, ainsi <command role="hg-cmd">hg log -r 2:4</command> affichera $2,3,4$ alors que
357 <command role="hg-cmd">hg log -r 4:2</command> affichera $4,3,2$.
358 </para>
360 </sect2>
361 <sect2>
362 <title>Informations détaillées</title>
365 <para>Le résumé affiché par <command role="hg-cmd">hg log</command> est suffisant si vous savez déjà ce %%%TODO: je pense que le premier "si" est de trop : exact
366 que vous cherchez. En revanche, vous aurez probablement besoin de voir une description
367 complète du changement, ou une liste des fichiers modifiés si vous
368 cherchez à déterminer qu'un \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 ?
369 recherchez. L'option \hgopt{-v} de la commande <command role="hg-cmd">hg log</command> (ou
370 \hgopt{--verbose}) vous donne ces informations supplémentaires.
371 <!-- &interaction.tour.log-v; -->
372 </para>
374 <para>Si vous voulez voir à la fois la description et le contenu d'une
375 modification, ajouter l'option <option role="hg-opt-log">-p</option> (ou <option role="hg-opt-log">--patch</option>).
376 Ceci affiche le contenu d'une modification comme un <emphasis>diff unifié</emphasis>
377 \footnote{NdT: \textit{unified diff}} (si vous n'avez jamais vu de diff
378 unifié avant, consultez la section <xref linkend="sec:mq:patch"/> pour un rapide
379 survol).
380 </para>
382 <para><!-- &interaction.tour.log-vp; -->
383 </para>
385 </sect2>
386 </sect1>
387 <sect1>
388 <title>Tout sur les options de commandes</title>
391 <para>Avant d'aller plus loin sur le fonctionnement des commandes de Mercurial,
392 étudions un moment comment elles fonctionnent de manière générale. Vous
393 trouverez ça probablement utile pour la suite de notre parcours.
394 </para>
396 <para>Mercurial utilise une approche directe et cohérente pour interpréter %%%TODO: une manière d'approche ?
397 les options que vous passez aux commandes. Il suit une convention commune
398 à la plupart des systèmes Unix et Linux modernes.
399 </para>
401 <itemizedlist>
402 <listitem><para>Chaque option a un nom complet. Par exemple, comme nous l'avons déjà
403 vu, la commande <command role="hg-cmd">hg log</command> accepte l'option <option role="hg-opt-log">--rev</option>.%%%TODO: commande ou command e\hgcmd...?
404 </para>
405 </listitem>
406 <listitem><para>La plupart des options disposent de noms abrégés. Aussi, au lieu d'utiliser
407 <option role="hg-opt-log">--rev</option>, vous pouvez utiliser <option role="hg-opt-log">-r</option>. (Les options qui
408 n'ont pas de noms abrégés sont généralement rarement utilisées, pour cette raison).
409 </para>
410 </listitem>
411 <listitem><para>Les noms complets commencent par deux tirets (i.e. <option role="hg-opt-log">--rev</option>),
412 alors que les options courtes commencent avec un seul (i.e. <option role="hg-opt-log">-r</option>).
413 </para>
414 </listitem>
415 <listitem><para>Les noms des options sont cohérents entre les commandes. Par exemple,
416 chaque commande qui accepte un \textit{changeset ID} ou un numéro de révision
417 accepte aussi <option role="hg-opt-log">-r</option> et <option role="hg-opt-log">--rev</option> comme arguments.
418 %TODO: Small mistake here, shouldn't have log here... shouldn't it ?
419 </para>
420 </listitem></itemizedlist>
422 <para>Dans les exemples de ce livre, j'utilise les noms abrégés plutôt que les noms
423 complets. Ceci est une préférence personnelle, pas une recommandation.
424 </para>
426 <para>La plupart des commandes qui affichent une quelconque sortie à l'écran,
427 afficheront davantage avec l'option <option role="hg-opt-global">-v</option> (ou <option role="hg-opt-global">--verbose</option>), et
428 moins avec l'option <option role="hg-opt-global">-q</option> (ou <option role="hg-opt-global">--quiet</option>).
429 </para>
431 </sect1>
432 <sect1>
433 <title>Faire et vérifier des modifications</title>
435 <para>Maintenant que nous avons une bonne idée des commandes pour consulter
436 l'historique de Mercurial, regardons comment faire des modifications et
437 les examiner.
438 </para>
441 <para>La première chose que nous allons faire c'est isoler notre expérience dans
442 un dépôt à part. Nous allons utiliser la commande <command role="hg-cmd">hg clone</command>, mais nous
443 n'avons pas besoin de faire une copie de dépôt distant. Comme nous avons
444 déjà une copie locale, nous pouvons juste faire un clone de celle-ci à la
445 place. C'est beaucoup plus rapide que de faire une copie à travers le
446 réseau, et un dépôt cloné localement prend également moins d'espace disque.
447 </para>
449 <para><!-- &interaction.tour.reclone; -->
450 </para>
452 <para>On notera au passage qu'il est souvent considéré comme une bonne pratique
453 de conserver une copie <quote>immaculée</quote> du dépôt distant, à partir de laquelle
454 vous pourrez faire des copies locales temporaires pour créer des <quote>bacs à
455 sable</quote> pour chaque tâche sur laquelle vous souhaitez travailler. Ceci vous
456 permet de travailler sur plusieurs choses en parallèle, chacune isolée les
457 unes des autres en attendant que ces tâches soient finies et que vous soyez
458 prêt à les réintégrer. Parce que les copies locales sont peu coûteuses, il
459 est très rapide de créer ou détruire des dépôts dès que vous en avez besoin.
460 </para>
462 <para>%% Note: la dernière phrase n'est pas une traduction littérale, mais je
463 %% pense qu'elle exprime plus clairement en français ce que veut dire son
464 %% équivalent anglais. : OUI
465 </para>
467 <para>Dans notre dépôt <filename class="directory">my-hello</filename>, nous avons un fichier <filename>hello.c</filename>
468 qui contient le classique programme <quote>hello, world</quote>. Nous allons utiliser
469 l'ancienne et vénérable commande <command>sed</command> pour l'éditer afin qu'il
470 affiche une seconde ligne à l'écran. (J'utilise <command>sed</command> seulement parce
471 qu'il est ainsi facile d'écrire des exemples sous forme de script. Comme
472 vous n'avez pas ces contraintes, vous n'utiliserez probablement pas <command>sed</command>
473 mais plutôt votre éditeur de texte favori).
474 </para>
476 <para><!-- &interaction.tour.sed; -->
477 </para>
479 <para>La commande <command role="hg-cmd">hg status</command> de Mercurial nous dira de quels fichiers Mercurial
480 s'occupe au sein de ce dépôt.
481 <!-- &interaction.tour.status; -->
482 La commande <command role="hg-cmd">hg status</command> n'affiche rien sur la sortie pour quelques fichiers
483 mais une ligne commence par <quote><literal>M</literal></quote> for <filename>hello.c</filename>. À moins que
484 vous ne lui indiquiez de le faire, <command role="hg-cmd">hg status</command> n'affichera aucune sortie
485 pour les fichiers qui n'ont pas été modifiés.
486 </para>
488 <para>Le caractère <quote><literal>M</literal></quote> indique que Mercurial a remarqué que nous avions
489 modifié le fichier <filename>hello.c</filename>. Nous n'avons pas besoin d'<emphasis>informer</emphasis>
490 Mercurial que nous allons modifier un fichier avant de le faire, ou que nous
491 venons de le modifier, il est capable de s'en rendre compte tout seul.
492 </para>
494 <para>C'est pratique de savoir que nous avons modifié <filename>hello.c</filename>, mais il
495 serait encore plus pratique de savoir ce que nous avons modifié exactement. Pour
496 cela, nous avons la commande <command role="hg-cmd">hg diff</command>.
497 </para>
499 <para><!-- &interaction.tour.diff; -->
500 </para>
502 </sect1>
503 <sect1>
504 <title>Enregister les modifications dans un nouveau \textit{changeset}</title>
506 <para>Nous pouvons modifier des fichiers, compiler et tester nos modifications,
507 et utiliser les commandes <command role="hg-cmd">hg status</command> et <command role="hg-cmd">hg diff</command> pour voir les
508 modifications effectuées, jusqu'au moment où nous serons assez satisfaits
509 pour décider d'enregistrer notre travail dans un \textit{changeset}.
510 </para>
512 <para>La commande <command role="hg-cmd">hg commit</command> vous laisse créer un nouveau \textit{changeset},
513 nous désignerons généralement cette opération par <quote>faire un commit</quote> ou
514 <quote>commiter</quote>\footnote{NdT: De mon expérience, la plupart des francophones
515 utilisent régulièrement, à l'oral, cette expression, mais bien évidement
516 il ne s'agit pas d'un terme de terminologie correcte, ni même français.}
517 </para>
519 <sect2>
520 <title>Définir le nom d'utilisateur</title>
522 <para>Quand vous exécutez la commande <command role="hg-cmd">hg commit</command> pour la première fois, elle
523 n'est pas garantie de réussir. Mercurial enregistre votre nom et votre
524 adresse avec chaque modification que vous effectuez, de manière à ce que
525 vous soyez capable (ou d'autres le soient) de savoir qui a fait quelle
526 modification. Mercurial essaye automatiquement de découvrir un nom
527 d'utilisateur qui ait un minimum de sens pour effectuer l'opération
528 de \textit{commit} avec. Il va essayer chacune des méthodes suivantes,
529 dans l'ordre:
530 </para>
531 <orderedlist>
532 <listitem><para>Si vous spécifiez l'option <option role="hg-opt-commit">-u</option> avec la commande
533 <command role="hg-cmd">hg commit</command>, suivi d'un nom d'utilisateur, ceci aura toujours la
534 priorité sur les autres méthodes ci dessous.
535 </para>
536 </listitem>
537 <listitem><para>Si vous avez défini une variable d'environnement <envar>HGUSER</envar>,
538 c'est cette valeur qui est alors utilisée.
539 </para>
540 </listitem>
541 <listitem><para>Si vous créez un fichier nommé <filename role="special">.hgrc</filename> dans votre
542 répertoire \textit{home}, avec une entrée <envar role="rc-item-ui">username</envar>,
543 c'est la valeur associée qui sera utilisée. Pour voir à quoi
544 ressemble le contenu de ce fichier regardez la
545 section <xref linkend="sec:tour-basic:username"/> ci-dessous.
546 </para>
547 </listitem>
548 <listitem><para>Si vous avez défini une variable d'environnement <envar>EMAIL</envar>
549 celle ci sera utilisée ensuite.
550 </para>
551 </listitem>
552 <listitem><para>Enfin, Mercurial interrogera votre système pour trouver votre
553 nom d'utilisateur local ainsi que le nom de la machine hôte, et il
554 fabriquera un nom d'utilisateur à partir de ces données. Comme il arrive
555 souvent que ce genre de noms soit totalement inutile, il vous
556 préviendra en affichant un message d'avertissement.
557 </para>
558 </listitem></orderedlist>
560 <para>Si tous ces mécanismes échouent, Mercurial n'exécutera pas la commande,
561 affichant un message d'erreur. Dans ce cas, il ne vous laissera pas
562 effectuer de \textit{commit} tant que vous n'aurez pas défini un nom
563 d'utilisateur.
564 </para>
566 <para>Vous devriez penser à utiliser la variable d'environement <envar>HGUSER</envar>
567 et l'option <option role="hg-opt-commit">-u</option> comme moyen pour \emph{changer le nom
568 d'utilisateur} par défaut. Pour une utilisation normale, la manière la plus
569 simple et robuste d'opérer est de créer un fichier <filename role="special">.hgrc</filename>,
570 voir ci-dessous pour les détails à ce sujet.
571 </para>
573 <sect3>
574 <title>Créer un fichier de configuration pour Mercurial</title>
575 <para>\label{sec:tour-basic:username}
576 </para>
578 <para>Pour définir un nom d'utilisateur, utilisez votre éditeur de texte favori
579 pour créer un fichier <filename role="special">.hgrc</filename> dans votre répertoire \textit{home}.
580 Mercurial va utiliser ce fichier pour retrouver votre configuration personnelle.
581 Le contenu initial devrait ressembler à ceci:
582 </para>
583 <programlisting>
584 <para> # This is a Mercurial configuration file.
585 [ui]
586 username = Firstname Lastname <email.address@domain.net>
587 </para>
588 </programlisting>
589 <para>La ligne avec <literal>[ui]</literal> commence une <emphasis>section</emphasis> du fichier de
590 configuration, ainsi la ligne <quote><literal>username = ...</literal></quote> signifie <quote>
591 définir la valeur de l'élément <literal>username</literal> dans la section
592 <literal>ui</literal></quote>. Une section continue jusqu'à ce qu'une nouvelle
593 commence, ou que la fin du fichier soit atteinte. Mercurial ignore
594 les lignes vides et traite tout texte situé à la suite d'un
595 <quote><literal>#</literal></quote> jusqu'à la fin de la ligne comme un commentaire.
596 </para>
598 </sect3>
599 <sect3>
600 <title>Choisir un nom d'utilisateur</title>
602 <para>Vous pouvez utiliser n'importe quelle valeur pour votre <literal>username</literal>,
603 car cette information est destinée à d'autres personnes et non à être
604 interprétée par Mercurial. La convention que la plupart des personnes
605 <<<<<<< local
606 suivent est d'utiliser leurs noms suivies de leurs adresses emails,
607 comme montrée ci-dessus:
608 </para>
610 <note>
611 <para> Le mécanisme interne du serveur \textit{web} intégré à Mercurial,
612 masque les adresses emails, pour rendre plus difficile leurs
613 récupérations par les outils utilisés par les \textit{spammmers}.
614 Ceci réduit la probabilité que de recevoir encore plus de
615 \textit{spam} si vous vous publiez un dépôt sur internet.
616 </para>
617 </note>
619 </sect3>
620 </sect2>
621 <sect2>
622 <title>Rédiger un message de \textit{commit}</title>
624 <para>Lorsqu'on effectue une opération de \textit{commit}, Mercurial
625 lance automatiquement un éditeur de texte pour permettre de saisir
626 un message qui décrira les modifications effectuées dans ce
627 \textit{changeset}. Ce message est nommé le \emph{message de
628 \textit{commit}}. Ce sera un enregistrement pour tout lecteur
629 expliquant le pourquoi et le comment de vos modifications, et il sera
630 affiché par la commande <command role="hg-cmd">hg log</command>.
631 <!-- &interaction.tour.commit; -->
632 </para>
634 <para>L'éditeur que la commande <command role="hg-cmd">hg commit</command> déclenche ne contiendra
635 qu'une ligne vide suivi d'un certain nombre de lignes commençant
636 par <quote><literal>HG:</literal></quote>.
637 </para>
638 <programlisting>
639 <para> <emphasis>empty line</emphasis>
640 HG: changed hello.c
641 </para>
642 </programlisting>
643 <para>Mercurial ignore les lignes qui commencent avec <quote><literal>HG:</literal></quote>, il
644 ne les utilise que pour nous indiquer quels fichiers modifiés il se
645 prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a
646 aucune conséquence sur l'opération de \textit{commit}.
647 </para>
649 </sect2>
650 <sect2>
651 <title>Rédiger un message \textit{approprié}</title>
653 <para>Comme <command role="hg-cmd">hg log</command> n'affiche que la première ligne du message de
654 \textit{commit} par défaut, il est souvent considéré comme une bonne
655 pratique de rédiger des messages de \textit{commit} qui tiennent
656 sur une seule ligne. Voilà un exemple concret de message de
657 \textit{commit} qui <emphasis>ne suit pas</emphasis> cette directive, et qui a donc
658 un résumé peu lisible.
659 </para>
661 <programlisting>
662 <para> changeset: 73:584af0e231be
663 user: Censored Person <censored.person@example.org>
664 date: Tue Sep 26 21:37:07 2006 -0700
665 summary: include buildmeister/commondefs. Add an exports and install
666 </para>
667 </programlisting>
669 <para>A ce sujet, il faut noter qu'il n'existe pas de règle absolue dans ce
670 domaine. Mercurial lui-même n'interprète pas les contenus des messages
671 de \textit{commit}, ainsi votre projet est libre de concevoir différentes
672 politiques de mise en page des messages.
673 </para>
675 <para>Ma préférence personnelle va au message court, mais informatif, qui offre
676 des précisions supplémentaires par rapport à ce que pourrait m'apprendre une commande
677 <command role="hg-cmd">hg log --patch</command>.
678 </para>
680 </sect2>
681 <sect2>
682 <title>Annuler un \textit{commit}</title>
684 <para>Si, en rédigeant le message, vous décidez que finalement vous ne
685 voulez pas effectuer ce \textit{commit}, il suffit de quitter simplement
686 l'éditeur sans sauver. Ceci n'aura aucune conséquence sur le dépôt ou
687 les fichiers de l'espace de travail.
688 </para>
690 <para>Si vous exécuter la commande <command role="hg-cmd">hg commit</command> sans aucun argument, elle
691 enregistre toutes les modifications que vous avez faites, comme le montre
692 les commandes <command role="hg-cmd">hg status</command> et <command role="hg-cmd">hg diff</command>.
693 </para>
695 </sect2>
696 <sect2>
697 <title>Admirer votre travail</title>
699 <para>Une fois que votre \textit{commit} est terminé, vous pouvez utiliser
700 la commande <command role="hg-cmd">hg tip</command> pour afficher le \textit{changeset} que nous
701 venons de créer. Cette commande produit une sortie à l'écran qui est
702 identique à celle du <command role="hg-cmd">hg log</command>, mais qui n'affiche que la dernière
703 révision du dépôt.
704 <!-- &interaction.tour.tip; -->
705 On fait couramment référence à la dernière révision du dépôt comme
706 étant la révision \textit{tip}, ou plus simplement le \textit{tip}.
707 </para>
709 </sect2>
710 </sect1>
711 <sect1>
712 <title>Partager ses modifications</title>
714 <para>Nous avons mentionné plus haut que les dépôts de Mercurial
715 sont autosuffisants. Ce qui signifie que le \textit{changeset}
716 que vous venez de créer existe seulement dans votre répertoire
717 <filename class="directory">my-hello</filename>. Étudions comment propager cette modification
718 dans d'autres dépôts.
719 </para>
721 <sect2>
722 <title>Récupérer les modifications d'autres dépôts</title>
723 <para>\label{sec:tour:pull}
724 </para>
726 <para>Pour commencer, construisons un clone de notre dépôt <filename class="directory">hello</filename>
727 qui ne contiendra pas le changement que nous venons d'effectuer. Nous
728 l'appellerons notre dépôt temporaire <filename class="directory">hello-pull</filename>.
729 </para>
731 <para><!-- &interaction.tour.clone-pull; -->
732 </para>
734 <para>Nous allons utiliser la commande <command role="hg-cmd">hg pull</command> pour apporter les
735 modifications depuis <filename class="directory">my-hello</filename> dans <filename class="directory">hello-pull</filename>.
736 Néanmoins, récupérer aveuglement des modifications depuis un dépôt
737 a quelque chose d'un peu effrayant. Mercurial propose donc une
738 commande <command role="hg-cmd">hg incoming</command> qui permet de savoir quelles modifications
739 la commande <command role="hg-cmd">hg pull</command> <emphasis>pourrait</emphasis> entraîner dans notre dépôt,
740 et ceci sans effectuer réellement de modification dessus.
741 <!-- &interaction.tour.incoming; -->
742 (Bien évidement, quelqu'un pourrait ajouter des modifications
743 supplémentaires sur le dépôt que nous étudions avec <command role="hg-cmd">hg incoming</command>,
744 avant que nous ayons effectué notre <command role="hg-cmd">hg pull</command>, avec comme
745 triste conséquence que nous aurons récupéré des modifications que
746 nous n'attendions pas.)
747 </para>
749 <para>Apporter les modifications rapatriées dans un dépôt se résume donc
750 à exécuter la commande <command role="hg-cmd">hg pull</command>, et préciser depuis quel dépôt
751 effectuer le <command role="hg-cmd">hg pull</command>.
752 <!-- &interaction.tour.pull; -->
753 </para>
755 <para>Comme vous le voyez avec une sortie avant et après de la commande
756 <command role="hg-cmd">hg tip</command>, nous avons réussi à récupérer aisément les modifications
757 dans notre dépôt. Il reste néanmoins quelque chose à faire avant de
758 placer ces modifications dans l'espace de travail.
759 </para>
761 </sect2>
762 <sect2>
763 <title>Mise à jour de l'espace de travail</title>
765 <para>Nous avons jusqu'à maintenant grossièrement définie la relation
766 entre un dépôt et un espace de travail. La commande <command role="hg-cmd">hg pull</command> que
767 nous avons exécutée dans la section <xref linkend="sec:tour:pull"/> a apporté
768 des modifications, que nous avons vérifiées, dans notre dépôt, mais
769 il n'y a aucune trace de ces modifications dans notre espace de travail.
770 En effet, <command role="hg-cmd">hg pull</command> ne touche pas (par défaut) à l'espace de
771 travail. C'est la commande <command role="hg-cmd">hg update</command> qui s'en charge.
772 <!-- &interaction.tour.update; -->
773 </para>
775 <para>Il peut sembler un peu étrange que la commande <command role="hg-cmd">hg pull</command> ne mette
776 pas à jour l'espace de travail automatiquement. Il y a en fait une
777 très bonne raison à cela : vous pouvez utilisez la commande
778 </para>
780 <para><command role="hg-cmd">hg update</command> pour mettre à jour votre espace de travail à l'état
781 dans lequel il était à <emphasis>n'importe quelle révision</emphasis> de l'historique
782 du dépôt. Si vous aviez un espace de travail contenant une ancienne
783 révision&emdash;pour chercher l'origine d'un \textit{bug}, par exemple&emdash;et
784 que vous effectuiez un <command role="hg-cmd">hg pull</command> qui mettrait à jour automatiquement
785 votre espace de travail, vous ne seriez probablement pas très satisfait.
786 </para>
788 <para>Néanmoins, comme les opérations de \textit{pull} sont très souvent
789 suivies d'un \textit{update}, Mercurial vous permet de combiner les
790 deux aisément en passant l'option <option role="hg-opt-pull">-u</option> à la commande
791 <command role="hg-cmd">hg pull</command>
792 </para>
793 <programlisting>
794 <para> hg pull -u
795 </para>
796 </programlisting>
798 <para>Si vous étudiez de nouveau la sortie de la commande <command role="hg-cmd">hg pull</command> dans
799 la section <xref linkend="sec:tour:pull"/> quand nous l'avons exécutée sans l'option
800 <option role="hg-opt-pull">-u</option>, vous pouvez constater qu'elle a affiché un rappel assez
801 utile : vous devez encore effectuer une opération pour mettre à jour
802 votre espace de travail:
803 </para>
805 <programlisting>
806 <para> (run 'hg update' to get a working copy)
807 </para>
808 </programlisting>
810 <para>Pour découvrir sur quelle révision de l'espace de travail on est, utilisez
811 la commande <command role="hg-cmd">hg parents</command>.
812 <!-- &interaction.tour.parents; -->
813 Si vous regardez de nouveau le dessin <xref linkend="fig:tour-basic:history"/>, vous
814 <<<<<<< local
815 verrez les flèches reliant entre eux les \textit{changeset}. Le nœud
816 d'où la flèche <emphasis>part</emphasis> est dans chaque cas un parent,
817 et le nœud où la flèche <emphasis>arrive</emphasis> est un enfant.
818 </para>
820 <para>L'espace de travail a un parent de la même manière, c'est ce \textit{changeset}
821 que l'espace de travail contient à ce moment.
822 %%%TODO : difficile à comprendre : l'espace de travail a un parent, de la même manière, c'est ce changeset que l'espace...
823 </para>
825 <para>Pour mettre à jour l'espace de travail d'une révision particulière,
826 indiquez un numéro de révision ou un \textit{changeset ID} à la commande
827 <command role="hg-cmd">hg update</command>.
828 <!-- &interaction.tour.older; -->
829 Si vous ne précisez pas de manière explicite de numéro de révision
830 la commande <command role="hg-cmd">hg update</command> mettra à jour votre espace de travail avec
831 le contenu de la révsion \textit{tip}, comme montré dans l'exemple
832 ci dessus lors du second appel à <command role="hg-cmd">hg update</command>.
833 </para>
835 </sect2>
836 <sect2>
837 <title>Transférer les modifications à un autre dépôt</title>
839 <para>Mercurial vous laisse transférer les modifications à un autre
840 dépôt, depuis votre dépôt actuel. Comme dans l'exemple du
841 <command role="hg-cmd">hg pull</command> ci-dessus, nous allons créer un dépôt temporaire
842 vers lequel transférer\footnote{NdT: Les francophones disent souvent
843 <quote>pousser</quote> tout simplement} nos modifications.
844 <!-- &interaction.tour.clone-push; -->
845 La commande <command role="hg-cmd">hg outgoing</command> nous indique quels changements nous
846 allons transférer vers l'autre serveur ?
847 <!-- &interaction.tour.outgoing; -->
848 Et la commande <command role="hg-cmd">hg push</command> effectue réellement le transfert.
849 <!-- &interaction.tour.push; -->
850 Comme avec <command role="hg-cmd">hg pull</command>, la commande <command role="hg-cmd">hg push</command> ne met pas à jour
851 le répertoire de travail du dépôt dans lequel il transfère les
852 modifications. (À l'inverse de <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg push</command> ne fournit
853 pas d'option <literal>-u</literal> pour forcer la mise à jour de l'espace
854 de travail cible).
855 </para>
857 <para>Qu'est ce qui se passe lorsque vous essayez de récupérer ou de transférer
858 vos modifications et que le dépôt cible a déjà reçu ces modifications ?
859 Rien de bien excitant.
860 <!-- &interaction.tour.push.nothing; -->
861 </para>
863 </sect2>
864 <sect2>
865 <title>Partager ses modifications à travers le réseau</title>
867 <para>Les commandes que nous avons étudiées dans les sections précédentes
868 ne sont pas limitées aux dépôt locaux. Chacune fonctionne de la même
869 manière à travers une connexion réseau, il suffit de lui passer une
870 URL à la place d'un chemin de fichier local.
871 </para>
873 <para><!-- &interaction.tour.outgoing.net; -->
874 Dans cet exemple, nous allons voir quels changements nous pourrions
875 transférer vers le dépôt distant, mais le dépôt est, de manière tout
876 à fait compréhensible, pas configuré pour accepter des modifications
877 d'utilisateurs anonymes.
878 <!-- &interaction.tour.push.net; -->
879 </para>
881 </sect2>
882 </sect1>
883 </chapter>
885 <!--
886 local variables:
887 sgml-parent-document: ("00book.xml" "book" "chapter")
888 end:
889 -->