hgbook
view fr/appA-svn.xml @ 977:719b03ea27c8
merge with Italian, and very (few) work on ch03
| author | Romain PELISSE <belaran@gmail.com> |
|---|---|
| date | Fri Sep 04 16:33:46 2009 +0200 (2009-09-04) |
| parents | 030ccd6c5474 |
| children | 58e0737da566 |
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é à 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éussiera 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ôt
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. Hors,
200 convertir un dépôt Mercurial via un protocol 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 arboresence 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 arboresence 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 connection 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'information 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écuter <command>svn log</command>, vous verrez l'historique
296 de la partie de l'arboresence où vous vous situez, et non la
297 hiérarchie entière.</para>
299 <para id="x_6fc">Les commandes de Mercurial ont un comportement
300 différents, appliquant toutes commandes à l'ensemble de l'arboresence
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'arboresence, quelque soit le
303 répertoire de cette dernière où vous vous situez à ce moment là. Si
304 vous souhaitez l'historique d'une répertoire ou seulement d'un
305 fichier, ajouter simplement le nom de celui-ci à la commande
306 <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 si vous basculez 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ée) que différentes personnes collaborent sur une seule
318 branche. Si Alice et Bob travaillent ensemble, et Alice ajoute ses
319 modications à leur branche partagée, Bob doit alors mettre à jour
320 la vue de la banche de son client avant d'ajouter lui même ses
321 modifications. Puisqu'il n'a, à ce moment, aucun enregistrement
322 permanent des modifications qu'il a fait, il peut corrompre ou perdre
323 des modifications pendant et après sa mise à jour.</para>
325 <para id="x_6ff">Mercurial encourage, à l'inverse, un modèle
326 "commit-puis-merge". Bob ajoute ses modifications de manière locale
327 avant de récupérer les modifications d'Alice, ou d'envoyer les siennes
328 au serveur qu'ils partagent. Si Alice envoye ses modifications avant
329 que Alice n'envoye les siennes, il ne pourra envoyer ses
330 modifications avant d'avoir récupérer les siennes. Si il fait une
331 erreur lors de la fusion, il peut toujours à sa version d'origine,
332 telle qu'elle a été enregistré.</para>
334 <para id="x_700">Il est important de souligner qu'il s'agit de la
335 manière habituelle de travailler avec ses outils. Subversion propose
336 une manière plus sûr de travailler-dans-votre-propre-branche, mais il
337 est assez complexe pour que, en pratique, il ne soit jamais utiliser.
338 Mercurial propose un mode, un peu moyen sûr, mais permettant de
339 récupérer des modifications par dessus des modifications non
340 commitées, mais c'est considéré comme assez inhabituel.</para>
341 </sect3>
343 <sect3>
344 <title>Publication vs changement locaux</title>
346 <para id="x_701">Une commande Subversion <command>svn
347 commit</command> publie immédiatement les modifications sur le
348 serveur, où ils peuvent être vu par n'importe qui doté du privilège
349 de lecture.</para>
351 <para id="x_702">Avec Mercurial, les modifications sont toujours
352 enregistrées localement, et doivent être par la suite transférer par
353 la commande <command>hg push</command>.</para>
355 <para id="x_703">Chaque approche à ses avantages et ses désavantages.
356 Le modèle Subversion implique que les modifications sont publiées, et
357 donc disponible immédiatement. D'un autre coté, il implique aussi
358 qu'un utilisateur doit avoir le droit d'écriture dans le dépôt pour
359 permettre l'utiliser normalement, et ce privilège n'est pas concédé
360 facilement par les projets Open Source.</para>
362 <para id="x_704">L'approche de Mercurial permet à quiquonque de faire
363 un clone du dépôt et d'y ajouter ses modifications sans jamais avoir
364 besoin de la permission de quiquonque, et l'on peut même publier ses
365 modifications et continuer à participer comme on le désir. La
366 distinction entre les commits et le transfert de ces derniers ouvre
367 la possibilité néanmoins que quelqu'un oublie pendant une longue
368 période de transférer ses modifications, ce qui dans certains cas
369 rares, peut piéger ses collaborateurs.</para>
370 </sect3>
371 </sect2>
373 <sect2>
374 <title>Références des commandes</title>
376 <table>
377 <title>Commandes Subversion et leurs équivalents Mercurial</title>
378 <tgroup cols="3">
379 <thead>
380 <row>
381 <entry>Subversion</entry>
382 <entry>Mercurial</entry>
383 <entry>Notes</entry>
384 </row>
385 </thead>
386 <tbody>
387 <row>
388 <entry><command>svn add</command></entry>
389 <entry><command>hg add</command></entry>
390 <entry></entry>
391 </row>
392 <row>
393 <entry><command>svn blame</command></entry>
394 <entry><command>hg annotate</command></entry>
395 <entry></entry>
396 </row>
397 <row>
398 <entry><command>svn cat</command></entry>
399 <entry><command>hg cat</command></entry>
400 <entry></entry>
401 </row>
402 <row>
403 <entry><command>svn checkout</command></entry>
404 <entry><command>hg clone</command></entry>
405 <entry></entry>
406 </row>
407 <row>
408 <entry><command>svn cleanup</command></entry>
409 <entry>n/a</entry>
410 <entry>Aucun nettoyage nécessaire.</entry>
411 </row>
412 <row>
413 <entry><command>svn commit</command></entry>
414 <entry><command>hg commit</command>; <command>hg
415 push</command></entry>
416 <entry><command>hg push</command> publie les modifications
417 après leur enregistrement.</entry>
418 </row>
419 <row>
420 <entry><command>svn copy</command></entry>
421 <entry><command>hg clone</command></entry>
422 <entry>Pour créer une nouvelle branche</entry>
423 </row>
424 <row>
425 <entry><command>svn copy</command></entry>
426 <entry><command>hg copy</command></entry>
427 <entry>Pour copier des fichiers ou des répertoires</entry>
428 </row>
429 <row>
430 <entry><command>svn delete</command> (<command>svn
431 remove</command>)</entry>
432 <entry><command>hg remove</command></entry>
433 <entry></entry>
434 </row>
435 <row>
436 <entry><command>svn diff</command></entry>
437 <entry><command>hg diff</command></entry>
438 <entry></entry>
439 </row>
440 <row>
441 <entry><command>svn export</command></entry>
442 <entry><command>hg archive</command></entry>
443 <entry></entry>
444 </row>
445 <row>
446 <entry><command>svn help</command></entry>
447 <entry><command>hg help</command></entry>
448 <entry></entry>
449 </row>
450 <row>
451 <entry><command>svn import</command></entry>
452 <entry><command>hg addremove</command>; <command>hg
453 commit</command></entry>
454 <entry></entry>
455 </row>
456 <row>
457 <entry><command>svn info</command></entry>
458 <entry><command>hg parents</command></entry>
459 <entry>Affiche quelle révision est extraite</entry>
460 </row>
461 <row>
462 <entry><command>svn info</command></entry>
463 <entry><command>hg showconfig
464 paths.parent</command></entry>
465 <entry>Affiche de quelle URL est extrait ce dépôt</entry>
466 </row>
467 <row>
468 <entry><command>svn list</command></entry>
469 <entry><command>hg manifest</command></entry>
470 <entry></entry>
471 </row>
472 <row>
473 <entry><command>svn log</command></entry>
474 <entry><command>hg log</command></entry>
475 <entry></entry>
476 </row>
477 <row>
478 <entry><command>svn merge</command></entry>
479 <entry><command>hg merge</command></entry>
480 <entry></entry>
481 </row>
482 <row>
483 <entry><command>svn mkdir</command></entry>
484 <entry>n/a</entry>
485 <entry>Mercurial ne versionne pas les répertoires</entry>
486 </row>
487 <row>
488 <entry><command>svn move</command> (<command>svn
489 rename</command>)</entry>
490 <entry><command>hg rename</command></entry>
491 <entry></entry>
492 </row>
493 <row>
494 <entry><command>svn resolved</command></entry>
495 <entry><command>hg resolve -m</command></entry>
496 <entry></entry>
497 </row>
498 <row>
499 <entry><command>svn revert</command></entry>
500 <entry><command>hg revert</command></entry>
501 <entry></entry>
502 </row>
503 <row>
504 <entry><command>svn status</command></entry>
505 <entry><command>hg status</command></entry>
506 <entry></entry>
507 </row>
508 <row>
509 <entry><command>svn update</command></entry>
510 <entry><command>hg pull -u</command></entry>
511 <entry></entry>
512 </row>
513 </tbody>
514 </tgroup>
515 </table>
516 </sect2>
517 </sect1>
519 <sect1>
520 <title>Conseils utiles pour les débutants</title>
522 <para id="x_705">Avec la plupart des gestionnaire de révisions, afficher
523 un diff associé à une révision peut être assez douloureux. Par exemple,
524 avec Subversion, pour voir ce qui a été modifiée dans la révision 104654,
525 vous devez saisir <command>svn diff -r104653:104654</command>. Mercurial
526 élimine le besoin de saisir l'identifiant d'une révision deux fois dans
527 ce cas classique. Pour un simple diff, <command>hg
528 export<command></command>
529 104654</command> suffit. Pour l'entrée du journal suivi du diff,
530 <command>hg log -r104654</command>. </para>
532 <para id="x_706">Quand vous exécutez la commande <command>hg status</command>
533 sans aucun arguments, elle affiche l'état de l'ensemble de l'arboresence,
534 avec des chemins relatifs partant de la raçine du dépôt. Ceci rend
535 difficile de copier un nom de fichier depuis la sortie de la commande
536 <command>hg status</command> dans une autre ligne de commande. Si vous
537 fournissez un fichier ou un répertoire à la commande <command>hg
538 status</command>, elle va afficher les chemins relatif depuis votre
539 répertoire courant à la place. Ainsi, pour avoir un état sur l'ensemble
540 de l'arboresence à l'aide de <command>hg status</command>, avec des
541 chemins relatifs à votre répertoire courant, et non le raçine du dépôt,
542 ajoutez la sortie de <command>hg root</command> à la commande
543 <command>hg status</command>. Vous pouvez le faire aisément sur un
544 système Unix ainsi :</para>
546 <screen><prompt>$</prompt> <userinput>hg status `hg root`</userinput></screen>
547 </sect1>
548 </appendix>
550 <!--
551 local variables:
552 sgml-parent-document: ("00book.xml" "book" "appendix")
553 end:
554 -->