hgbook
view fr/tour-basic.tex @ 960:e3913a4b5b26
Fixing leftovers stuff from last merge with Wilkk
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Tue Feb 24 00:03:10 2009 +0100 (2009-02-24) |
| parents | f42151a42f9e |
| children |
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 uniques 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 distributions les plus courantes. 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écutez 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 à 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 installateur de Mercurial pour Mac OS~X sur le site
68 \url{http://mercurial.berkwood.com}. Ce paquetage fonctionne sur les
69 architectures Intel-~et PowerPC. Avant de vous en servir, vous devez
70 installer une version Universelle 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, utilisez \command{sudo fink install mercurial-py25}. Si vous avez
77 MacPorts, \command{sudo port install mercurial}.
79 \subsection{Windows}
81 Lee Cantey publie aussi un installateur 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 La version de Windows de Mercurial ne convertie pas automatiquement
87 les retours chariot Windows et Unix. Si vous désirez partager votre
88 travail avec des utilisateurs Unix, vous devez faire un peu de configuration
89 supplé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 importantes 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écutez 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épôt}
117 Avec Mercurial, tout se déroule au sein du \emph{dépôt}\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épôt, c'est
122 simplement une arborescence sur votre système de fichiers que Mercurial
123 traite de manière spéciale. 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épôt}
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 à 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 leur
144 historique. 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 dépôt sont à vous, et vous pouvez en faire ce que vous 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 \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 ponctuelle}\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 modifications 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 deux points
188 (:), d'une chaine hexadécimale. Il s'agit en fait d'\emph{identifiants}
189 d'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{user}] L'identité de la personne qui a créée ce %%% laisser le terme anglais car il sera affiché
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{fuseau horaire} dans laquelle il a été créé. %%%TODO: Translate 'timezone' properly : FUSEAU
197 (La date et l'heure sont locales à ce \textit{fuseau}, elles indiquent
198 donc quelle date et heure il était pour la personne qui a créé ce %%%TODO: je suppose (quelle "heure") OUI
199 \textit{changeset}.)
200 \item[\texttt{résumé}] La première du message que le créateur a associé à
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.
207 La figure~\ref{fig:tour-basic:history} fournit une représentation graphique
208 de l'historique du dépôt \dirname{hello}, pour rendre plus facile de voir
209 dans quelle direction l'historique se ``déroule''\footnote{NdT: \textit{flowing in}.}.
210 Nous reviendrons régulièrement sur cette représentation dans ce chapitre et
211 ceux qui suivent.
213 \begin{figure}[ht]
214 \centering
215 \grafix{tour-history}
216 \caption{Représentation graphique du dépôt \dirname{hello} }
217 \label{fig:tour-basic:history}
218 \end{figure}
220 \subsection{Changesets, révisions, et discuter avec les autres}%%%TODO: je propose : "discussion" (3 noms communs)
221 %%% je propose "colaboration"
223 Comme l'anglais est réputé pour être un langage maladroit, et que l'informatique
224 est la source de bien des erreurs de terminologies (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 discutez d'historique de Mercurial avec 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 contracté 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{changeset} \textit{spécifique} a une grande
237 importance. Rappelez vous que le champ \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éros de révision uniquement comme des raccourcis
258 pratiques. Si vous devez discuter d'un \textit{changeset} avec quelqu'un,
259 ou identifer 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 demander 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 %%%TODO : intervalle de numérotation ?
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 Le résumé affiché par \hgcmd{log} est suffisant si vous savez déjà ce %%%TODO: je pense que le premier "si" est de trop : exact
285 que vous cherchez. En revanche, vous aurez probablement besoin de voir une description
286 complète du changement, ou une liste des fichiers modifiés si vous
287 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 ?
288 recherchez. L'option \hgopt{-v} de la commande \hgcmd{log} (ou
289 \hgopt{--verbose}) vous donne ces 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 utilise une 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 commande \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, pour cette raison).
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 un 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 quelconque sortie à l'écran,
330 afficheront davantage 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 également moins d'espace disque.
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. : OUI
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 afin qu'il
365 affiche une seconde ligne à l'écran. (J'utilise \command{sed} seulement parce
366 qu'il est ainsi facile d'écrire des exemples sous forme de script. 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} et \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 de terminologie correcte, 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'environnement \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'environnement \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 fabriquera un nom d'utilisateur à partir de ces données. Comme il arrive
430 souvent que ce genre de noms soit totalement inutile, il vous
431 préviendra en affichant un message d'avertissement.
432 \end{enumerate}
434 Si tous ces mécanismes échouent, Mercurial n'exécutera pas la commande,
435 affichant un message d'erreur. Dans ce cas, il ne vous laissera pas
436 effectuer de \textit{commit} tant que vous n'aurez pas défini un nom
437 d'utilisateur.
439 Vous devriez penser à utiliser la variable d'environement \envar{HGUSER}
440 et l'option \hgopt{commit}{-u} comme moyen pour \emph{changer le nom
441 d'utilisateur} par défaut. Pour une utilisation normale, la manière la plus
442 simple et robuste d'opérer est de créer un fichier \sfilename{.hgrc},
443 voir ci-dessous pour les détails à ce sujet.
445 \subsubsection{Créer un fichier de configuration pour Mercurial}
446 \label{sec:tour-basic:username}
448 Pour définir un nom d'utilisateur, utilisez votre éditeur de texte favori
449 pour créer un fichier \sfilename{.hgrc} dans votre répertoire \textit{home}.
450 Mercurial va utiliser ce fichier pour retrouver votre configuration personnelle.
451 Le contenu initial devrait ressembler à ceci:
452 \begin{codesample2}
453 # This is a Mercurial configuration file.
454 [ui]
455 username = Firstname Lastname <email.address@domain.net>
456 \end{codesample2}
457 La ligne avec \texttt{[ui]} commence une \emph{section} du fichier de
458 configuration, ainsi la ligne ``\texttt{username = ...}'' signifie ``
459 définir la valeur de l'élément \texttt{username} dans la section
460 \texttt{ui}''. Une section continue jusqu'à ce qu'une nouvelle
461 commence, ou que la fin du fichier soit atteinte. Mercurial ignore
462 les lignes vides et traite tout texte situé à la suite d'un
463 ``\texttt{\#}'' jusqu'à la fin de la ligne comme un commentaire.
465 \subsubsection{Choisir un nom d'utilisateur}
467 Vous pouvez utiliser n'importe quelle valeur pour votre \texttt{username},
468 car cette information est destinée à d'autres personnes et non à être
469 interprétée par Mercurial. La convention que la plupart des personnes
470 <<<<<<< local
471 suivent est d'utiliser leurs noms suivies de leurs adresses emails,
472 comme montrée ci-dessus:
474 \begin{note}
475 Le mécanisme interne du serveur \textit{web} intégré à Mercurial,
476 masque les adresses emails, pour rendre plus difficile leurs
477 récupérations par les outils utilisés par les \textit{spammmers}.
478 Ceci réduit la probabilité que de recevoir encore plus de
479 \textit{spam} si vous vous publiez un dépôt sur internet.
480 \end{note}
482 \subsection{Rédiger un message de \textit{commit}}
484 Lorsqu'on effectue une opération de \textit{commit}, Mercurial
485 lance automatiquement un éditeur de texte pour permettre de saisir
486 un message qui décrira les modifications effectuées dans ce
487 \textit{changeset}. Ce message est nommé le \emph{message de
488 \textit{commit}}. Ce sera un enregistrement pour tout lecteur
489 expliquant le pourquoi et le comment de vos modifications, et il sera
490 affiché par la commande \hgcmd{log}.
491 \interaction{tour.commit}
493 L'éditeur que la commande \hgcmd{commit} déclenche ne contiendra
494 qu'une ligne vide suivi d'un certain nombre de lignes commençant
495 par ``\texttt{HG:}''.
496 \begin{codesample2}
497 \emph{empty line}
498 HG: changed hello.c
499 \end{codesample2}
500 Mercurial ignore les lignes qui commencent avec ``\texttt{HG:}'', il
501 ne les utilise que pour nous indiquer quels fichiers modifiés il se
502 prépare à \textit{commiter}. Modifier ou effacer ces lignes n'a
503 aucune conséquence sur l'opération de \textit{commit}.
505 \subsection{Rédiger un message \textit{approprié}}
507 Comme \hgcmd{log} n'affiche que la première ligne du message de
508 \textit{commit} par défaut, il est souvent considéré comme une bonne
509 pratique de rédiger des messages de \textit{commit} qui tiennent
510 sur une seule ligne. Voilà un exemple concret de message de
511 \textit{commit} qui \emph{ne suit pas} cette directive, et qui a donc
512 un résumé peu lisible.
514 \begin{codesample2}
515 changeset: 73:584af0e231be
516 user: Censored Person <censored.person@example.org>
517 date: Tue Sep 26 21:37:07 2006 -0700
518 summary: include buildmeister/commondefs. Add an exports and install
519 \end{codesample2}
521 A ce sujet, il faut noter qu'il n'existe pas de règle absolue dans ce
522 domaine. Mercurial lui-même n'interprète pas les contenus des messages
523 de \textit{commit}, ainsi votre projet est libre de concevoir différentes
524 politiques de mise en page des messages.
526 Ma préférence personnelle va au message court, mais informatif, qui offre
527 des précisions supplémentaires par rapport à ce que pourrait m'apprendre une commande
528 \hgcmdargs{log}{--patch}.
530 \subsection{Annuler un \textit{commit}}
532 Si, en rédigeant le message, vous décidez que finalement vous ne
533 voulez pas effectuer ce \textit{commit}, il suffit de quitter simplement
534 l'éditeur sans sauver. Ceci n'aura aucune conséquence sur le dépôt ou
535 les fichiers de l'espace de travail.
537 Si vous exécuter la commande \hgcmd{commit} sans aucun argument, elle
538 enregistre toutes les modifications que vous avez faites, comme le montre
539 les commandes \hgcmd{status} et \hgcmd{diff}.
541 \subsection{Admirer votre travail}
543 Une fois que votre \textit{commit} est terminé, vous pouvez utiliser
544 la commande \hgcmd{tip} pour afficher le \textit{changeset} que nous
545 venons de créer. Cette commande produit une sortie à l'écran qui est
546 identique à celle du \hgcmd{log}, mais qui n'affiche que la dernière
547 révision du dépôt.
548 \interaction{tour.tip}
549 On fait couramment référence à la dernière révision du dépôt comme
550 étant la révision \textit{tip}, ou plus simplement le \textit{tip}.
552 \section{Partager ses modifications}
554 Nous avons mentionné plus haut que les dépôts de Mercurial
555 sont autosuffisants. Ce qui signifie que le \textit{changeset}
556 que vous venez de créer existe seulement dans votre répertoire
557 \dirname{my-hello}. Étudions comment propager cette modification
558 dans d'autres dépôts.
560 \subsection{Récupérer les modifications d'autres dépôts}
561 \label{sec:tour:pull}
563 Pour commencer, construisons un clone de notre dépôt \dirname{hello}
564 qui ne contiendra pas le changement que nous venons d'effectuer. Nous
565 l'appellerons notre dépôt temporaire \dirname{hello-pull}.
567 \interaction{tour.clone-pull}
569 Nous allons utiliser la commande \hgcmd{pull} pour apporter les
570 modifications depuis \dirname{my-hello} dans \dirname{hello-pull}.
571 Néanmoins, récupérer aveuglement des modifications depuis un dépôt
572 a quelque chose d'un peu effrayant. Mercurial propose donc une
573 commande \hgcmd{incoming} qui permet de savoir quelles modifications
574 la commande \hgcmd{pull} \emph{pourrait} entraîner dans notre dépôt,
575 et ceci sans effectuer réellement de modification dessus.
576 \interaction{tour.incoming}
577 (Bien évidement, quelqu'un pourrait ajouter des modifications
578 supplémentaires sur le dépôt que nous étudions avec \hgcmd{incoming},
579 avant que nous ayons effectué notre \hgcmd{pull}, avec comme
580 triste conséquence que nous aurons récupéré des modifications que
581 nous n'attendions pas.)
583 Apporter les modifications rapatriées dans un dépôt se résume donc
584 à exécuter la commande \hgcmd{pull}, et préciser depuis quel dépôt
585 effectuer le \hgcmd{pull}.
586 \interaction{tour.pull}
588 Comme vous le voyez avec une sortie avant et après de la commande
589 \hgcmd{tip}, nous avons réussi à récupérer aisément les modifications
590 dans notre dépôt. Il reste néanmoins quelque chose à faire avant de
591 placer ces modifications dans l'espace de travail.
593 \subsection{Mise à jour de l'espace de travail}
595 Nous avons jusqu'à maintenant grossièrement définie la relation
596 entre un dépôt et un espace de travail. La commande \hgcmd{pull} que
597 nous avons exécutée dans la section~\ref{sec:tour:pull} a apporté
598 des modifications, que nous avons vérifiées, dans notre dépôt, mais
599 il n'y a aucune trace de ces modifications dans notre espace de travail.
600 En effet, \hgcmd{pull} ne touche pas (par défaut) à l'espace de
601 travail. C'est la commande \hgcmd{update} qui s'en charge.
602 \interaction{tour.update}
604 Il peut sembler un peu étrange que la commande \hgcmd{pull} ne mette
605 pas à jour l'espace de travail automatiquement. Il y a en fait une
606 très bonne raison à cela : vous pouvez utilisez la commande
608 \hgcmd{update} pour mettre à jour votre espace de travail à l'état
609 dans lequel il était à \emph{n'importe quelle révision} de l'historique
610 du dépôt. Si vous aviez un espace de travail contenant une ancienne
611 révision---pour chercher l'origine d'un \textit{bug}, par exemple---et
612 que vous effectuiez un \hgcmd{pull} qui mettrait à jour automatiquement
613 votre espace de travail, vous ne seriez probablement pas très satisfait.
615 Néanmoins, comme les opérations de \textit{pull} sont très souvent
616 suivies d'un \textit{update}, Mercurial vous permet de combiner les
617 deux aisément en passant l'option \hgopt{pull}{-u} à la commande
618 \hgcmd{pull}
619 \begin{codesample2}
620 hg pull -u
621 \end{codesample2}
623 Si vous étudiez de nouveau la sortie de la commande \hgcmd{pull} dans
624 la section~\ref{sec:tour:pull} quand nous l'avons exécutée sans l'option
625 \hgopt{pull}{-u}, vous pouvez constater qu'elle a affiché un rappel assez
626 utile : vous devez encore effectuer une opération pour mettre à jour
627 votre espace de travail:
629 \begin{codesample2}
630 (run 'hg update' to get a working copy)
631 \end{codesample2}
633 Pour découvrir sur quelle révision de l'espace de travail on est, utilisez
634 la commande \hgcmd{parents}.
635 \interaction{tour.parents}
636 Si vous regardez de nouveau le dessin~\ref{fig:tour-basic:history}, vous
637 <<<<<<< local
638 verrez les flèches reliant entre eux les \textit{changeset}. Le nœud
639 d'où la flèche \emph{part} est dans chaque cas un parent,
640 et le nœud où la flèche \emph{arrive} est un enfant.
642 L'espace de travail a un parent de la même manière, c'est ce \textit{changeset}
643 que l'espace de travail contient à ce moment.
644 %%%TODO : difficile à comprendre : l'espace de travail a un parent, de la même manière, c'est ce changeset que l'espace...
646 Pour mettre à jour l'espace de travail d'une révision particulière,
647 indiquez un numéro de révision ou un \textit{changeset~ID} à la commande
648 \hgcmd{update}.
649 \interaction{tour.older}
650 Si vous ne précisez pas de manière explicite de numéro de révision
651 la commande \hgcmd{update} mettra à jour votre espace de travail avec
652 le contenu de la révsion \textit{tip}, comme montré dans l'exemple
653 ci dessus lors du second appel à \hgcmd{update}.
655 \subsection{Transférer les modifications à un autre dépôt}
657 Mercurial vous laisse transférer les modifications à un autre
658 dépôt, depuis votre dépôt actuel. Comme dans l'exemple du
659 \hgcmd{pull} ci-dessus, nous allons créer un dépôt temporaire
660 vers lequel transférer\footnote{NdT: Les francophones disent souvent
661 ``pousser'' tout simplement} nos modifications.
662 \interaction{tour.clone-push}
663 La commande \hgcmd{outgoing} nous indique quels changements nous
664 allons transférer vers l'autre serveur ?
665 \interaction{tour.outgoing}
666 Et la commande \hgcmd{push} effectue réellement le transfert.
667 \interaction{tour.push}
668 Comme avec \hgcmd{pull}, la commande \hgcmd{push} ne met pas à jour
669 le répertoire de travail du dépôt dans lequel il transfère les
670 modifications. (À l'inverse de \hgcmd{pull}, \hgcmd{push} ne fournit
671 pas d'option \texttt{-u} pour forcer la mise à jour de l'espace
672 de travail cible).
674 Qu'est ce qui se passe lorsque vous essayez de récupérer ou de transférer
675 vos modifications et que le dépôt cible a déjà reçu ces modifications ?
676 Rien de bien excitant.
677 \interaction{tour.push.nothing}
679 \subsection{Partager ses modifications à travers le réseau}
681 Les commandes que nous avons étudiées dans les sections précédentes
682 ne sont pas limitées aux dépôt locaux. Chacune fonctionne de la même
683 manière à travers une connexion réseau, il suffit de lui passer une
684 URL à la place d'un chemin de fichier local.
686 \interaction{tour.outgoing.net}
687 Dans cet exemple, nous allons voir quels changements nous pourrions
688 transférer vers le dépôt distant, mais le dépôt est, de manière tout
689 à fait compréhensible, pas configuré pour accepter des modifications
690 d'utilisateurs anonymes.
691 \interaction{tour.push.net}
693 %%% Local Variables:
694 %%% mode: latex
695 %%% TeX-master: "00book"
696 %%% End: