hgbook
view fr/tour-merge.tex @ 956:61f7bf2e562d
review of french tour-basic
| author | Wilk |
|---|---|
| date | Sun Feb 22 16:15:40 2009 +0100 (2009-02-22) |
| parents | 547d3aa25ef0 |
| children | 2cd5d582c956 |
line source
1 \chapter{Un rapide tour de Mercurial: fusionner les travaux}
2 \label{chap:tour-merge}
4 Nous avons maintenons étudié comment clôner un dépôt, effectuer
5 des changements dedans, et récupérer ou transférer depuis un
6 autre dépôt. La prochaine étape est donc de \emph{fusionner} les
7 modifications de différents dépôts.
9 \section{Fusionner différents travaux} %%%TODO: better translation
10 %%% for 'Merging streams of work' ?
11 La fusion\footnote{NdT: Je garde fusion mais le jargon professionnel
12 employera généralement le terme \textit{merge}.} est un aspect
13 fondamental lorsqu'on travail avec un gestionnaire de source
14 distribé.
15 \begin{itemize}
16 \item Alice et Bob ont chacun une copie personnelle du dépôt d'un
17 projet sur lequel ils collaborent. Alice corrige un \textit{bug}
18 dans son dépôt, et Bob ajoute une nouvelle fonctionnalité dans le
19 sien. Ils veulent un dépôt partagé avec à la fois le correctif du
20 \textit{bug} et la nouvelle fonctionnalité.
21 \item Je travaille régulièrement sur plusieurs tâches différentes sur
22 un seul projet en même temps, chacun isolée dans son propre dépôt.
23 Travailler ainsi signifie que je dois régulièrement fusionner une
24 partie de mon code avec celui des autres.
25 \end{itemize}
27 Parce que la fusion est une opération si commune que je dois réaliser,
28 Mercurial la rend facile. Etudions ensemble le déroulement des opérations.
29 Nous commencerons par faire un clone d'encore un autre dépôt (vous voyez
30 comment on fait ça tout le temps ?) puis nous ferons quelques modifications
31 dessus.
32 \interaction{tour.merge.clone}
33 Nous devrions avoir maintenant deux copies de \filename{hello.c} avec
34 des contenus différents. Les historiques de ces deux dépôts ont aussi
35 divergés, comme illustré dans la figure~\ref{fig:tour-merge:sep-repos}.
37 \interaction{tour.merge.cat}
39 \begin{figure}[ht]
40 \centering
41 \grafix{tour-merge-sep-repos}
42 \caption{Historiques récent divergents des dépôts \dirname{my-hello}
43 et \dirname{my-new-hello}}
44 \label{fig:tour-merge:sep-repos}
45 \end{figure}
47 Nous savons déjà que récupérer les modifications depuis notre dépôt
48 \dirname{my-hello} n'aura aucun effet sur l'espace de travail.
50 \interaction{tour.merge.pull}
52 Néanmoins, la commande \hgcmd{pull} nous indique quelquechose au
53 sujet des ``heads''.
55 \subsection{\textit{Head changesets}} %%%TODO: Hard (too?) to translate
57 Une \textit{head}\footnote{NdT: Je garde \textit{head} que j'accorde
58 au féminin comme la coutume oral l'a imposée.} est un \textit{changeset}
59 sans descendants, ou enfants, comme on les désigne parfois. La révision
60 \textit{tip} est une \textit{head}, car la dernière révision dans un dépôt
61 n'a aucun enfant, mais il est important de noter qu'un dépôt peut contenir
62 plus d'une \textit{head}.
64 \begin{figure}[ht]
65 \centering
66 \grafix{tour-merge-pull}
67 \caption{Contenu d'un dépôt après avoir transférer le contenu du dépôt
68 \dirname{my-hello} dans le dépôt \dirname{my-new-hello}}
69 \label{fig:tour-merge:pull}
70 \end{figure}
72 Dans la figure~\ref{fig:tour-merge:pull}, vous pouvez constater l'effet
73 d'un \textit{pull} depuis le dépôt \dirname{my-hello} dans le dépôt
74 \dirname{my-new-hello}. L'historique qui était déjà présent dans le dépôt
75 \dirname{my-new-hello} reste intact, mais une nouvelle révision a été
76 ajoutée. En vous reportant à la figure~\ref{fig:tour-merge:sep-repos},
77 vous pouvez voir que le \textit{\emph{changeset ID}} reste le même dans
78 le nouveau dépôt, mais que le \emph{numéro de révision} reste le même.
79 (Ceci est un parfait exemple de pourquoi il n'est fiable d'utiliser les
80 numéro de révision lorsque l'on discute d'un \textit{changeset}.) Vous
81 pouvez voir les \texit{heads} présente dans le dépôt en utilisant la
82 commande \hgcmd{heads}.
83 \interaction{tour.merge.heads}
85 \subsection{Effectuer la fusion}
87 Que se passe-t-il quand vous essayez d'utiliser la commande \hgcmd{update}
88 pour mettre à jour votre espace de travail au nouveau \textit{tip}.
89 \interaction{tour.merge.update}
90 Mercurial nous prévient que la commande \hgcmd{update} n'effectuera pas
91 la fusion, il ne veut pas mettre à jour l'espace de travail quand il
92 estime que nous pourrions avoir besoin d'une fusion, à moins de lui
93 forcer la main. À la place, il faut utiliser la commande \hgcmd{merge}
94 pour fusionner les deux \textit{heads}.
95 \interaction{tour.merge.merge}
97 \begin{figure}[ht]
98 \centering
99 \grafix{tour-merge-merge}
100 \caption{Espace de travail et dépôt lors d'une fusion, et dans le
101 \textit{commit} qui suit.}
102 \label{fig:tour-merge:merge}
103 \end{figure}
105 Ceci met à jour de l'espace de travail de manière à ce qu'il contienne
106 les modifications des \emph{deux} \textit{heads}, ce qui apparait dans
107 les sorties de la commande \hgcmd{parents} et le contenu de
108 \filename{hello.c}.
109 \interaction{tour.merge.parents}
111 \subsection{Committing the results of the merge}
113 Whenever we've done a merge, \hgcmd{parents} will display two parents
114 until we \hgcmd{commit} the results of the merge.
115 \interaction{tour.merge.commit}
116 Nous avons maintenant un nouveau \textit{tip}, remarquer qu'il contient
117 \emph{à la fois} nos anciennes \textit{heads} et leurs parents. Ce sont
118 les mêmes révisions que nous avions affichés avec la commande
119 \hgcmd{parents}.
121 \interaction{tour.merge.tip}
122 Dans la figure~\ref{fig:tour-merge:merge}, vous pouvez voir une représentation
123 de ce qui se passe dans l'espace de travail pendant la fusion, et comment ceci
124 affecte le dépôt lors du \textit{commit}. Pendant la fusion, l'espace de travail,
125 qui a deux \texit{changesets} comme parents, voit ces derniers devenir le parent
126 d'un nouveau \textit{changeset}.
128 \section{Fusionner les modifications en conflit}
130 La plupart des fusions sont assez simple à réaliser, mais parfois
131 vous vous trouverez à fusioner des fichiers où la modification touche
132 la même portion de code, au sein d'un même fichier. À moins que ces
133 modification ne soient identiques, ceci aboutira à un \emph{conflit},
134 et vous devrez décider comment réconcillier les différentes modifications
135 dans un tout cohérent.
137 \begin{figure}[ht]
138 \centering
139 \grafix{tour-merge-conflict}
140 \caption{Modifications conflictuelles dans un document}
141 \label{fig:tour-merge:conflict}
142 \end{figure}
144 La figure~\ref{fig:tour-merge:conflict} illustre un cas de modifications
145 conflictuelles dans un document. Nous avons commencé avec une version simple
146 de ce fichier, puis nous avons ajoutés des modifications, pendant que
147 quelqu'un d'autre modifie le même texte. Notre tâche dans la résolution
148 du conflit est de décider à quoi le fichier devrait ressembler.
150 Mercurial n'a pas de mécanisme interne pour gérer les conflits.
151 À la place, il exéctue un programme externe appelé \command{hgmerge}.
152 Il s'agit d'un script shell qui est embarqué par Mercurial, vous
153 pouvez le modifier si vous le voulez. Ce qu'il fait par défaut est
154 d'essayer de trouver un des différents outils de fusion qui seront
155 probablement installé sur le système. Il commence par les outils
156 totalement automatique, et si ils échouent (parce que la résolution
157 du conflit nécessite une intervention humaine) ou si ils sont absents,
158 le script tente d'exécuter certains outils graphiques de fusion.
160 Il est aussi possible de demander à Mercurial d'exécuter un autre
161 programme ou un autre script au lieu de la commande \command{hgmerge},
162 en définissant la variable d'environement \envar{HGMERGE} avec le nom
163 du programme de votre choix.
165 \subsection{Utiliser un outil graphique de fusion}
167 Mon outil de fusion préféré est \command{kdiff3}, que j'utilise ici
168 pour illustré les fonctionnalités classiques des outils graphiques
169 de fusion. Vous pouvez voir une capture d'écran de l'utilisation de
170 \command{kdiff3} dans la figure~\ref{fig:tour-merge:kdiff3}. Cet outil
171 effectue une \emph{fusion \textit{three-way}}, car il y a trois différentes
172 versions du fichier qui nous intéresse. Le fichier découpe la partie
173 supérieure de la fenêtre en trois panneaux:
175 \begin{itemize}
176 \item A gauche on la version de \emph{base} du fichier, soit ~la plus
177 récente version des deux versions qu'on souhaite fusionner.
178 \item Au centre, il y a ``notre'' version du fichier, avec le contenu
179 que nous avons modifié.
180 \item Sur la droite, on trouve ``leur'' version du fichier, celui qui qui
181 contient le \textit{changeset} que nous souhaitons intégré.
182 \end{itemize}
184 Dans le panneau en dessous, on trouve le \emph{résultat} actuel de notre
185 fusion. Notre tâche consiste donc à remplacement tout les textes en rouges,
186 qui indiquent des conflits non résolus, avec un fusion manuel et pertinente
187 de ``notre'' version et de la ``leur''.
189 Tout les quatres panneaux sont \emph{accrochés ensemble}, si nous déroulons
190 les ascenseurs verticalement ou horizontalement dans chacun d'entre eux, les
191 autres sont mise à jours avec la section correspondantes dans leurs fichiers.
193 \begin{figure}[ht]
194 \centering
195 \grafix{kdiff3}
196 \caption{Utilisation de \command{kdiff3} pour fusionner différents versions
197 d'un fichier.}
198 \label{fig:tour-merge:kdiff3}
199 \end{figure}
201 Pour chaque portion de fichier posant problème, nous pouvons choisir
202 de résoudre le le conlfit en utilisant en utilisant une combinaison
203 de texte depuis la version de base, la notre, ou la leur. Nous pouvons
204 aussi éditer manuellement les fichiers à tous moments, si c'est
205 nécessaire.
207 Il y a \emph{beaucoup} d'outils de fusion disponibles, bien trop pour
208 en parler de tous ici. Leurs disponibilités varient selon les plateformes
209 ainsi que leurs avantages et incovénients. La plupart sont optimisé pour
210 la fusion de fichier contenant un texte plat, certains sont spécialisé
211 dans un format de fichier précis (générallement XML).
213 \subsection{A worked example}
215 In this example, we will reproduce the file modification history of
216 figure~\ref{fig:tour-merge:conflict} above. Let's begin by creating a
217 repository with a base version of our document.
218 \interaction{tour-merge-conflict.wife}
219 We'll clone the repository and make a change to the file.
220 \interaction{tour-merge-conflict.cousin}
221 And another clone, to simulate someone else making a change to the
222 file. (This hints at the idea that it's not all that unusual to merge
223 with yourself when you isolate tasks in separate repositories, and
224 indeed to find and resolve conflicts while doing so.)
225 \interaction{tour-merge-conflict.son}
226 Having created two different versions of the file, we'll set up an
227 environment suitable for running our merge.
228 \interaction{tour-merge-conflict.pull}
230 In this example, I won't use Mercurial's normal \command{hgmerge}
231 program to do the merge, because it would drop my nice automated
232 example-running tool into a graphical user interface. Instead, I'll
233 set \envar{HGMERGE} to tell Mercurial to use the non-interactive
234 \command{merge} command. This is bundled with many Unix-like systems.
235 If you're following this example on your computer, don't bother
236 setting \envar{HGMERGE}.
237 \interaction{tour-merge-conflict.merge}
238 Because \command{merge} can't resolve the conflicting changes, it
239 leaves \emph{merge markers} inside the file that has conflicts,
240 indicating which lines have conflicts, and whether they came from our
241 version of the file or theirs.
243 Mercurial can tell from the way \command{merge} exits that it wasn't
244 able to merge successfully, so it tells us what commands we'll need to
245 run if we want to redo the merging operation. This could be useful
246 if, for example, we were running a graphical merge tool and quit
247 because we were confused or realised we had made a mistake.
249 If automatic or manual merges fail, there's nothing to prevent us from
250 ``fixing up'' the affected files ourselves, and committing the results
251 of our merge:
252 \interaction{tour-merge-conflict.commit}
254 \section{Simplifying the pull-merge-commit sequence}
255 \label{sec:tour-merge:fetch}
257 The process of merging changes as outlined above is straightforward,
258 but requires running three commands in sequence.
259 \begin{codesample2}
260 hg pull
261 hg merge
262 hg commit -m 'Merged remote changes'
263 \end{codesample2}
264 In the case of the final commit, you also need to enter a commit
265 message, which is almost always going to be a piece of uninteresting
266 ``boilerplate'' text.
268 It would be nice to reduce the number of steps needed, if this were
269 possible. Indeed, Mercurial is distributed with an extension called
270 \hgext{fetch} that does just this.
272 Mercurial provides a flexible extension mechanism that lets people
273 extend its functionality, while keeping the core of Mercurial small
274 and easy to deal with. Some extensions add new commands that you can
275 use from the command line, while others work ``behind the scenes,''
276 for example adding capabilities to the server.
278 The \hgext{fetch} extension adds a new command called, not
279 surprisingly, \hgcmd{fetch}. This extension acts as a combination of
280 \hgcmd{pull}, \hgcmd{update} and \hgcmd{merge}. It begins by pulling
281 changes from another repository into the current repository. If it
282 finds that the changes added a new head to the repository, it begins a
283 merge, then commits the result of the merge with an
284 automatically-generated commit message. If no new heads were added,
285 it updates the working directory to the new tip changeset.
287 Enabling the \hgext{fetch} extension is easy. Edit your
288 \sfilename{.hgrc}, and either go to the \rcsection{extensions} section
289 or create an \rcsection{extensions} section. Then add a line that
290 simply reads ``\Verb+fetch +''.
291 \begin{codesample2}
292 [extensions]
293 fetch =
294 \end{codesample2}
295 (Normally, on the right-hand side of the ``\texttt{=}'' would appear
296 the location of the extension, but since the \hgext{fetch} extension
297 is in the standard distribution, Mercurial knows where to search for
298 it.)
300 %%% Local Variables:
301 %%% mode: latex
302 %%% TeX-master: "00book"
303 %%% End: