hgbook
view fr/appA-svn.xml @ 1001:669ae1a09e46
French translation : ch04-concepts translated
| author | Frédéric Bouquet <youshe.jaalon@gmail.com> |
|---|---|
| date | Mon Sep 14 01:18:56 2009 +0200 (2009-09-14) |
| parents | cc81b4175833 |
| children |
line source
3 <appendix id="svn">
4 <?dbhtml filename="migrating-to-mercurial.html"?>
5 <title>Migrer vers Mercurial</title>
7 <para id="x_6e1">Une manière courante de s'essayer à un nouveau
8 gestionnaire de révisions est d'expérimenter en migrant un
9 projet existant, plutôt que le faire avec un nouveau projet.
10 </para>
12 <para id="x_6e2">Dans cette annexe, nous discuterons comment importer
13 l'historique d'un projet dans Mercurial, et à quoi faire attention
14 si vous êtes habitués à un autre outil de gestion de révisions.
15 </para>
17 <sect1>
18 <title>Importer l'historique depuis un autre système</title>
20 <para id="x_6e3">Mercurial est livré avec une extension nommée
21 <literal>convert</literal>, qui permet d'importer un historique
22 depuis les gestionnaire de révisions les plus courants. Au moment de
23 l'écriture de ce livre, il pouvait importer l'historique depuis:
24 </para>
25 <itemizedlist>
26 <listitem>
27 <para id="x_6e4">Subversion</para>
28 </listitem>
29 <listitem>
30 <para id="x_6e5">CVS</para>
31 </listitem>
32 <listitem>
33 <para id="x_6e6">git</para>
34 </listitem>
35 <listitem>
36 <para id="x_6e7">Darcs</para>
37 </listitem>
38 <listitem>
39 <para id="x_6e8">Bazaar</para>
40 </listitem>
41 <listitem>
42 <para id="x_6e9">Monotone</para>
43 </listitem>
44 <listitem>
45 <para id="x_6ea">GNU Arch</para>
46 </listitem>
47 <listitem>
48 <para id="x_6eb">Mercurial</para>
49 </listitem>
50 </itemizedlist>
52 <para id="x_6ec">(Pour savoir pourquoi Mercurial lui même est supporté
53 comme source, voir <xref linkend="svn.filemap"/>.)</para>
55 <para id="x_6ed">Vous pouvez activer l'extension de la manière
56 habituelle, en éditant votre fichier <filename>~/.hgrc</filename></para>
58 <programlisting>[extensions]
59 convert =</programlisting>
61 <para id="x_6ee">Ceci rendra la commande <command>hg convert</command>
62 disponible. La commande est facile à utiliser. Par exemple, la
63 commande suivante va importer l'historique Subversion du <emphasis
64 remap="it">framework</emphasis> de test <quote>Nose Unit</quote> dans Mercurial.
65 </para>
67 <screen><prompt>$</prompt> <userinput>hg convert http://python-nose.googlecode.com/svn/trunk</userinput></screen>
69 <para id="x_6ef">L'extension <literal>convert</literal> opère de
70 manière incrémentale. En d'autres mots, après une première exécution de
71 la commande <command>hg convert</command>, les exécutions ultérieures
72 importeront les révisions ultérieures à l'exécution précédente.
73 La conversion incrémentale ne réussira que si
74 vous exécutez <command>hg convert</command> dans le même dépôt que vous
75 aviez utilisé à l'origine, ceci parce que l'extension <literal>convert</literal>
76 sauvegarde un certain nombre de méta-données privées dans le fichier
77 <filename>.hg/shamap</filename> (non versioné) au sein du dépôt cible.
78 </para>
80 <para id="x_707">Lorsque vous voulez faire des modifications en utilisant
81 Mercurial, le mieux est de faire un clone de l'ensemble de l'arborescence
82 que vous souhaitez convertir, et de laisser l'arborescence d'origine pour
83 de futures conversions incrémentales. C'est la manière la plus sûre pour vous laisser
84 récupérer et fusionner les modifications futures depuis l'outil de gestion
85 de révisions dans votre nouveau dépôt Mercurial.</para>
87 <sect2>
88 <title>Convertir plusieurs branches</title>
90 <para id="x_708">La commande <command>hg convert</command> citée
91 ci-dessus convertit seulement l'historique de la <literal>branche
92 principale (trunk)</literal> du dépôt Subversion. Si nous utilisons
93 à la place l'URL <literal>http://python-nose.googlecode.com/svn</literal>,
94 Mercurial va automatiquement détecter la
95 <literal>branche principale (trunk)</literal>, les <literal>étiquettes
96 (tags)</literal>, et les <literal>branches</literal> que les dépôts
97 Subversion utilisent généralement, et les importera chacun dans
98 une branche Mercurial distincte.</para>
100 <para id="x_709">Par défaut, chaque branche Subversion importée
101 dans Mercurial se voit attribuer un nom de branche. Une fois la
102 conversion achevée, vous pouvez obtenir la liste des noms des branches
103 actives dans le dépôt Mercurial en utilisant la commande
104 <command>hg branches -a</command>. Si vous préférez importer les
105 branches Subversion sans noms, ajoutez l'option <option>--config
106 convert.hg.usebranches=false</option> à la commande
107 <command>hg convert</command>.</para>
109 <para id="x_70a">Une fois votre arborescence convertie,
110 si vous souhaitez travailler selon la pratique habituelle sous Mercurial
111 avec une arborescence qui ne contient qu'une seule branche, vous pouvez cloner
112 cette seule branche en utilisant
113 <command>hg clone -r nomdemabranche</command>.</para>
114 </sect2>
116 <sect2>
117 <title>Associer les noms d'utilisateurs</title>
119 <para id="x_6f0">Certains outils de gestion de révisions
120 ne sauvegardent, avec les modifications, que les noms
121 d'utilisateurs raccourcis. Ceux-ci peuvent être difficiles à
122 interpréter. La norme avec Mercurial est de sauvegarder le
123 nom du <emphasis remap="it">committeur</emphasis> et son adresse
124 mail, ce qui est beaucoup plus utile pour discuter avec lui
125 par la suite.</para>
127 <para id="x_6f1">Si vous convertissez une arborescence depuis
128 un gestionnaire de révisions qui utilise seulement les noms
129 raccourcis, vous pouvez associer ces noms à des équivalents
130 plus détaillés en passant l'option <option>--authors</option>
131 à la commande <command>hg convert</command>. Cette option
132 attend un fichier qui contient des entrées sous la forme suivante:
133 </para>
135 <programlisting>arist = Aristotle <aristotle@phil.example.gr>
136 soc = Socrates <socrates@phil.example.gr></programlisting>
138 <para id="x_6f2">Quand <literal>convert</literal> trouve une
139 modification associée au nom <literal>arist</literal> dans le
140 dépôt de source, il va utiliser le nom <literal>Aristotle
141 <aristotle@phil.example.gr></literal> dans les révisions
142 Mercurial. Si aucune correspondance n'est trouvé, il utilise
143 le nom tel quel.</para>
144 </sect2>
146 <sect2 id="svn.filemap">
147 <title>Nettoyer l'arboresence</title>
149 <para id="x_6f3">Tous les projets n'ont pas un historique parfait.
150 Il peut y avoir des répertoires qui n'auraient jamais dû être ajoutés,
151 un fichier qui est trop volumineux, ou même une partie de la
152 hiérarchie qui devrait être réorganisée.</para>
154 <para id="x_6f4">L'extension <literal>convert</literal> permet
155 d'utiliser un <quote>fichier d'association</quote> qui peut
156 réorganiser les fichiers et les répertoires dans un projet lors de
157 l'importation de son historique. Ceci est utile non seulement quand vous
158 importez l'historique d'un autre gestionnaire de révisions, mais
159 aussi pour nettoyer ou réorganiser l'arborescence d'un projet
160 Mercurial.</para>
162 <para id="x_6f5">Pour indiquer le fichier d'association, on utilise
163 l'option <option>--filemap</option> en lui fournissant un nom de
164 fichier. Le fichier d'association contient des lignes de la forme
165 suivante :</para>
167 <programlisting># Ceci est un commentaire.
168 # Les lignes vides sont ignorées.
170 include path/to/file
172 exclude path/to/file
174 rename from/some/path to/some/other/place
175 </programlisting>
177 <para id="x_6f6">La directive <literal>include</literal> inclut un
178 fichier, ou l'ensemble des fichiers d'un répertoire, dans le dépôt
179 de destination. La directive <literal>exclude</literal> omet les
180 fichiers ou répertoires du dépôt. Ceci inclut aussi les autres
181 fichiers et répertoires qui ne sont pas explicitement inclus.
182 La directive <literal>exclude</literal> entraine l'omission
183 des fichiers ou répertoires, et autres fichiers qui ne sont pas
184 explicitement inclus.</para>
186 <para id="x_6f7">Pour déplacer un fichier ou un répertoire d'un
187 emplacement à un autre, utilisez la directive
188 <literal>rename</literal>. Si vous avez besoin de déplacer un
189 fichier ou un répertoire depuis un sous répertoire dans la racine
190 du dépôt, utilisez <literal>.</literal> comme second argument de
191 la directive <literal>rename</literal>.</para>
192 </sect2>
194 <sect2>
195 <title>Améliorer les performances de la conversion Subversion</title>
197 <para id="x_70b">Vous aurez souvent besoin de plusieurs essais
198 avant d'arriver à la parfaite combinaison de fichier d'association de fichiers,
199 de fichier d'association de noms d'utilisateurs et des autres paramètres. Or,
200 convertir un dépôt Mercurial via un protocole comme <literal>ssh</literal>
201 ou <literal>http</literal> peut être des milliers de fois plus long
202 que ce dont le système d'exploitation est en fait capable de faire,
203 à cause des latence réseau. Ceci peut rendre la conception de cette
204 combinaison parfaite très douloureuse.</para>
206 <para id="x_70c">La commande <ulink
207 url="http://svn.collab.net/repos/svn/trunk/notes/svnsync.txt"><command>svnsync</command></ulink>
208 peut grandement améliorer la vitesse de conversion d'un dépôt
209 Subversion. Il s'agit d'un programme de miroir de dépôt Subversion
210 en lecture seule. L'idée est de créer un miroir local d'une
211 arborescence Subversion, puis de convertir ce miroir en dépôt
212 Mercurial.</para>
214 <para id="x_70d">Supposez que nous voulions convertir le dépôt
215 Subversion du populaire projet Memcached en une arborescence Mercurial.
216 Tout d'abord, nous créons un dépôt Subversion local.</para>
218 <screen><prompt>$</prompt> <userinput>svnadmin create memcached-mirror</userinput></screen>
220 <para id="x_70e">Puis, nous allons mettre en place un <quote>hook</quote> Subversion
221 dont <command>svnsync</command> a besoin.</para>
223 <screen><prompt>$</prompt> <userinput>echo '#!/bin/sh' > memcached-mirror/hooks/pre-revprop-change</userinput>
224 <prompt>$</prompt> <userinput>chmod +x memcached-mirror/hooks/pre-revprop-change</userinput></screen>
226 <para id="x_70f">Nous initialisons ensuite <command>svnsync</command> dans ce
227 dépôt.</para>
229 <screen><prompt>$</prompt> <userinput>svnsync --init file://`pwd`/memcached-mirror \
230 http://code.sixapart.com/svn/memcached</userinput></screen>
232 <para id="x_710">La prochaine étape est de commencer le processus de
233 mirroring de <command>svnsync</command>.</para>
235 <screen><prompt>$</prompt> <userinput>svnsync sync file://`pwd`/memcached-mirror</userinput></screen>
237 <para id="x_711">Enfin, nous importons l'historique de notre dépôt
238 local Subversion dans Mercurial.</para>
240 <screen><prompt>$</prompt> <userinput>hg convert memcached-mirror</userinput></screen>
242 <para id="x_712">Nous pouvons utiliser ce processus de manière
243 incrémentale, si le dépôt Subversion est toujours en activité.
244 Il suffit d'exécuter de nouveau <command>svnsync</command> pour
245 récupérer les récentes modifications dans notre miroir, puis <command>hg
246 convert</command>
247 les importe dans notre arborescence Mercurial.</para>
249 <para id="x_713">Il y a deux avantages à utiliser un import à deux
250 étages comme avec <command>svnsync</command>. Le premier
251 est qu'il utilise du code de synchronisation réseau de Subversion
252 plus efficace que la commande <command>hg convert</command>,
253 et donc transfère moins de données par le réseau. Le deuxième
254 est que l'import depuis un dépôt Subversion local est si rapide que
255 vous pouvez peaufiner et réitérer les paramètres de conversion de
256 ce dernier sans souffrir de la qualité de la connexion réseau.</para>
257 </sect2>
258 </sect1>
260 <sect1>
261 <title>Migrer depuis Subversion</title>
263 <para id="x_6f8">Subversion est le système de gestion de versions
264 open source le plus populaire aujourd'hui. Bien qu'il y ait des
265 différences entre Mercurial et Subversion, faire la transition de
266 l'un à l'autre n'est pas très difficile. Les deux disposent en effet
267 de jeux de commandes similaires et d'interfaces similaires.</para>
269 <sect2>
270 <title>Différences philosophiques</title>
272 <para id="x_6f9">La différence fondamentale entre Subversion et
273 Mercurial est bien évidement que Subversion est centralisé, alors
274 que Mercurial est distribué. Puisque que Mercurial enregistre tout
275 l'historique d'un projet sur votre disque dur local, il n'a besoin
276 d'effectuer des accès au réseau que lorsque vous voulez
277 explicitement communiquer avec un autre dépôt. Subversion, par contre,
278 ne conserve que peu d'informations localement, et le client
279 doit donc communiquer avec le serveur central pour la
280 plupart des opérations communes.</para>
282 <para id="x_6fa">Subversion s'en tire plus ou moins bien sans notion
283 de branche réellement bien définie : quelle portion de l'espace de nommage
284 du serveur est une branche est une simple question de convention, le
285 logiciel n'imposant rien à ce sujet. Mercurial considère
286 un dépôt comme un élément de la gestion des branches.</para>
288 <sect3>
289 <title>Portée des commandes</title>
291 <para id="x_6fb">Puisque que Subversion ne sait pas réellement
292 quelle partie de son espace de nommage est en fait une branche, il
293 traite la plupart des commandes comme des requêtes à exécuter sur le
294 répertoire où vous vous situez, et ses sous répertoires. Par exemple,
295 si vous exécutez <command>svn log</command>, vous verrez l'historique
296 de la partie de l'arborescence où vous vous situez, et non de la
297 hiérarchie entière.</para>
299 <para id="x_6fc">Les commandes de Mercurial ont un comportement
300 différent : toutes les commandes s'appliquent à l'ensemble de l'arborescence
301 du dépôt. Exécutez la commande <command>hg log</command> et elle vous
302 donnera l'historique de l'ensemble de l'arborescence, quel que soit le
303 sous-répertoire où vous vous situez. Si
304 vous souhaitez obtenir l'historique d'un répertoire ou seulement d'un
305 fichier, ajouter simplement le nom de celui-ci à la commande, par
306 exemple <command>hg log src</command>.</para>
308 <para id="x_6fd">De ma propre expérience, cette différence dans leur
309 comportement par défaut est probablement ce qui risque de vous
310 surprendre le plus si vous passez régulièrement d'un outil à l'autre.</para>
311 </sect3>
313 <sect3>
314 <title>Opération multi utilisateur et sécurité</title>
316 <para id="x_6fe">Avec Subversion, il est normal (bien que légèrement
317 désapprouvé) que différentes personnes collaborent sur une seule
318 branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses
319 modifications à leur branche partagée, Bob doit alors mettre à jour
320 sa vue de la branche avant de pouvoir appliquer un commit.
321 Puisqu'il n'a, à ce moment, pas effectué de commit
322 des modifications qu'il a faites, il se peut qu'il ne corrompe
323 ou ne perde
324 ses modifications pendant ou après la mise à jour.</para>
326 <para id="x_6ff">Mercurial encourage, à l'inverse, un modèle
327 "commit-puis-merge". Avant de récupérer des modifications depuis le
328 serveur, ou avant d'y envoyer les siennes, Bob enregistre ses
329 modifications de manière locale en appliquant un commit. C'est à dire
330 que si Alice avait envoyé ses modifications sur le serveur avant
331 que Bob n'envoie les siennes, ce dernier ne pourra le faire
332 qu'après avoir récupéré et fusionné celles d'Alice avec les siennes.
333 Si Bob fait alors une
334 erreur lors de la fusion, il pourra toujours restaurer sa version, pour
335 laquelle il avait appliqué le commit.</para>
337 <para id="x_700">Il est important de souligner qu'il s'agit de la
338 manière habituelle de travailler avec ces outils. Subversion propose
339 une manière plus sûre de "travailler-dans-votre-propre-branche", mais elle
340 est assez complexe pour que, en pratique, elle ne soit que rarement utilisé.
341 Mercurial propose de son côté un mode un peu moins sûr, permettant de
342 récupérer des modifications par dessus des modifications non
343 committées, qui reste toutefois très peu répandu.</para>
344 </sect3>
346 <sect3>
347 <title>Publication vs changement locaux</title>
349 <para id="x_701">Une commande Subversion <command>svn
350 commit</command> publie immédiatement les modifications sur le
351 serveur, où elles peuvent être vu par n'importe qui doté d'un privilège
352 de lecture.</para>
354 <para id="x_702">Avec Mercurial, les modifications sont toujours d'abord
355 enregistrées localement, et doivent être par la suite transférés par
356 la commande <command>hg push</command>.</para>
358 <para id="x_703">Chaque approche a ses avantages et ses inconvénients.
359 Le modèle Subversion implique que les modifications soient publiées, et
360 donc disponibles immédiatement. D'un autre coté, cela implique aussi
361 que, pour pouvoir utiliser le logiciel normalement, un utilisateur doit
362 avoir les droits d'écriture dans le dépôt, et ce privilège n'est pas concédé
363 facilement par la plupart des projets Open Source.</para>
365 <para id="x_704">L'approche de Mercurial permet à quiconque de faire
366 un clone du dépôt et d'y ajouter ses modifications sans jamais avoir
367 besoin de la permission de quiconque, et l'on peut même publier ses
368 modifications et continuer à participer comme on le désire. Toutefois, la
369 distinction entre les commits et le transfert de ces derniers présente
370 le risque que quelqu'un applique ses modifications par un commit local
371 sur son portable et parte se promener pendant quelques jours en ayant
372 oublié de les transférer, ce qui peut, dans certains rares cas,
373 bloquer temporairement ses collaborateurs.</para>
374 </sect3>
375 </sect2>
377 <sect2>
378 <title>Références des commandes</title>
380 <table>
381 <title>Commandes Subversion et leurs équivalents Mercurial</title>
382 <tgroup cols="3">
383 <thead>
384 <row>
385 <entry>Subversion</entry>
386 <entry>Mercurial</entry>
387 <entry>Notes</entry>
388 </row>
389 </thead>
390 <tbody>
391 <row>
392 <entry><command>svn add</command></entry>
393 <entry><command>hg add</command></entry>
394 <entry></entry>
395 </row>
396 <row>
397 <entry><command>svn blame</command></entry>
398 <entry><command>hg annotate</command></entry>
399 <entry></entry>
400 </row>
401 <row>
402 <entry><command>svn cat</command></entry>
403 <entry><command>hg cat</command></entry>
404 <entry></entry>
405 </row>
406 <row>
407 <entry><command>svn checkout</command></entry>
408 <entry><command>hg clone</command></entry>
409 <entry></entry>
410 </row>
411 <row>
412 <entry><command>svn cleanup</command></entry>
413 <entry>n/a</entry>
414 <entry>Aucun nettoyage nécessaire.</entry>
415 </row>
416 <row>
417 <entry><command>svn commit</command></entry>
418 <entry><command>hg commit</command>; <command>hg
419 push</command></entry>
420 <entry><command>hg push</command> publie les modifications
421 après un commit.</entry>
422 </row>
423 <row>
424 <entry><command>svn copy</command></entry>
425 <entry><command>hg clone</command></entry>
426 <entry>Pour créer une nouvelle branche</entry>
427 </row>
428 <row>
429 <entry><command>svn copy</command></entry>
430 <entry><command>hg copy</command></entry>
431 <entry>Pour copier des fichiers ou des répertoires</entry>
432 </row>
433 <row>
434 <entry><command>svn delete</command> (<command>svn
435 remove</command>)</entry>
436 <entry><command>hg remove</command></entry>
437 <entry></entry>
438 </row>
439 <row>
440 <entry><command>svn diff</command></entry>
441 <entry><command>hg diff</command></entry>
442 <entry></entry>
443 </row>
444 <row>
445 <entry><command>svn export</command></entry>
446 <entry><command>hg archive</command></entry>
447 <entry></entry>
448 </row>
449 <row>
450 <entry><command>svn help</command></entry>
451 <entry><command>hg help</command></entry>
452 <entry></entry>
453 </row>
454 <row>
455 <entry><command>svn import</command></entry>
456 <entry><command>hg addremove</command>; <command>hg
457 commit</command></entry>
458 <entry></entry>
459 </row>
460 <row>
461 <entry><command>svn info</command></entry>
462 <entry><command>hg parents</command></entry>
463 <entry>Affiche la version sur la base de laquelle on travaille</entry>
464 </row>
465 <row>
466 <entry><command>svn info</command></entry>
467 <entry><command>hg showconfig
468 paths.default</command></entry>
469 <entry>Affiche de quelle URL est extrait ce dépôt</entry>
470 </row>
471 <row>
472 <entry><command>svn list</command></entry>
473 <entry><command>hg manifest</command></entry>
474 <entry></entry>
475 </row>
476 <row>
477 <entry><command>svn log</command></entry>
478 <entry><command>hg log</command></entry>
479 <entry></entry>
480 </row>
481 <row>
482 <entry><command>svn merge</command></entry>
483 <entry><command>hg merge</command></entry>
484 <entry></entry>
485 </row>
486 <row>
487 <entry><command>svn mkdir</command></entry>
488 <entry>n/a</entry>
489 <entry>Mercurial ne versionne pas les répertoires</entry>
490 </row>
491 <row>
492 <entry><command>svn move</command> (<command>svn
493 rename</command>)</entry>
494 <entry><command>hg rename</command></entry>
495 <entry></entry>
496 </row>
497 <row>
498 <entry><command>svn resolved</command></entry>
499 <entry><command>hg resolve -m</command></entry>
500 <entry></entry>
501 </row>
502 <row>
503 <entry><command>svn revert</command></entry>
504 <entry><command>hg revert</command></entry>
505 <entry></entry>
506 </row>
507 <row>
508 <entry><command>svn status</command></entry>
509 <entry><command>hg status</command></entry>
510 <entry></entry>
511 </row>
512 <row>
513 <entry><command>svn update</command></entry>
514 <entry><command>hg pull -u</command></entry>
515 <entry></entry>
516 </row>
517 </tbody>
518 </tgroup>
519 </table>
520 </sect2>
521 </sect1>
523 <sect1>
524 <title>Conseils utiles pour les débutants</title>
526 <para id="x_705">Avec la plupart des gestionnaire de versions, afficher
527 un diff associé à une révision peut être assez douloureux. Par exemple,
528 avec Subversion, pour voir ce qui a été modifiée dans la révision 104654,
529 vous devez saisir <command>svn diff -r104653:104654</command>. Mercurial
530 élimine le besoin de saisir l'identifiant d'une révision deux fois dans
531 ce cas classique. Pour un simple diff, <command>hg
532 export 104654</command> suffit. Pour obtenir une entrée du journal suivie d'un diff,
533 <command>hg log -r104654 -p</command>.</para>
535 <para id="x_706">Quand vous exécutez la commande <command>hg status</command>
536 sans aucun argument, elle affiche l'état de l'ensemble de l'arborescence,
537 avec des chemins relatifs partant de la racine du dépôt. Ceci rend
538 difficile de copier un nom de fichier depuis la sortie de la commande
539 <command>hg status</command> dans une autre ligne de commande. Si vous
540 fournissez un fichier ou un répertoire à la commande <command>hg
541 status</command>, elle va afficher les chemins relatif depuis votre
542 répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble
543 de l'arborescence à l'aide de <command>hg status</command>, avec des
544 chemins relatifs à votre répertoire courant, et non la racine du dépôt,
545 ajoutez la sortie de <command>hg root</command> à la commande
546 <command>hg status</command>. Vous pouvez le faire aisément sur un
547 système Unix ainsi :</para>
549 <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
550 </sect1>
551 </appendix>
553 <!--
554 local variables:
555 sgml-parent-document: ("00book.xml" "book" "appendix")
556 end:
557 -->