1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/en/ch03-tour-merge.xml	Sat Sep 12 20:53:56 2009 +0200
     1.3 @@ -0,0 +1,454 @@
     1.4 +<!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
     1.5 +
     1.6 +<chapter id="chap:tour-merge">
     1.7 +  <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
     1.8 +  <title>A tour of Mercurial: merging work</title>
     1.9 +
    1.10 +  <para id="x_338">We've now covered cloning a repository, making changes in a
    1.11 +    repository, and pulling or pushing changes from one repository
    1.12 +    into another.  Our next step is <emphasis>merging</emphasis>
    1.13 +    changes from separate repositories.</para>
    1.14 +
    1.15 +  <sect1>
    1.16 +    <title>Merging streams of work</title>
    1.17 +
    1.18 +    <para id="x_339">Merging is a fundamental part of working with a distributed
    1.19 +      revision control tool.  Here are a few cases in which the need
    1.20 +      to merge work arises.</para>
    1.21 +    <itemizedlist>
    1.22 +      <listitem>
    1.23 +	<para id="x_33a">Alice and Bob each have a personal copy of a
    1.24 +	  repository for a project they're collaborating on.  Alice
    1.25 +	  fixes a bug in her repository; Bob adds a new feature in
    1.26 +	  his.  They want the shared repository to contain both the
    1.27 +	  bug fix and the new feature.</para>
    1.28 +      </listitem>
    1.29 +      <listitem>
    1.30 +	<para id="x_33b">Cynthia frequently works on several different
    1.31 +	  tasks for a single project at once, each safely isolated in
    1.32 +	  its own repository. Working this way means that she often
    1.33 +	  needs to merge one piece of her own work with
    1.34 +	  another.</para>
    1.35 +      </listitem>
    1.36 +    </itemizedlist>
    1.37 +
    1.38 +    <para id="x_33c">Because we need to merge often, Mercurial makes
    1.39 +      the process easy.  Let's walk through a merge.  We'll begin by
    1.40 +      cloning yet another repository (see how often they spring up?)
    1.41 +      and making a change in it.</para>
    1.42 +
    1.43 +    &interaction.tour.merge.clone;
    1.44 +
    1.45 +    <para id="x_33d">We should now have two copies of
    1.46 +      <filename>hello.c</filename> with different contents.  The
    1.47 +      histories of the two repositories have also diverged, as
    1.48 +      illustrated in <xref
    1.49 +	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
    1.50 +      file from one repository.</para>
    1.51 +
    1.52 +    &interaction.tour.merge.cat1;
    1.53 +
    1.54 +    <para id="x_722">And here is our slightly different version from the other
    1.55 +      repository.</para>
    1.56 +
    1.57 +    &interaction.tour.merge.cat2;
    1.58 +
    1.59 +    <figure id="fig:tour-merge:sep-repos">
    1.60 +      <title>Divergent recent histories of the <filename
    1.61 +	  class="directory">my-hello</filename> and <filename
    1.62 +	  class="directory">my-new-hello</filename>
    1.63 +	repositories</title>
    1.64 +      <mediaobject>
    1.65 +	<imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
    1.66 +	<textobject><phrase>XXX add text</phrase></textobject>
    1.67 +      </mediaobject>
    1.68 +    </figure>
    1.69 +
    1.70 +    <para id="x_33f">We already know that pulling changes from our <filename
    1.71 +	class="directory">my-hello</filename> repository will have no
    1.72 +      effect on the working directory.</para>
    1.73 +
    1.74 +    &interaction.tour.merge.pull;
    1.75 +
    1.76 +    <para id="x_340">However, the <command role="hg-cmd">hg pull</command>
    1.77 +      command says something about <quote>heads</quote>.</para>
    1.78 +
    1.79 +    <sect2>
    1.80 +      <title>Head changesets</title>
    1.81 +
    1.82 +      <para id="x_341">Remember that Mercurial records what the parent
    1.83 +	of each change is.  If a change has a parent, we call it a
    1.84 +	child or descendant of the parent.  A head is a change that
    1.85 +	has no children.  The tip revision is thus a head, because the
    1.86 +	newest revision in a repository doesn't have any children.
    1.87 +	There are times when a repository can contain more than one
    1.88 +	head.</para>
    1.89 +
    1.90 +      <figure id="fig:tour-merge:pull">
    1.91 +	<title>Repository contents after pulling from <filename
    1.92 +	    class="directory">my-hello</filename> into <filename
    1.93 +	    class="directory">my-new-hello</filename></title>
    1.94 +	<mediaobject>
    1.95 +	  <imageobject>
    1.96 +	    <imagedata fileref="figs/tour-merge-pull.png"/>
    1.97 +	  </imageobject>
    1.98 +	  <textobject><phrase>XXX add text</phrase></textobject>
    1.99 +	</mediaobject>
   1.100 +      </figure>
   1.101 +
   1.102 +      <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
   1.103 +	see the effect of the pull from <filename
   1.104 +	  class="directory">my-hello</filename> into <filename
   1.105 +	  class="directory">my-new-hello</filename>.  The history that
   1.106 +	was already present in <filename
   1.107 +	  class="directory">my-new-hello</filename> is untouched, but
   1.108 +	a new revision has been added.  By referring to <xref
   1.109 +	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
   1.110 +	<emphasis>changeset ID</emphasis> remains the same in the new
   1.111 +	repository, but the <emphasis>revision number</emphasis> has
   1.112 +	changed.  (This, incidentally, is a fine example of why it's
   1.113 +	not safe to use revision numbers when discussing changesets.)
   1.114 +	We can view the heads in a repository using the <command
   1.115 +	  role="hg-cmd">hg heads</command> command.</para>
   1.116 +
   1.117 +      &interaction.tour.merge.heads;
   1.118 +    </sect2>
   1.119 +
   1.120 +    <sect2>
   1.121 +      <title>Performing the merge</title>
   1.122 +
   1.123 +      <para id="x_344">What happens if we try to use the normal <command
   1.124 +	  role="hg-cmd">hg update</command> command to update to the
   1.125 +	new tip?</para>
   1.126 +
   1.127 +      &interaction.tour.merge.update;
   1.128 +
   1.129 +      <para id="x_345">Mercurial is telling us that the <command
   1.130 +	  role="hg-cmd">hg update</command> command won't do a merge;
   1.131 +	it won't update the working directory when it thinks we might
   1.132 +	want to do a merge, unless we force it to do so.
   1.133 +	(Incidentally, forcing the update with <command>hg update
   1.134 +	  -C</command> would revert any uncommitted changes in the
   1.135 +	working directory.)</para>
   1.136 +
   1.137 +      <para id="x_723">To start a merge between the two heads, we use the
   1.138 +	<command role="hg-cmd">hg merge</command> command.</para>
   1.139 +
   1.140 +      &interaction.tour.merge.merge;
   1.141 +
   1.142 +      <para id="x_347">We resolve the contents of <filename>hello.c</filename>
   1.143 +
   1.144 +This updates the working directory so that it
   1.145 +	contains changes from <emphasis>both</emphasis> heads, which
   1.146 +	is reflected in both the output of <command role="hg-cmd">hg
   1.147 +	  parents</command> and the contents of
   1.148 +	<filename>hello.c</filename>.</para>
   1.149 +
   1.150 +      &interaction.tour.merge.parents;
   1.151 +    </sect2>
   1.152 +
   1.153 +    <sect2>
   1.154 +      <title>Committing the results of the merge</title>
   1.155 +
   1.156 +      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
   1.157 +	  parents</command> will display two parents until we <command
   1.158 +	  role="hg-cmd">hg commit</command> the results of the
   1.159 +	  merge.</para>
   1.160 +
   1.161 +	&interaction.tour.merge.commit;
   1.162 +
   1.163 +      <para id="x_349">We now have a new tip revision; notice that it has
   1.164 +	<emphasis>both</emphasis> of our former heads as its parents.
   1.165 +	These are the same revisions that were previously displayed by
   1.166 +	<command role="hg-cmd">hg parents</command>.</para>
   1.167 +
   1.168 +      &interaction.tour.merge.tip;
   1.169 +
   1.170 +      <para id="x_34a">In <xref
   1.171 +	  linkend="fig:tour-merge:merge"/>, you can see a
   1.172 +	representation of what happens to the working directory during
   1.173 +	the merge, and how this affects the repository when the commit
   1.174 +	happens.  During the merge, the working directory has two
   1.175 +	parent changesets, and these become the parents of the new
   1.176 +	changeset.</para>
   1.177 +
   1.178 +      <figure id="fig:tour-merge:merge">
   1.179 +	<title>Working directory and repository during merge, and
   1.180 +	  following commit</title>
   1.181 +	<mediaobject>
   1.182 +	  <imageobject>
   1.183 +	    <imagedata fileref="figs/tour-merge-merge.png"/>
   1.184 +	  </imageobject>
   1.185 +	  <textobject><phrase>XXX add text</phrase></textobject>
   1.186 +	</mediaobject>
   1.187 +      </figure>
   1.188 +
   1.189 +      <para id="x_69c">We sometimes talk about a merge having
   1.190 +	<emphasis>sides</emphasis>: the left side is the first parent
   1.191 +	in the output of <command role="hg-cmd">hg parents</command>,
   1.192 +	and the right side is the second.  If the working directory
   1.193 +	was at e.g. revision 5 before we began a merge, that revision
   1.194 +	will become the left side of the merge.</para>
   1.195 +    </sect2>
   1.196 +  </sect1>
   1.197 +
   1.198 +  <sect1>
   1.199 +    <title>Merging conflicting changes</title>
   1.200 +
   1.201 +    <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
   1.202 +      yourself merging changes where each side modifies the same portions
   1.203 +      of the same files.  Unless both modifications are identical,
   1.204 +      this results in a <emphasis>conflict</emphasis>, where you have
   1.205 +      to decide how to reconcile the different changes into something
   1.206 +      coherent.</para>
   1.207 +
   1.208 +    <figure id="fig:tour-merge:conflict">
   1.209 +      <title>Conflicting changes to a document</title>
   1.210 +      <mediaobject>
   1.211 +	<imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
   1.212 +	<textobject><phrase>XXX add text</phrase></textobject>
   1.213 +      </mediaobject>
   1.214 +    </figure>
   1.215 +
   1.216 +    <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
   1.217 +      an instance of two conflicting changes to a document.  We
   1.218 +      started with a single version of the file; then we made some
   1.219 +      changes; while someone else made different changes to the same
   1.220 +      text.  Our task in resolving the conflicting changes is to
   1.221 +      decide what the file should look like.</para>
   1.222 +
   1.223 +    <para id="x_34e">Mercurial doesn't have a built-in facility for handling
   1.224 +      conflicts. Instead, it runs an external program, usually one
   1.225 +      that displays some kind of graphical conflict resolution
   1.226 +      interface.  By default, Mercurial tries to find one of several
   1.227 +      different merging tools that are likely to be installed on your
   1.228 +      system.  It first tries a few fully automatic merging tools; if
   1.229 +      these don't succeed (because the resolution process requires
   1.230 +      human guidance) or aren't present, it tries a few
   1.231 +      different graphical merging tools.</para>
   1.232 +
   1.233 +    <para id="x_34f">It's also possible to get Mercurial to run a
   1.234 +      specific program or script, by setting the
   1.235 +      <envar>HGMERGE</envar> environment variable to the name of your
   1.236 +      preferred program.</para>
   1.237 +
   1.238 +    <sect2>
   1.239 +      <title>Using a graphical merge tool</title>
   1.240 +
   1.241 +      <para id="x_350">My preferred graphical merge tool is
   1.242 +	<command>kdiff3</command>, which I'll use to describe the
   1.243 +	features that are common to graphical file merging tools.  You
   1.244 +	can see a screenshot of <command>kdiff3</command> in action in
   1.245 +	<xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
   1.246 +	merge it is performing is called a <emphasis>three-way
   1.247 +	  merge</emphasis>, because there are three different versions
   1.248 +	of the file of interest to us.  The tool thus splits the upper
   1.249 +	portion of the window into three panes:</para>
   1.250 +      <itemizedlist>
   1.251 +	<listitem><para id="x_351">At the left is the <emphasis>base</emphasis>
   1.252 +	    version of the file, i.e. the most recent version from
   1.253 +	    which the two versions we're trying to merge are
   1.254 +	    descended.</para>
   1.255 +	</listitem>
   1.256 +	<listitem><para id="x_352">In the middle is <quote>our</quote> version of
   1.257 +	    the file, with the contents that we modified.</para>
   1.258 +	</listitem>
   1.259 +	<listitem><para id="x_353">On the right is <quote>their</quote> version
   1.260 +	    of the file, the one that from the changeset that we're
   1.261 +	    trying to merge with.</para>
   1.262 +	</listitem></itemizedlist>
   1.263 +      <para id="x_354">In the pane below these is the current
   1.264 +	<emphasis>result</emphasis> of the merge. Our task is to
   1.265 +	replace all of the red text, which indicates unresolved
   1.266 +	conflicts, with some sensible merger of the
   1.267 +	<quote>ours</quote> and <quote>theirs</quote> versions of the
   1.268 +	file.</para>
   1.269 +
   1.270 +      <para id="x_355">All four of these panes are <emphasis>locked
   1.271 +	  together</emphasis>; if we scroll vertically or horizontally
   1.272 +	in any of them, the others are updated to display the
   1.273 +	corresponding sections of their respective files.</para>
   1.274 +
   1.275 +      <figure id="fig:tour-merge:kdiff3">
   1.276 +	<title>Using <command>kdiff3</command> to merge versions of a
   1.277 +	  file</title>
   1.278 +	<mediaobject>
   1.279 +	  <imageobject>
   1.280 +	    <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
   1.281 +	  <textobject>
   1.282 +	    <phrase>XXX add text</phrase>
   1.283 +	  </textobject>
   1.284 +	</mediaobject>
   1.285 +      </figure>
   1.286 +
   1.287 +      <para id="x_357">For each conflicting portion of the file, we can choose to
   1.288 +	resolve the conflict using some combination of text from the
   1.289 +	base version, ours, or theirs.  We can also manually edit the
   1.290 +	merged file at any time, in case we need to make further
   1.291 +	modifications.</para>
   1.292 +
   1.293 +      <para id="x_358">There are <emphasis>many</emphasis> file merging tools
   1.294 +	available, too many to cover here.  They vary in which
   1.295 +	platforms they are available for, and in their particular
   1.296 +	strengths and weaknesses.  Most are tuned for merging files
   1.297 +	containing plain text, while a few are aimed at specialised
   1.298 +	file formats (generally XML).</para>
   1.299 +    </sect2>
   1.300 +
   1.301 +    <sect2>
   1.302 +      <title>A worked example</title>
   1.303 +
   1.304 +      <para id="x_359">In this example, we will reproduce the file modification
   1.305 +	history of <xref linkend="fig:tour-merge:conflict"/>
   1.306 +	above.  Let's begin by creating a repository with a base
   1.307 +	version of our document.</para>
   1.308 +
   1.309 +      &interaction.tour-merge-conflict.wife;
   1.310 +
   1.311 +      <para id="x_35a">We'll clone the repository and make a change to the
   1.312 +	file.</para>
   1.313 +
   1.314 +      &interaction.tour-merge-conflict.cousin;
   1.315 +
   1.316 +      <para id="x_35b">And another clone, to simulate someone else making a
   1.317 +	change to the file. (This hints at the idea that it's not all
   1.318 +	that unusual to merge with yourself when you isolate tasks in
   1.319 +	separate repositories, and indeed to find and resolve
   1.320 +	conflicts while doing so.)</para>
   1.321 +
   1.322 +      &interaction.tour-merge-conflict.son;
   1.323 +
   1.324 +      <para id="x_35c">Having created two
   1.325 +	different versions of the file, we'll set up an environment
   1.326 +	suitable for running our merge.</para>
   1.327 +
   1.328 +      &interaction.tour-merge-conflict.pull;
   1.329 +
   1.330 +      <para id="x_35d">In this example, I'll set
   1.331 +	<envar>HGMERGE</envar> to tell Mercurial to use the
   1.332 +	non-interactive <command>merge</command> command.  This is
   1.333 +	bundled with many Unix-like systems. (If you're following this
   1.334 +	example on your computer, don't bother setting
   1.335 +	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
   1.336 +	merge tool instead, which is much preferable.)</para>
   1.337 +
   1.338 +      &interaction.tour-merge-conflict.merge;
   1.339 +
   1.340 +      <para id="x_35f">Because <command>merge</command> can't resolve the
   1.341 +	conflicting changes, it leaves <emphasis>merge
   1.342 +	  markers</emphasis> inside the file that has conflicts,
   1.343 +	indicating which lines have conflicts, and whether they came
   1.344 +	from our version of the file or theirs.</para>
   1.345 +
   1.346 +      <para id="x_360">Mercurial can tell from the way <command>merge</command>
   1.347 +	exits that it wasn't able to merge successfully, so it tells
   1.348 +	us what commands we'll need to run if we want to redo the
   1.349 +	merging operation.  This could be useful if, for example, we
   1.350 +	were running a graphical merge tool and quit because we were
   1.351 +	confused or realised we had made a mistake.</para>
   1.352 +
   1.353 +      <para id="x_361">If automatic or manual merges fail, there's nothing to
   1.354 +	prevent us from <quote>fixing up</quote> the affected files
   1.355 +	ourselves, and committing the results of our merge:</para>
   1.356 +
   1.357 +      &interaction.tour-merge-conflict.commit;
   1.358 +
   1.359 +      <note>
   1.360 +	<title>Where is the <command>hg resolve</command> command?</title>
   1.361 +
   1.362 +	<para id="x_724">The <command>hg resolve</command> command was introduced
   1.363 +	  in Mercurial 1.1, which was released in December 2008. If
   1.364 +	  you are using an older version of Mercurial (run <command>hg
   1.365 +	    version</command> to see), this command will not be
   1.366 +	  present.  If your version of Mercurial is older than 1.1,
   1.367 +	  you should strongly consider upgrading to a newer version
   1.368 +	  before trying to tackle complicated merges.</para>
   1.369 +      </note>
   1.370 +    </sect2>
   1.371 +  </sect1>
   1.372 +
   1.373 +  <sect1 id="sec:tour-merge:fetch">
   1.374 +    <title>Simplifying the pull-merge-commit sequence</title>
   1.375 +
   1.376 +    <para id="x_362">The process of merging changes as outlined above is
   1.377 +      straightforward, but requires running three commands in
   1.378 +      sequence.</para>
   1.379 +    <programlisting>hg pull -u
   1.380 +hg merge
   1.381 +hg commit -m 'Merged remote changes'</programlisting>
   1.382 +    <para id="x_363">In the case of the final commit, you also need to enter a
   1.383 +      commit message, which is almost always going to be a piece of
   1.384 +      uninteresting <quote>boilerplate</quote> text.</para>
   1.385 +
   1.386 +    <para id="x_364">It would be nice to reduce the number of steps needed, if
   1.387 +      this were possible.  Indeed, Mercurial is distributed with an
   1.388 +      extension called <literal role="hg-ext">fetch</literal> that
   1.389 +      does just this.</para>
   1.390 +
   1.391 +    <para id="x_365">Mercurial provides a flexible extension mechanism that lets
   1.392 +      people extend its functionality, while keeping the core of
   1.393 +      Mercurial small and easy to deal with.  Some extensions add new
   1.394 +      commands that you can use from the command line, while others
   1.395 +      work <quote>behind the scenes,</quote> for example adding
   1.396 +      capabilities to Mercurial's built-in server mode.</para>
   1.397 +
   1.398 +    <para id="x_366">The <literal role="hg-ext">fetch</literal>
   1.399 +      extension adds a new command called, not surprisingly, <command
   1.400 +	role="hg-cmd">hg fetch</command>.  This extension acts as a
   1.401 +      combination of <command role="hg-cmd">hg pull -u</command>,
   1.402 +      <command role="hg-cmd">hg merge</command> and <command
   1.403 +	role="hg-cmd">hg commit</command>.  It begins by pulling
   1.404 +      changes from another repository into the current repository.  If
   1.405 +      it finds that the changes added a new head to the repository, it
   1.406 +      updates to the new head, begins a merge, then (if the merge
   1.407 +      succeeded) commits the result of the merge with an
   1.408 +      automatically-generated commit message.  If no new heads were
   1.409 +      added, it updates the working directory to the new tip
   1.410 +      changeset.</para>
   1.411 +
   1.412 +    <para id="x_367">Enabling the <literal
   1.413 +	role="hg-ext">fetch</literal> extension is easy.  Edit the
   1.414 +      <filename role="special">.hgrc</filename> file in your home
   1.415 +      directory, and either go to the <literal
   1.416 +	role="rc-extensions">extensions</literal> section or create an
   1.417 +      <literal role="rc-extensions">extensions</literal> section. Then
   1.418 +      add a line that simply reads
   1.419 +      <quote><literal>fetch=</literal></quote>.</para>
   1.420 +
   1.421 +    <programlisting>[extensions]
   1.422 +fetch =</programlisting>
   1.423 +
   1.424 +    <para id="x_368">(Normally, the right-hand side of the
   1.425 +      <quote><literal>=</literal></quote> would indicate where to find
   1.426 +      the extension, but since the <literal
   1.427 +	role="hg-ext">fetch</literal> extension is in the standard
   1.428 +      distribution, Mercurial knows where to search for it.)</para>
   1.429 +  </sect1>
   1.430 +
   1.431 +  <sect1>
   1.432 +    <title>Renaming, copying, and merging</title>
   1.433 +
   1.434 +    <para id="x_729">During the life of a project, we will often want to change
   1.435 +      the layout of its files and directories. This can be as simple
   1.436 +      as renaming a single file, or as complex as restructuring the
   1.437 +      entire hierarchy of files within the project.</para>
   1.438 +
   1.439 +    <para id="x_72a">Mercurial supports these kinds of complex changes fluently,
   1.440 +      provided we tell it what we're doing.  If we want to rename a
   1.441 +      file, we should use the <command>hg rename</command><footnote>
   1.442 +	<para id="x_72b">If you're a Unix user, you'll be glad to know that the
   1.443 +	  <command>hg rename</command> command can be abbreviated as
   1.444 +	  <command>hg mv</command>.</para>
   1.445 +      </footnote> command to rename it, so that Mercurial can do the
   1.446 +      right thing later when we merge.</para>
   1.447 +
   1.448 +    <para id="x_72c">We will cover the use of these commands in more detail in
   1.449 +      <xref linkend="chap:daily.copy"/>.</para>
   1.450 +  </sect1>
   1.451 +</chapter>
   1.452 +
   1.453 +<!--
   1.454 +local variables: 
   1.455 +sgml-parent-document: ("00book.xml" "book" "chapter")
   1.456 +end:
   1.457 +-->