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