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