hgbook
diff fr/ch03-tour-merge.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 | 713f0f69029a |
line diff
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000 1.2 +++ b/fr/ch03-tour-merge.xml Sun Aug 16 04:58:01 2009 +0200 1.3 @@ -0,0 +1,384 @@ 1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : --> 1.5 + 1.6 +<chapter> 1.7 +<title>Un rapide tour de Mercurial: fusionner les travaux</title> 1.8 +<para>\label{chap:tour-merge}</para> 1.9 + 1.10 +<para>Nous avons maintenant étudié comment cloner un dépôt, effectuer 1.11 +des changements dedans, et récupérer ou transférer depuis un 1.12 +autre dépôt. La prochaine étape est donc de <emphasis>fusionner</emphasis> les 1.13 +modifications de différents dépôts.</para> 1.14 + 1.15 +<sect1> 1.16 +<title>Fusionner différents travaux</title> 1.17 +<para> %%% for 'Merging streams of work' ? 1.18 +La fusion\footnote{NdT: Je garde fusion mais le jargon professionnel 1.19 +emploiera généralement le terme \textit{merge}.} est un aspect 1.20 +fondamental lorsqu'on travaille avec un gestionnaire de source 1.21 +distribué.</para> 1.22 +<itemizedlist> 1.23 +<listitem><para>Alice et Bob ont chacun une copie personnelle du dépôt d'un 1.24 + projet sur lequel ils collaborent. Alice corrige un \textit{bug} 1.25 + dans son dépôt, et Bob ajoute une nouvelle fonctionnalité dans le 1.26 + sien. Ils veulent un dépôt partagé avec à la fois le correctif du 1.27 + \textit{bug} et la nouvelle fonctionnalité.</para> 1.28 +</listitem> 1.29 +<listitem><para>Je travaille régulièrement sur plusieurs tâches différentes sur 1.30 + un seul projet en même temps, chacun isolé dans son propre dépôt. 1.31 + Travailler ainsi signifie que je dois régulièrement fusionner une 1.32 + partie de mon code avec celui des autres.</para> 1.33 +</listitem></itemizedlist> 1.34 + 1.35 +<para>Parce que la fusion est une opération si commune à réaliser, 1.36 +Mercurial la rend facile. Étudions ensemble le déroulement des opérations. 1.37 +Nous commencerons encore par faire un clone d'un autre dépôt (vous voyez 1.38 +que l'on fait ça tout le temps ?) puis nous ferons quelques modifications 1.39 +dessus. 1.40 +<!-- &interaction.tour.merge.clone; --> 1.41 +Nous devrions avoir maintenant deux copies de <filename>hello.c</filename> avec 1.42 +des contenus différents. Les historiques de ces deux dépôts ont aussi 1.43 +divergés, comme illustré dans la figure <xref linkend="fig:tour-merge:sep-repos"/>.</para> 1.44 + 1.45 +<para><!-- &interaction.tour.merge.cat; --></para> 1.46 + 1.47 +<informalfigure> 1.48 + 1.49 +<para> <mediaobject><imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 1.50 + <caption><para>Historiques récent divergents des dépôts \dirname{my-hello</para></caption> 1.51 + et <filename class="directory">my-new-hello</filename>} 1.52 + \label{fig:tour-merge:sep-repos}</para> 1.53 +</informalfigure> 1.54 + 1.55 +<para>Nous savons déjà que récupérer les modifications depuis notre dépôt 1.56 +<filename class="directory">my-hello</filename> n'aura aucun effet sur l'espace de travail. 1.57 +</para> 1.58 + 1.59 +<para><!-- &interaction.tour.merge.pull; --> 1.60 +</para> 1.61 + 1.62 +<para>Néanmoins, la commande <command role="hg-cmd">hg pull</command> nous indique quelque chose au 1.63 +sujet des <quote>heads</quote>. 1.64 +</para> 1.65 + 1.66 +<sect2> 1.67 +<title>\textit{Head changesets}</title> 1.68 + 1.69 +<para>Une \textit{head}\footnote{NdT: Je garde \textit{head} que j'accorde 1.70 +au féminin comme la coutume orale l'a imposé.} est un \textit{changeset} 1.71 +sans descendants, ou enfants, comme on les désigne parfois. La révision 1.72 +\textit{tip} est une \textit{head}, car la dernière révision dans un dépôt 1.73 +n'a aucun enfant, mais il est important de noter qu'un dépôt peut contenir 1.74 +plus d'une \textit{head}. 1.75 +</para> 1.76 + 1.77 +<informalfigure> 1.78 + 1.79 +<para> <mediaobject><imageobject><imagedata fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 1.80 + \caption{Contenu d'un dépôt après avoir transféré le contenu du dépôt 1.81 + <filename class="directory">my-hello</filename> dans le dépôt <filename class="directory">my-new-hello</filename>} 1.82 + \label{fig:tour-merge:pull} 1.83 +</para> 1.84 +</informalfigure> 1.85 + 1.86 +<para>Dans la figure <xref linkend="fig:tour-merge:pull"/>, vous pouvez constater l'effet 1.87 +d'un \textit{pull} depuis le dépôt <filename class="directory">my-hello</filename> dans le dépôt 1.88 +<filename class="directory">my-new-hello</filename>. L'historique qui était déjà présent dans le dépôt 1.89 +<filename class="directory">my-new-hello</filename> reste intact, mais une nouvelle révision a été 1.90 +ajoutée. En vous reportant à la figure <xref linkend="fig:tour-merge:sep-repos"/>, 1.91 +vous pouvez voir que le \textit{<emphasis>changeset ID</emphasis>} reste le même dans 1.92 +le nouveau dépôt, mais que le <emphasis>numéro de révision</emphasis> reste le même. 1.93 +(Ceci est un parfait exemple de pourquoi il n'est fiable d'utiliser les 1.94 +numéros de révision lorsque l'on discute d'un \textit{changeset}.) Vous 1.95 +pouvez voir les \texit{heads} présentes dans le dépôt en utilisant la 1.96 +commande <command role="hg-cmd">hg heads</command>. 1.97 +<!-- &interaction.tour.merge.heads; --> 1.98 +</para> 1.99 + 1.100 +</sect2> 1.101 +<sect2> 1.102 +<title>Effectuer la fusion</title> 1.103 + 1.104 +<para>Que se passe-t-il quand vous essayez d'utiliser la commande <command role="hg-cmd">hg update</command> 1.105 +pour mettre à jour votre espace de travail au nouveau \textit{tip}. 1.106 +<!-- &interaction.tour.merge.update; --> 1.107 +Mercurial nous prévient que la commande <command role="hg-cmd">hg update</command> n'effectuera pas 1.108 +la fusion, il ne veut pas mettre à jour l'espace de travail quand il 1.109 +estime que nous pourrions avoir besoin d'une fusion, à moins de lui 1.110 +forcer la main. À la place, il faut utiliser la commande <command role="hg-cmd">hg merge</command> 1.111 +pour fusionner les deux \textit{heads}. 1.112 +<!-- &interaction.tour.merge.merge; --> 1.113 +</para> 1.114 + 1.115 +<informalfigure> 1.116 + 1.117 +<para> <mediaobject><imageobject><imagedata fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 1.118 + \caption{Espace de travail et dépôt lors d'une fusion, et dans le 1.119 + \textit{commit} qui suit.} 1.120 + \label{fig:tour-merge:merge} 1.121 +</para> 1.122 +</informalfigure> 1.123 + 1.124 +<para>Ceci met à jour l'espace de travail de manière à ce qu'il contienne 1.125 +les modifications des <emphasis>deux</emphasis> \textit{heads}, ce qui apparaît dans 1.126 +les sorties de la commande <command role="hg-cmd">hg parents</command> et le contenu de 1.127 +<filename>hello.c</filename>. 1.128 +<!-- &interaction.tour.merge.parents; --> 1.129 +</para> 1.130 + 1.131 +</sect2> 1.132 +<sect2> 1.133 +<title>Effectuer le \textit{commit} du résultat de la fusion</title> 1.134 + 1.135 +<para>Dès l'instant où vous avez effectué une fusion, <command role="hg-cmd">hg parents</command> vous 1.136 +affichera deux parents, avant que vous n'exécutiez la commande 1.137 +<command role="hg-cmd">hg commit</command> sur le résultat de la fusion. 1.138 +<!-- &interaction.tour.merge.commit; --> 1.139 +Nous avons maintenant un nouveau \textit{tip}, remarquer qu'il contient 1.140 +<emphasis>à la fois</emphasis> nos anciennes \textit{heads} et leurs parents. Ce sont 1.141 +les mêmes révisions que nous avions affichées avec la commande 1.142 +<command role="hg-cmd">hg parents</command>. 1.143 +</para> 1.144 + 1.145 +<para><!-- &interaction.tour.merge.tip; --> 1.146 +Dans la figure <xref linkend="fig:tour-merge:merge"/>, vous pouvez voir une représentation 1.147 +de ce qui se passe dans l'espace de travail pendant la fusion, et comment ceci 1.148 +affecte le dépôt lors du \textit{commit}. Pendant la fusion, l'espace de travail, 1.149 +qui a deux \texit{changesets} comme parents, voit ces derniers devenir le parent 1.150 +%%% TODO: le parent ou "les parents" : plus logique mais si il reste seulement 1.151 +%%% un changeset, alors c'est effectivement un parent (le changeset est hermaphrodite) 1.152 +d'un nouveau \textit{changeset}. 1.153 +</para> 1.154 + 1.155 +</sect2> 1.156 +</sect1> 1.157 +<sect1> 1.158 +<title>Fusionner les modifications en conflit</title> 1.159 + 1.160 +<para>La plupart des fusions sont assez simple à réaliser, mais parfois 1.161 +vous vous retrouverez à fusionner des fichiers où la modification touche 1.162 +la même portion de code, au sein d'un même fichier. À moins que ces 1.163 +modification ne soient identiques, ceci aboutira à un <emphasis>conflit</emphasis>, 1.164 +et vous devrez décider comment réconcilier les différentes modifications 1.165 +dans un tout cohérent. 1.166 +</para> 1.167 + 1.168 +<informalfigure> 1.169 + 1.170 +<para> <mediaobject><imageobject><imagedata fileref="tour-merge-conflict"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 1.171 + <caption><para>Modifications conflictuelles dans un document</para></caption> 1.172 + \label{fig:tour-merge:conflict} 1.173 +</para> 1.174 +</informalfigure> 1.175 + 1.176 +<para>La figure <xref linkend="fig:tour-merge:conflict"/> illustre un cas de modifications 1.177 +conflictuelles dans un document. Nous avons commencé avec une version simple 1.178 +de ce fichier, puis nous avons ajouté des modifications, pendant que 1.179 +quelqu'un d'autre modifiait le même texte. Notre tâche dans la résolution 1.180 +du conflit est de décider à quoi le fichier devrait ressembler. 1.181 +</para> 1.182 + 1.183 +<para>Mercurial n'a pas de mécanisme interne pour gérer les conflits. 1.184 +À la place, il exécute un programme externe appelé <command>hgmerge</command>. 1.185 +Il s'agit d'un script shell qui est embarqué par Mercurial, vous 1.186 +pouvez le modifier si vous le voulez. Ce qu'il fait par défaut est 1.187 +d'essayer de trouver un des différents outils de fusion qui seront 1.188 +probablement installés sur le système. Il commence par les outils 1.189 +totalement automatiques, et si ils échouent (parce que la résolution 1.190 +du conflit nécessite une intervention humaine) ou si ils sont absents, 1.191 +le script tente d'exécuter certains outils graphiques de fusion. 1.192 +</para> 1.193 + 1.194 +<para>Il est aussi possible de demander à Mercurial d'exécuter un autre 1.195 +programme ou un autre script au lieu de la commande <command>hgmerge</command>, 1.196 +en définissant la variable d'environnement <envar>HGMERGE</envar> avec le nom 1.197 +du programme de votre choix. 1.198 +</para> 1.199 + 1.200 +<sect2> 1.201 +<title>Utiliser un outil graphique de fusion</title> 1.202 + 1.203 +<para>Mon outil de fusion préféré est <command>kdiff3</command>, que j'utilise ici 1.204 +pour illustrer les fonctionnalités classiques des outils graphiques 1.205 +de fusion. Vous pouvez voir une capture d'écran de l'utilisation de 1.206 +<command>kdiff3</command> dans la figure <xref linkend="fig:tour-merge:kdiff3"/>. Cet outil 1.207 +effectue une <emphasis>fusion \textit{three-way</emphasis>}, car il y a trois différentes 1.208 +versions du fichier qui nous intéresse. Le fichier découpe la partie 1.209 +supérieure de la fenêtre en trois panneaux: 1.210 +</para> 1.211 + 1.212 +<itemizedlist> 1.213 +<listitem><para>A gauche on la version de <emphasis>base</emphasis> du fichier, soit la plus 1.214 + récente version des deux versions qu'on souhaite fusionner. 1.215 +</para> 1.216 +</listitem> 1.217 +<listitem><para>Au centre, il y a <quote>notre</quote> version du fichier, avec le contenu 1.218 + que nous avons modifié. 1.219 +</para> 1.220 +</listitem> 1.221 +<listitem><para>Sur la droite, on trouve <quote>leur</quote> version du fichier, celui qui 1.222 + contient le \textit{changeset} que nous souhaitons intégré. 1.223 +</para> 1.224 +</listitem></itemizedlist> 1.225 + 1.226 +<para>Dans le panneau en dessous, on trouve le <emphasis>résultat</emphasis> actuel de notre 1.227 +fusion. Notre tâche consiste donc à remplacement tous les textes en rouges, 1.228 +qui indiquent des conflits non résolus, avec une fusion manuelle et pertinente 1.229 +de <quote>notre</quote> version et de la <quote>leur</quote>. 1.230 +</para> 1.231 + 1.232 +<para>Tous les quatre panneaux sont <emphasis>accrochés ensemble</emphasis>, si nous déroulons 1.233 +les ascenseurs verticalement ou horizontalement dans chacun d'entre eux, les 1.234 +autres sont mis à jour avec la section correspondante dans leurs fichiers 1.235 +respectifs. 1.236 +</para> 1.237 + 1.238 +<informalfigure> 1.239 + 1.240 +<para> <mediaobject><imageobject><imagedata fileref="kdiff3"/></imageobject><textobject><phrase>XXX add text</phrase></textobject></mediaobject> 1.241 + <caption><para>Utilisation de \command{kdiff3</para></caption> pour fusionner différentes versions 1.242 + d'un fichier.} 1.243 + \label{fig:tour-merge:kdiff3} 1.244 +</para> 1.245 +</informalfigure> 1.246 + 1.247 +<para>Pour chaque portion de fichier posant problème, nous pouvons choisir 1.248 +de résoudre le conflit en utilisant une combinaison 1.249 +de texte depuis la version de base, la notre, ou la leur. Nous pouvons 1.250 +aussi éditer manuellement les fichiers à tout moment, si c'est 1.251 +nécessaire. 1.252 +</para> 1.253 + 1.254 +<para>Il y a <emphasis>beaucoup</emphasis> d'outils de fusion disponibles, bien trop pour 1.255 +en parler de tous ici. Leurs disponibilités varient selon les plate formes 1.256 +ainsi que leurs avantages et inconvénients. La plupart sont optimisé pour 1.257 +la fusion de fichier contenant un texte plat, certains sont spécialisé 1.258 +dans un format de fichier précis (généralement XML). 1.259 +</para> 1.260 + 1.261 +</sect2> 1.262 +<sect2> 1.263 +<title>Un exemple concret</title> 1.264 + 1.265 +<para>Dans cet exemple, nous allons reproduire la modification de l'historique 1.266 +du fichier de la figure <xref linkend="fig:tour-merge:conflict"/> ci dessus. Commençons 1.267 +par créer un dépôt avec une version de base de notre document. 1.268 +</para> 1.269 + 1.270 +<para><!-- &interaction.tour-merge-conflict.wife; --> 1.271 +Créons un clone de ce dépôt et faisons une modification dans le fichier. 1.272 +<!-- &interaction.tour-merge-conflict.cousin; --> 1.273 +Et un autre clone, pour simuler que quelqu'un d'autre effectue une 1.274 +modification sur le fichier. (Ceci pour suggérer qu'il n'est pas rare 1.275 +de devoir effectuer des \textit{merge} avec vos propres travaux quand 1.276 +vous isolez les tâches dans des dépôts distincts. En effet, vous 1.277 +aurez alors à trouver et résoudre certains conflits). 1.278 +<!-- &interaction.tour-merge-conflict.son; --> 1.279 +Maintenant que ces deux versions différentes du même fichier sont 1.280 +créées, nous allons configurer l'environnement de manière appropriée pour 1.281 +exécuter notre \textit{merge}. 1.282 +<!-- &interaction.tour-merge-conflict.pull; --> 1.283 +</para> 1.284 + 1.285 +<para>Dans cette exemple, je n'utiliserais pas la commande Mercurial 1.286 +habituelle <command>hgmerge</command> pour effectuer le \textit{merge}, 1.287 +car il me faudrait abandonner ce joli petit exemple automatisé 1.288 +pour utiliser un outil graphique. À la place, je vais définir 1.289 +la variable d'environnement <envar>HGMERGE</envar> pour indiquer à 1.290 +Mercurial d'utiliser la commande non-interactive <command>merge</command>. 1.291 +Cette dernière est embarquée par de nombreux systèmes <quote>à la Unix</quote>. 1.292 +Si vous exécutez cet exemple depuis votre ordinateur, ne vous 1.293 +occupez pas de définir <envar>HGMERGE</envar>. 1.294 +<!-- &interaction.tour-merge-conflict.merge; --> 1.295 +Parce que <command>merge</command> ne peut pas résoudre les modifications 1.296 +conflictuelles, il laisse des <emphasis>marqueurs de différences</emphasis> 1.297 +\footnote{NdT: Oui, je traduis \textit{merge markers} par un sens 1.298 +inverse en Français, mais je pense vraiment que c'est plus clair 1.299 +comme ça...} à l'intérieur du fichier qui a des conflits, indiquant 1.300 +clairement quelles lignes sont en conflits, et si elles viennent de 1.301 +notre fichier ou du fichier externe. 1.302 +</para> 1.303 + 1.304 +<para>Mercurial peut distinguer, à la manière dont la commande <command>merge</command> 1.305 +se termine, qu'elle n'a pas été capable d'effectuer le \textit{merge}, 1.306 +alors il nous indique que nous devons effectuer de nouveau cette 1.307 +opération. Ceci peut être très utile si, par exemple, nous exécutons un 1.308 +outil graphique de fusion et que nous le quittons sans nous rendre compte 1.309 +qu'il reste des conflits ou simplement par erreur. 1.310 +</para> 1.311 + 1.312 +<para>Si le \textit{merge} automatique ou manuel échoue, il n'y a rien pour 1.313 +nous empêcher de <quote>corriger le tir</quote> en modifiant nous même les fichiers, 1.314 +et enfin effectuer le \textit{commit} du fichier: 1.315 +<!-- &interaction.tour-merge-conflict.commit; --> 1.316 +</para> 1.317 + 1.318 +</sect2> 1.319 +</sect1> 1.320 +<sect1> 1.321 +<title>Simplification de la séquence pull-merge-commit</title> 1.322 +<para>\label{sec:tour-merge:fetch} 1.323 +</para> 1.324 + 1.325 +<para>La procédure pour effectuer la fusion indiquée ci-dessus est simple, 1.326 +mais requiert le lancement de trois commandes à la suite. 1.327 +</para> 1.328 +<programlisting> 1.329 +<para> hg pull 1.330 + hg merge 1.331 + hg commit -m 'Merged remote changes' 1.332 +</para> 1.333 +</programlisting> 1.334 + 1.335 +<para>Lors du \textit{commit} final, vous devez également saisir un message, 1.336 +qui aura vraisemblablement assez peu d'intérêt. 1.337 +</para> 1.338 + 1.339 +<para>Il serait assez sympathique de pouvoir réduire le nombre d'opérations 1.340 +nécessaire, si possible. De fait Mercurial est fourni avec une 1.341 +extension appelé <literal role="hg-ext">fetch</literal> qui fait justement cela. 1.342 +</para> 1.343 + 1.344 +<para>Mercurial fourni un mécanisme d'extension flexible qui permet à chacun 1.345 +d'étendre ces fonctionnalités, tout en conservant le cœur de Mercurial 1.346 +léger et facile à utiliser. Certains extensions ajoutent de nouvelles 1.347 +commandes que vous pouvez utiliser en ligne de commande, alors que 1.348 +d'autres travaillent <quote>en coulisse,</quote> par exemple en ajoutant des 1.349 +possibilités au serveur. 1.350 +</para> 1.351 + 1.352 +<para>L'extension <literal role="hg-ext">fetch</literal> ajoute une nouvelle commande nommée, sans 1.353 +surprise, <command role="hg-cmd">hg fetch</command>. Cette extension résulte en une combinaison 1.354 +de <command role="hg-cmd">hg pull</command>, <command role="hg-cmd">hg update</command> and <command role="hg-cmd">hg merge</command>. Elle commence par 1.355 +récupérer les modifications d'un autre dépôt dans le dépôt courant. 1.356 +Si elle trouve que les modifications ajoutent une nouvelle \textit{head}, 1.357 +elle effectue un \textit{merge}, et ensuite \texit{commit} le résultat 1.358 +du \textit{merge} avec un message généré automatiquement. Si aucune 1.359 +\textit{head} n'ont été ajouté, elle met à jour le répertoire de travail 1.360 +au niveau du nouveau \textit{changeset} \textit{tip}. 1.361 +</para> 1.362 + 1.363 + 1.364 +<para>Activer l'extension <literal role="hg-ext">fetch</literal> est facile. Modifiez votre <filename role="special">.hgrc</filename>, 1.365 +et soit allez à la section <literal role="rc-extensions">extensions</literal> soit créer une 1.366 +section <literal role="rc-extensions">extensions</literal>. Ensuite ajoutez une ligne qui consiste 1.367 +simplement en <quote>\Verb+fetch =</quote>. 1.368 +</para> 1.369 + 1.370 +<programlisting> 1.371 +<para> [extensions] 1.372 + fetch = 1.373 +</para> 1.374 +</programlisting> 1.375 +<para>(Normalement, sur la partie droite de <quote><literal>=</literal></quote> devrait apparaître 1.376 +le chemin de l'extension, mais étant donné que l'extension <literal role="hg-ext">fetch</literal> 1.377 +fait partie de la distribution standard, Mercurial sait où la trouver.) 1.378 +</para> 1.379 + 1.380 +</sect1> 1.381 +</chapter> 1.382 + 1.383 +<!-- 1.384 +local variables: 1.385 +sgml-parent-document: ("00book.xml" "book" "chapter") 1.386 +end: 1.387 +--> 1.388 \ No newline at end of file