hgbook
view en/ch02-tour-merge.xml @ 655:65e9a18d2c7e
Shrink large images to fit page
| author | Dongsheng Song <dongsheng.song@gmail.com> |
|---|---|
| date | Mon Mar 30 17:36:57 2009 +0800 (2009-03-30) |
| parents | 1c13ed2130a7 |
| children | e9ef075327c1 |
line source
1 <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
3 <chapter id="chap:tour-merge">
4 <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
5 <title>A tour of Mercurial: merging work</title>
7 <para id="x_338">We've now covered cloning a repository, making changes in a
8 repository, and pulling or pushing changes from one repository
9 into another. Our next step is <emphasis>merging</emphasis>
10 changes from separate repositories.</para>
12 <sect1>
13 <title>Merging streams of work</title>
15 <para id="x_339">Merging is a fundamental part of working with a distributed
16 revision control tool.</para>
17 <itemizedlist>
18 <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
19 repository for a project they're collaborating on. Alice
20 fixes a bug in her repository; Bob adds a new feature in
21 his. They want the shared repository to contain both the
22 bug fix and the new feature.</para>
23 </listitem>
24 <listitem><para id="x_33b">I frequently work on several different tasks for
25 a single project at once, each safely isolated in its own
26 repository. Working this way means that I often need to
27 merge one piece of my own work with another.</para>
28 </listitem></itemizedlist>
30 <para id="x_33c">Because merging is such a common thing to need to do,
31 Mercurial makes it easy. Let's walk through the process. We'll
32 begin by cloning yet another repository (see how often they
33 spring up?) and making a change in it.</para>
35 &interaction.tour.merge.clone;
37 <para id="x_33d">We should now have two copies of
38 <filename>hello.c</filename> with different contents. The
39 histories of the two repositories have also diverged, as
40 illustrated in <xref
41 linkend="fig:tour-merge:sep-repos"/>.</para>
43 &interaction.tour.merge.cat;
45 <figure id="fig:tour-merge:sep-repos">
46 <title>Divergent recent histories of the <filename
47 class="directory">my-hello</filename> and <filename
48 class="directory">my-new-hello</filename>
49 repositories</title>
50 <mediaobject>
51 <imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
52 <textobject><phrase>XXX add text</phrase></textobject>
53 </mediaobject>
54 </figure>
56 <para id="x_33f">We already know that pulling changes from our <filename
57 class="directory">my-hello</filename> repository will have no
58 effect on the working directory.</para>
60 &interaction.tour.merge.pull;
62 <para id="x_340">However, the <command role="hg-cmd">hg pull</command>
63 command says something about <quote>heads</quote>.</para>
65 <sect2>
66 <title>Head changesets</title>
68 <para id="x_341">A head is a change that has no descendants, or children,
69 as they're also known. The tip revision is thus a head,
70 because the newest revision in a repository doesn't have any
71 children, but a repository can contain more than one
72 head.</para>
74 <figure id="fig:tour-merge:pull">
75 <title>Repository contents after pulling from <filename
76 class="directory">my-hello</filename> into <filename
77 class="directory">my-new-hello</filename></title>
78 <mediaobject>
79 <imageobject>
80 <imagedata fileref="figs/tour-merge-pull.png"/>
81 </imageobject>
82 <textobject><phrase>XXX add text</phrase></textobject>
83 </mediaobject>
84 </figure>
86 <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
87 see the effect of the pull from <filename
88 class="directory">my-hello</filename> into <filename
89 class="directory">my-new-hello</filename>. The history that
90 was already present in <filename
91 class="directory">my-new-hello</filename> is untouched, but
92 a new revision has been added. By referring to <xref
93 linkend="fig:tour-merge:sep-repos"/>, we can see that the
94 <emphasis>changeset ID</emphasis> remains the same in the new
95 repository, but the <emphasis>revision number</emphasis> has
96 changed. (This, incidentally, is a fine example of why it's
97 not safe to use revision numbers when discussing changesets.)
98 We can view the heads in a repository using the <command
99 role="hg-cmd">hg heads</command> command.</para>
101 &interaction.tour.merge.heads;
103 </sect2>
104 <sect2>
105 <title>Performing the merge</title>
107 <para id="x_344">What happens if we try to use the normal <command
108 role="hg-cmd">hg update</command> command to update to the
109 new tip?</para>
111 &interaction.tour.merge.update;
113 <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
114 update</command> command won't do a merge; it won't update
115 the working directory when it thinks we might be wanting to do
116 a merge, unless we force it to do so. Instead, we use the
117 <command role="hg-cmd">hg merge</command> command to merge the
118 two heads.</para>
120 &interaction.tour.merge.merge;
122 <figure id="fig:tour-merge:merge">
123 <title>Working directory and repository during merge, and
124 following commit</title>
125 <mediaobject>
126 <imageobject>
127 <imagedata fileref="figs/tour-merge-merge.png"/>
128 </imageobject>
129 <textobject><phrase>XXX add text</phrase></textobject>
130 </mediaobject>
131 </figure>
133 <para id="x_347">This updates the working directory so that it contains
134 changes from <emphasis>both</emphasis> heads, which is
135 reflected in both the output of <command role="hg-cmd">hg
136 parents</command> and the contents of
137 <filename>hello.c</filename>.</para>
139 &interaction.tour.merge.parents;
141 </sect2>
142 <sect2>
143 <title>Committing the results of the merge</title>
145 <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
146 parents</command> will display two parents until we <command
147 role="hg-cmd">hg commit</command> the results of the
148 merge.</para>
150 &interaction.tour.merge.commit;
152 <para id="x_349">We now have a new tip revision; notice that it has
153 <emphasis>both</emphasis> of our former heads as its parents.
154 These are the same revisions that were previously displayed by
155 <command role="hg-cmd">hg parents</command>.</para>
157 &interaction.tour.merge.tip;
159 <para id="x_34a">In <xref
160 linkend="fig:tour-merge:merge"/>, you can see a
161 representation of what happens to the working directory during
162 the merge, and how this affects the repository when the commit
163 happens. During the merge, the working directory has two
164 parent changesets, and these become the parents of the new
165 changeset.</para>
167 </sect2>
168 </sect1>
169 <sect1>
170 <title>Merging conflicting changes</title>
172 <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
173 yourself merging changes where each modifies the same portions
174 of the same files. Unless both modifications are identical,
175 this results in a <emphasis>conflict</emphasis>, where you have
176 to decide how to reconcile the different changes into something
177 coherent.</para>
179 <figure id="fig:tour-merge:conflict">
180 <title>Conflicting changes to a document</title>
181 <mediaobject>
182 <imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
183 <textobject><phrase>XXX add text</phrase></textobject>
184 </mediaobject>
185 </figure>
187 <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
188 an instance of two conflicting changes to a document. We
189 started with a single version of the file; then we made some
190 changes; while someone else made different changes to the same
191 text. Our task in resolving the conflicting changes is to
192 decide what the file should look like.</para>
194 <para id="x_34e">Mercurial doesn't have a built-in facility for handling
195 conflicts. Instead, it runs an external program called
196 <command>hgmerge</command>. This is a shell script that is
197 bundled with Mercurial; you can change it to behave however you
198 please. What it does by default is try to find one of several
199 different merging tools that are likely to be installed on your
200 system. It first tries a few fully automatic merging tools; if
201 these don't succeed (because the resolution process requires
202 human guidance) or aren't present, the script tries a few
203 different graphical merging tools.</para>
205 <para id="x_34f">It's also possible to get Mercurial to run another program
206 or script instead of <command>hgmerge</command>, by setting the
207 <envar>HGMERGE</envar> environment variable to the name of your
208 preferred program.</para>
210 <sect2>
211 <title>Using a graphical merge tool</title>
213 <para id="x_350">My preferred graphical merge tool is
214 <command>kdiff3</command>, which I'll use to describe the
215 features that are common to graphical file merging tools. You
216 can see a screenshot of <command>kdiff3</command> in action in
217 <xref linkend="fig:tour-merge:kdiff3"/>. The kind of
218 merge it is performing is called a <emphasis>three-way
219 merge</emphasis>, because there are three different versions
220 of the file of interest to us. The tool thus splits the upper
221 portion of the window into three panes:</para>
222 <itemizedlist>
223 <listitem><para id="x_351">At the left is the <emphasis>base</emphasis>
224 version of the file, i.e. the most recent version from
225 which the two versions we're trying to merge are
226 descended.</para>
227 </listitem>
228 <listitem><para id="x_352">In the middle is <quote>our</quote> version of
229 the file, with the contents that we modified.</para>
230 </listitem>
231 <listitem><para id="x_353">On the right is <quote>their</quote> version
232 of the file, the one that from the changeset that we're
233 trying to merge with.</para>
234 </listitem></itemizedlist>
235 <para id="x_354">In the pane below these is the current
236 <emphasis>result</emphasis> of the merge. Our task is to
237 replace all of the red text, which indicates unresolved
238 conflicts, with some sensible merger of the
239 <quote>ours</quote> and <quote>theirs</quote> versions of the
240 file.</para>
242 <para id="x_355">All four of these panes are <emphasis>locked
243 together</emphasis>; if we scroll vertically or horizontally
244 in any of them, the others are updated to display the
245 corresponding sections of their respective files.</para>
247 <figure id="fig:tour-merge:kdiff3">
248 <title>Using <command>kdiff3</command> to merge versions of a
249 file</title>
250 <mediaobject>
251 <imageobject>
252 <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
253 <textobject>
254 <phrase>XXX add text</phrase>
255 </textobject>
256 </mediaobject>
257 </figure>
259 <para id="x_357">For each conflicting portion of the file, we can choose to
260 resolve the conflict using some combination of text from the
261 base version, ours, or theirs. We can also manually edit the
262 merged file at any time, in case we need to make further
263 modifications.</para>
265 <para id="x_358">There are <emphasis>many</emphasis> file merging tools
266 available, too many to cover here. They vary in which
267 platforms they are available for, and in their particular
268 strengths and weaknesses. Most are tuned for merging files
269 containing plain text, while a few are aimed at specialised
270 file formats (generally XML).</para>
272 </sect2>
273 <sect2>
274 <title>A worked example</title>
276 <para id="x_359">In this example, we will reproduce the file modification
277 history of <xref linkend="fig:tour-merge:conflict"/>
278 above. Let's begin by creating a repository with a base
279 version of our document.</para>
281 &interaction.tour-merge-conflict.wife;
283 <para id="x_35a">We'll clone the repository and make a change to the
284 file.</para>
286 &interaction.tour-merge-conflict.cousin;
288 <para id="x_35b">And another clone, to simulate someone else making a
289 change to the file. (This hints at the idea that it's not all
290 that unusual to merge with yourself when you isolate tasks in
291 separate repositories, and indeed to find and resolve
292 conflicts while doing so.)</para>
294 &interaction.tour-merge-conflict.son;
296 <para id="x_35c">Having created two
297 different versions of the file, we'll set up an environment
298 suitable for running our merge.</para>
300 &interaction.tour-merge-conflict.pull;
302 <para id="x_35d">In this example, I won't use Mercurial's normal
303 <command>hgmerge</command> program to do the merge, because it
304 would drop my nice automated example-running tool into a
305 graphical user interface. Instead, I'll set
306 <envar>HGMERGE</envar> to tell Mercurial to use the
307 non-interactive <command>merge</command> command. This is
308 bundled with many Unix-like systems. If you're following this
309 example on your computer, don't bother setting
310 <envar>HGMERGE</envar>.</para>
312 <para id="x_35e"><emphasis role="bold">XXX FIX THIS
313 EXAMPLE.</emphasis></para>
315 &interaction.tour-merge-conflict.merge;
317 <para id="x_35f">Because <command>merge</command> can't resolve the
318 conflicting changes, it leaves <emphasis>merge
319 markers</emphasis> inside the file that has conflicts,
320 indicating which lines have conflicts, and whether they came
321 from our version of the file or theirs.</para>
323 <para id="x_360">Mercurial can tell from the way <command>merge</command>
324 exits that it wasn't able to merge successfully, so it tells
325 us what commands we'll need to run if we want to redo the
326 merging operation. This could be useful if, for example, we
327 were running a graphical merge tool and quit because we were
328 confused or realised we had made a mistake.</para>
330 <para id="x_361">If automatic or manual merges fail, there's nothing to
331 prevent us from <quote>fixing up</quote> the affected files
332 ourselves, and committing the results of our merge:</para>
334 &interaction.tour-merge-conflict.commit;
336 </sect2>
337 </sect1>
338 <sect1 id="sec:tour-merge:fetch">
339 <title>Simplifying the pull-merge-commit sequence</title>
341 <para id="x_362">The process of merging changes as outlined above is
342 straightforward, but requires running three commands in
343 sequence.</para>
344 <programlisting>hg pull
345 hg merge
346 hg commit -m 'Merged remote changes'</programlisting>
347 <para id="x_363">In the case of the final commit, you also need to enter a
348 commit message, which is almost always going to be a piece of
349 uninteresting <quote>boilerplate</quote> text.</para>
351 <para id="x_364">It would be nice to reduce the number of steps needed, if
352 this were possible. Indeed, Mercurial is distributed with an
353 extension called <literal role="hg-ext">fetch</literal> that
354 does just this.</para>
356 <para id="x_365">Mercurial provides a flexible extension mechanism that lets
357 people extend its functionality, while keeping the core of
358 Mercurial small and easy to deal with. Some extensions add new
359 commands that you can use from the command line, while others
360 work <quote>behind the scenes,</quote> for example adding
361 capabilities to the server.</para>
363 <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a
364 new command called, not surprisingly, <command role="hg-cmd">hg
365 fetch</command>. This extension acts as a combination of
366 <command role="hg-cmd">hg pull</command>, <command
367 role="hg-cmd">hg update</command> and <command
368 role="hg-cmd">hg merge</command>. It begins by pulling
369 changes from another repository into the current repository. If
370 it finds that the changes added a new head to the repository, it
371 begins a merge, then commits the result of the merge with an
372 automatically-generated commit message. If no new heads were
373 added, it updates the working directory to the new tip
374 changeset.</para>
376 <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal>
377 extension is easy. Edit your <filename
378 role="special">.hgrc</filename>, and either go to the <literal
379 role="rc-extensions">extensions</literal> section or create an
380 <literal role="rc-extensions">extensions</literal> section. Then
381 add a line that simply reads <quote><literal>fetch
382 </literal></quote>.</para>
383 <programlisting>[extensions]
384 fetch =</programlisting>
385 <para id="x_368">(Normally, on the right-hand side of the
386 <quote><literal>=</literal></quote> would appear the location of
387 the extension, but since the <literal
388 role="hg-ext">fetch</literal> extension is in the standard
389 distribution, Mercurial knows where to search for it.)</para>
391 </sect1>
392 </chapter>
394 <!--
395 local variables:
396 sgml-parent-document: ("00book.xml" "book" "chapter")
397 end:
398 -->