hgbook
diff en/ch02-tour-merge.xml @ 584:c838b3975bc6
Add IDs to paragraphs.
author | Bryan O'Sullivan <bos@serpentine.com> |
---|---|
date | Thu Mar 19 21:18:52 2009 -0700 (2009-03-19) |
parents | 28b5a5befb08 |
children | b788b405e141 |
line diff
1.1 --- a/en/ch02-tour-merge.xml Thu Mar 19 20:54:12 2009 -0700 1.2 +++ b/en/ch02-tour-merge.xml Thu Mar 19 21:18:52 2009 -0700 1.3 @@ -4,7 +4,7 @@ 1.4 <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?> 1.5 <title>A tour of Mercurial: merging work</title> 1.6 1.7 - <para>We've now covered cloning a repository, making changes in a 1.8 + <para id="x_338">We've now covered cloning a repository, making changes in a 1.9 repository, and pulling or pushing changes from one repository 1.10 into another. Our next step is <emphasis>merging</emphasis> 1.11 changes from separate repositories.</para> 1.12 @@ -12,29 +12,29 @@ 1.13 <sect1> 1.14 <title>Merging streams of work</title> 1.15 1.16 - <para>Merging is a fundamental part of working with a distributed 1.17 + <para id="x_339">Merging is a fundamental part of working with a distributed 1.18 revision control tool.</para> 1.19 <itemizedlist> 1.20 - <listitem><para>Alice and Bob each have a personal copy of a 1.21 + <listitem><para id="x_33a">Alice and Bob each have a personal copy of a 1.22 repository for a project they're collaborating on. Alice 1.23 fixes a bug in her repository; Bob adds a new feature in 1.24 his. They want the shared repository to contain both the 1.25 bug fix and the new feature.</para> 1.26 </listitem> 1.27 - <listitem><para>I frequently work on several different tasks for 1.28 + <listitem><para id="x_33b">I frequently work on several different tasks for 1.29 a single project at once, each safely isolated in its own 1.30 repository. Working this way means that I often need to 1.31 merge one piece of my own work with another.</para> 1.32 </listitem></itemizedlist> 1.33 1.34 - <para>Because merging is such a common thing to need to do, 1.35 + <para id="x_33c">Because merging is such a common thing to need to do, 1.36 Mercurial makes it easy. Let's walk through the process. We'll 1.37 begin by cloning yet another repository (see how often they 1.38 spring up?) and making a change in it.</para> 1.39 1.40 &interaction.tour.merge.clone; 1.41 1.42 - <para>We should now have two copies of 1.43 + <para id="x_33d">We should now have two copies of 1.44 <filename>hello.c</filename> with different contents. The 1.45 histories of the two repositories have also diverged, as 1.46 illustrated in figure <xref 1.47 @@ -46,26 +46,26 @@ 1.48 <mediaobject> 1.49 <imageobject><imagedata fileref="tour-merge-sep-repos"/></imageobject> 1.50 <textobject><phrase>XXX add text</phrase></textobject> 1.51 - <caption><para>Divergent recent histories of the <filename 1.52 + <caption><para id="x_33e">Divergent recent histories of the <filename 1.53 class="directory">my-hello</filename> and <filename 1.54 class="directory">my-new-hello</filename> 1.55 repositories</para></caption> 1.56 </mediaobject> 1.57 </informalfigure> 1.58 1.59 - <para>We already know that pulling changes from our <filename 1.60 + <para id="x_33f">We already know that pulling changes from our <filename 1.61 class="directory">my-hello</filename> repository will have no 1.62 effect on the working directory.</para> 1.63 1.64 &interaction.tour.merge.pull; 1.65 1.66 - <para>However, the <command role="hg-cmd">hg pull</command> 1.67 + <para id="x_340">However, the <command role="hg-cmd">hg pull</command> 1.68 command says something about <quote>heads</quote>.</para> 1.69 1.70 <sect2> 1.71 <title>Head changesets</title> 1.72 1.73 - <para>A head is a change that has no descendants, or children, 1.74 + <para id="x_341">A head is a change that has no descendants, or children, 1.75 as they're also known. The tip revision is thus a head, 1.76 because the newest revision in a repository doesn't have any 1.77 children, but a repository can contain more than one 1.78 @@ -75,14 +75,14 @@ 1.79 <mediaobject><imageobject><imagedata 1.80 fileref="tour-merge-pull"/></imageobject><textobject><phrase>XXX 1.81 add text</phrase></textobject> 1.82 - <caption><para>Repository contents after pulling from 1.83 + <caption><para id="x_342">Repository contents after pulling from 1.84 <filename class="directory">my-hello</filename> into 1.85 <filename 1.86 class="directory">my-new-hello</filename></para></caption> 1.87 </mediaobject> 1.88 </informalfigure> 1.89 1.90 - <para>In figure <xref linkend="fig:tour-merge:pull"/>, you can 1.91 + <para id="x_343">In figure <xref linkend="fig:tour-merge:pull"/>, you can 1.92 see the effect of the pull from <filename 1.93 class="directory">my-hello</filename> into <filename 1.94 class="directory">my-new-hello</filename>. The history that 1.95 @@ -103,13 +103,13 @@ 1.96 <sect2> 1.97 <title>Performing the merge</title> 1.98 1.99 - <para>What happens if we try to use the normal <command 1.100 + <para id="x_344">What happens if we try to use the normal <command 1.101 role="hg-cmd">hg update</command> command to update to the 1.102 new tip?</para> 1.103 1.104 &interaction.tour.merge.update; 1.105 1.106 - <para>Mercurial is telling us that the <command role="hg-cmd">hg 1.107 + <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg 1.108 update</command> command won't do a merge; it won't update 1.109 the working directory when it thinks we might be wanting to do 1.110 a merge, unless we force it to do so. Instead, we use the 1.111 @@ -123,12 +123,12 @@ 1.112 <mediaobject><imageobject><imagedata 1.113 fileref="tour-merge-merge"/></imageobject><textobject><phrase>XXX 1.114 add text</phrase></textobject> 1.115 - <caption><para>Working directory and repository during 1.116 + <caption><para id="x_346">Working directory and repository during 1.117 merge, and following commit</para></caption> 1.118 </mediaobject> 1.119 </informalfigure> 1.120 1.121 - <para>This updates the working directory so that it contains 1.122 + <para id="x_347">This updates the working directory so that it contains 1.123 changes from <emphasis>both</emphasis> heads, which is 1.124 reflected in both the output of <command role="hg-cmd">hg 1.125 parents</command> and the contents of 1.126 @@ -140,21 +140,21 @@ 1.127 <sect2> 1.128 <title>Committing the results of the merge</title> 1.129 1.130 - <para>Whenever we've done a merge, <command role="hg-cmd">hg 1.131 + <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg 1.132 parents</command> will display two parents until we <command 1.133 role="hg-cmd">hg commit</command> the results of the 1.134 merge.</para> 1.135 1.136 &interaction.tour.merge.commit; 1.137 1.138 - <para>We now have a new tip revision; notice that it has 1.139 + <para id="x_349">We now have a new tip revision; notice that it has 1.140 <emphasis>both</emphasis> of our former heads as its parents. 1.141 These are the same revisions that were previously displayed by 1.142 <command role="hg-cmd">hg parents</command>.</para> 1.143 1.144 &interaction.tour.merge.tip; 1.145 1.146 - <para>In figure <xref 1.147 + <para id="x_34a">In figure <xref 1.148 linkend="fig:tour-merge:merge"/>, you can see a 1.149 representation of what happens to the working directory during 1.150 the merge, and how this affects the repository when the commit 1.151 @@ -167,7 +167,7 @@ 1.152 <sect1> 1.153 <title>Merging conflicting changes</title> 1.154 1.155 - <para>Most merges are simple affairs, but sometimes you'll find 1.156 + <para id="x_34b">Most merges are simple affairs, but sometimes you'll find 1.157 yourself merging changes where each modifies the same portions 1.158 of the same files. Unless both modifications are identical, 1.159 this results in a <emphasis>conflict</emphasis>, where you have 1.160 @@ -179,18 +179,18 @@ 1.161 <mediaobject id="fig:tour-merge:conflict"> 1.162 <imageobject><imagedata fileref="tour-merge-conflict"/></imageobject> 1.163 <textobject><phrase>XXX add text</phrase></textobject> 1.164 - <caption><para>Conflicting changes to a 1.165 + <caption><para id="x_34c">Conflicting changes to a 1.166 document</para></caption> </mediaobject> 1.167 </informalfigure> 1.168 1.169 - <para>Figure <xref linkend="fig:tour-merge:conflict"/> illustrates 1.170 + <para id="x_34d">Figure <xref linkend="fig:tour-merge:conflict"/> illustrates 1.171 an instance of two conflicting changes to a document. We 1.172 started with a single version of the file; then we made some 1.173 changes; while someone else made different changes to the same 1.174 text. Our task in resolving the conflicting changes is to 1.175 decide what the file should look like.</para> 1.176 1.177 - <para>Mercurial doesn't have a built-in facility for handling 1.178 + <para id="x_34e">Mercurial doesn't have a built-in facility for handling 1.179 conflicts. Instead, it runs an external program called 1.180 <command>hgmerge</command>. This is a shell script that is 1.181 bundled with Mercurial; you can change it to behave however you 1.182 @@ -201,7 +201,7 @@ 1.183 human guidance) or aren't present, the script tries a few 1.184 different graphical merging tools.</para> 1.185 1.186 - <para>It's also possible to get Mercurial to run another program 1.187 + <para id="x_34f">It's also possible to get Mercurial to run another program 1.188 or script instead of <command>hgmerge</command>, by setting the 1.189 <envar>HGMERGE</envar> environment variable to the name of your 1.190 preferred program.</para> 1.191 @@ -209,7 +209,7 @@ 1.192 <sect2> 1.193 <title>Using a graphical merge tool</title> 1.194 1.195 - <para>My preferred graphical merge tool is 1.196 + <para id="x_350">My preferred graphical merge tool is 1.197 <command>kdiff3</command>, which I'll use to describe the 1.198 features that are common to graphical file merging tools. You 1.199 can see a screenshot of <command>kdiff3</command> in action in 1.200 @@ -219,26 +219,26 @@ 1.201 of the file of interest to us. The tool thus splits the upper 1.202 portion of the window into three panes:</para> 1.203 <itemizedlist> 1.204 - <listitem><para>At the left is the <emphasis>base</emphasis> 1.205 + <listitem><para id="x_351">At the left is the <emphasis>base</emphasis> 1.206 version of the file, i.e. the most recent version from 1.207 which the two versions we're trying to merge are 1.208 descended.</para> 1.209 </listitem> 1.210 - <listitem><para>In the middle is <quote>our</quote> version of 1.211 + <listitem><para id="x_352">In the middle is <quote>our</quote> version of 1.212 the file, with the contents that we modified.</para> 1.213 </listitem> 1.214 - <listitem><para>On the right is <quote>their</quote> version 1.215 + <listitem><para id="x_353">On the right is <quote>their</quote> version 1.216 of the file, the one that from the changeset that we're 1.217 trying to merge with.</para> 1.218 </listitem></itemizedlist> 1.219 - <para>In the pane below these is the current 1.220 + <para id="x_354">In the pane below these is the current 1.221 <emphasis>result</emphasis> of the merge. Our task is to 1.222 replace all of the red text, which indicates unresolved 1.223 conflicts, with some sensible merger of the 1.224 <quote>ours</quote> and <quote>theirs</quote> versions of the 1.225 file.</para> 1.226 1.227 - <para>All four of these panes are <emphasis>locked 1.228 + <para id="x_355">All four of these panes are <emphasis>locked 1.229 together</emphasis>; if we scroll vertically or horizontally 1.230 in any of them, the others are updated to display the 1.231 corresponding sections of their respective files.</para> 1.232 @@ -247,18 +247,18 @@ 1.233 <mediaobject><imageobject><imagedata 1.234 fileref="kdiff3"/></imageobject><textobject><phrase>XXX 1.235 add text</phrase></textobject> 1.236 - <caption><para>Using <command>kdiff3</command> to merge 1.237 + <caption><para id="x_356">Using <command>kdiff3</command> to merge 1.238 versions of a file</para></caption> 1.239 </mediaobject> 1.240 </informalfigure> 1.241 1.242 - <para>For each conflicting portion of the file, we can choose to 1.243 + <para id="x_357">For each conflicting portion of the file, we can choose to 1.244 resolve the conflict using some combination of text from the 1.245 base version, ours, or theirs. We can also manually edit the 1.246 merged file at any time, in case we need to make further 1.247 modifications.</para> 1.248 1.249 - <para>There are <emphasis>many</emphasis> file merging tools 1.250 + <para id="x_358">There are <emphasis>many</emphasis> file merging tools 1.251 available, too many to cover here. They vary in which 1.252 platforms they are available for, and in their particular 1.253 strengths and weaknesses. Most are tuned for merging files 1.254 @@ -269,19 +269,19 @@ 1.255 <sect2> 1.256 <title>A worked example</title> 1.257 1.258 - <para>In this example, we will reproduce the file modification 1.259 + <para id="x_359">In this example, we will reproduce the file modification 1.260 history of figure <xref linkend="fig:tour-merge:conflict"/> 1.261 above. Let's begin by creating a repository with a base 1.262 version of our document.</para> 1.263 1.264 &interaction.tour-merge-conflict.wife; 1.265 1.266 - <para>We'll clone the repository and make a change to the 1.267 + <para id="x_35a">We'll clone the repository and make a change to the 1.268 file.</para> 1.269 1.270 &interaction.tour-merge-conflict.cousin; 1.271 1.272 - <para>And another clone, to simulate someone else making a 1.273 + <para id="x_35b">And another clone, to simulate someone else making a 1.274 change to the file. (This hints at the idea that it's not all 1.275 that unusual to merge with yourself when you isolate tasks in 1.276 separate repositories, and indeed to find and resolve 1.277 @@ -289,13 +289,13 @@ 1.278 1.279 &interaction.tour-merge-conflict.son; 1.280 1.281 - <para>Having created two 1.282 + <para id="x_35c">Having created two 1.283 different versions of the file, we'll set up an environment 1.284 suitable for running our merge.</para> 1.285 1.286 &interaction.tour-merge-conflict.pull; 1.287 1.288 - <para>In this example, I won't use Mercurial's normal 1.289 + <para id="x_35d">In this example, I won't use Mercurial's normal 1.290 <command>hgmerge</command> program to do the merge, because it 1.291 would drop my nice automated example-running tool into a 1.292 graphical user interface. Instead, I'll set 1.293 @@ -305,25 +305,25 @@ 1.294 example on your computer, don't bother setting 1.295 <envar>HGMERGE</envar>.</para> 1.296 1.297 - <para><emphasis role="bold">XXX FIX THIS 1.298 + <para id="x_35e"><emphasis role="bold">XXX FIX THIS 1.299 EXAMPLE.</emphasis></para> 1.300 1.301 &interaction.tour-merge-conflict.merge; 1.302 1.303 - <para>Because <command>merge</command> can't resolve the 1.304 + <para id="x_35f">Because <command>merge</command> can't resolve the 1.305 conflicting changes, it leaves <emphasis>merge 1.306 markers</emphasis> inside the file that has conflicts, 1.307 indicating which lines have conflicts, and whether they came 1.308 from our version of the file or theirs.</para> 1.309 1.310 - <para>Mercurial can tell from the way <command>merge</command> 1.311 + <para id="x_360">Mercurial can tell from the way <command>merge</command> 1.312 exits that it wasn't able to merge successfully, so it tells 1.313 us what commands we'll need to run if we want to redo the 1.314 merging operation. This could be useful if, for example, we 1.315 were running a graphical merge tool and quit because we were 1.316 confused or realised we had made a mistake.</para> 1.317 1.318 - <para>If automatic or manual merges fail, there's nothing to 1.319 + <para id="x_361">If automatic or manual merges fail, there's nothing to 1.320 prevent us from <quote>fixing up</quote> the affected files 1.321 ourselves, and committing the results of our merge:</para> 1.322 1.323 @@ -334,29 +334,29 @@ 1.324 <sect1 id="sec:tour-merge:fetch"> 1.325 <title>Simplifying the pull-merge-commit sequence</title> 1.326 1.327 - <para>The process of merging changes as outlined above is 1.328 + <para id="x_362">The process of merging changes as outlined above is 1.329 straightforward, but requires running three commands in 1.330 sequence.</para> 1.331 <programlisting>hg pull 1.332 hg merge 1.333 hg commit -m 'Merged remote changes'</programlisting> 1.334 - <para>In the case of the final commit, you also need to enter a 1.335 + <para id="x_363">In the case of the final commit, you also need to enter a 1.336 commit message, which is almost always going to be a piece of 1.337 uninteresting <quote>boilerplate</quote> text.</para> 1.338 1.339 - <para>It would be nice to reduce the number of steps needed, if 1.340 + <para id="x_364">It would be nice to reduce the number of steps needed, if 1.341 this were possible. Indeed, Mercurial is distributed with an 1.342 extension called <literal role="hg-ext">fetch</literal> that 1.343 does just this.</para> 1.344 1.345 - <para>Mercurial provides a flexible extension mechanism that lets 1.346 + <para id="x_365">Mercurial provides a flexible extension mechanism that lets 1.347 people extend its functionality, while keeping the core of 1.348 Mercurial small and easy to deal with. Some extensions add new 1.349 commands that you can use from the command line, while others 1.350 work <quote>behind the scenes,</quote> for example adding 1.351 capabilities to the server.</para> 1.352 1.353 - <para>The <literal role="hg-ext">fetch</literal> extension adds a 1.354 + <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a 1.355 new command called, not surprisingly, <command role="hg-cmd">hg 1.356 fetch</command>. This extension acts as a combination of 1.357 <command role="hg-cmd">hg pull</command>, <command 1.358 @@ -369,7 +369,7 @@ 1.359 added, it updates the working directory to the new tip 1.360 changeset.</para> 1.361 1.362 - <para>Enabling the <literal role="hg-ext">fetch</literal> 1.363 + <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal> 1.364 extension is easy. Edit your <filename 1.365 role="special">.hgrc</filename>, and either go to the <literal 1.366 role="rc-extensions">extensions</literal> section or create an 1.367 @@ -378,7 +378,7 @@ 1.368 </literal></quote>.</para> 1.369 <programlisting>[extensions] 1.370 fetch =</programlisting> 1.371 - <para>(Normally, on the right-hand side of the 1.372 + <para id="x_368">(Normally, on the right-hand side of the 1.373 <quote><literal>=</literal></quote> would appear the location of 1.374 the extension, but since the <literal 1.375 role="hg-ext">fetch</literal> extension is in the standard