bos@559: <!-- vim: set filetype=docbkxml shiftwidth=2 autoindent expandtab tw=77 : -->
bos@559: 
bos@559: <chapter id="chap:tour-merge">
bos@572:   <?dbhtml filename="a-tour-of-mercurial-merging-work.html"?>
bos@559:   <title>A tour of Mercurial: merging work</title>
bos@559: 
bos@584:   <para id="x_338">We've now covered cloning a repository, making changes in a
bos@559:     repository, and pulling or pushing changes from one repository
bos@559:     into another.  Our next step is <emphasis>merging</emphasis>
bos@559:     changes from separate repositories.</para>
bos@559: 
bos@559:   <sect1>
bos@559:     <title>Merging streams of work</title>
bos@559: 
bos@584:     <para id="x_339">Merging is a fundamental part of working with a distributed
bos@559:       revision control tool.</para>
bos@559:     <itemizedlist>
bos@584:       <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
bos@559: 	  repository for a project they're collaborating on.  Alice
bos@559: 	  fixes a bug in her repository; Bob adds a new feature in
bos@559: 	  his.  They want the shared repository to contain both the
bos@559: 	  bug fix and the new feature.</para>
bos@559:       </listitem>
bos@584:       <listitem><para id="x_33b">I frequently work on several different tasks for
bos@559: 	  a single project at once, each safely isolated in its own
bos@559: 	  repository. Working this way means that I often need to
bos@559: 	  merge one piece of my own work with another.</para>
bos@559:       </listitem></itemizedlist>
bos@559: 
bos@584:     <para id="x_33c">Because merging is such a common thing to need to do,
bos@559:       Mercurial makes it easy.  Let's walk through the process.  We'll
bos@559:       begin by cloning yet another repository (see how often they
bos@559:       spring up?) and making a change in it.</para>
bos@559: 
bos@567:     &interaction.tour.merge.clone;
bos@559: 
bos@584:     <para id="x_33d">We should now have two copies of
bos@559:       <filename>hello.c</filename> with different contents.  The
bos@559:       histories of the two repositories have also diverged, as
bos@592:       illustrated in <xref
bos@559: 	linkend="fig:tour-merge:sep-repos"/>.</para>
bos@559: 
bos@567:     &interaction.tour.merge.cat;
bos@559: 
bos@591:     <figure id="fig:tour-merge:sep-repos">
bos@591:       <title>Divergent recent histories of the <filename
bos@591: 	  class="directory">my-hello</filename> and <filename
bos@591: 	  class="directory">my-new-hello</filename>
bos@591: 	repositories</title>
bos@559:       <mediaobject>
bos@594: 	<imageobject><imagedata fileref="figs/tour-merge-sep-repos.png"/></imageobject>
bos@559: 	<textobject><phrase>XXX add text</phrase></textobject>
bos@559:       </mediaobject>
bos@591:     </figure>
bos@559: 
bos@584:     <para id="x_33f">We already know that pulling changes from our <filename
bos@559: 	class="directory">my-hello</filename> repository will have no
bos@559:       effect on the working directory.</para>
bos@559: 
bos@567:     &interaction.tour.merge.pull;
bos@559: 
bos@584:     <para id="x_340">However, the <command role="hg-cmd">hg pull</command>
bos@559:       command says something about <quote>heads</quote>.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Head changesets</title>
bos@559: 
bos@584:       <para id="x_341">A head is a change that has no descendants, or children,
bos@559: 	as they're also known.  The tip revision is thus a head,
bos@559: 	because the newest revision in a repository doesn't have any
bos@559: 	children, but a repository can contain more than one
bos@559: 	head.</para>
bos@559: 
bos@591:       <figure id="fig:tour-merge:pull">
bos@591: 	<title>Repository contents after pulling from <filename
bos@591: 	    class="directory">my-hello</filename> into <filename
bos@591: 	    class="directory">my-new-hello</filename></title>
bos@591: 	<mediaobject>
bos@591: 	  <imageobject>
bos@594: 	    <imagedata fileref="figs/tour-merge-pull.png"/>
bos@591: 	  </imageobject>
bos@591: 	  <textobject><phrase>XXX add text</phrase></textobject>
bos@559: 	</mediaobject>
bos@591:       </figure>
bos@559: 
bos@592:       <para id="x_343">In <xref linkend="fig:tour-merge:pull"/>, you can
bos@559: 	see the effect of the pull from <filename
bos@559: 	  class="directory">my-hello</filename> into <filename
bos@559: 	  class="directory">my-new-hello</filename>.  The history that
bos@559: 	was already present in <filename
bos@559: 	  class="directory">my-new-hello</filename> is untouched, but
bos@592: 	a new revision has been added.  By referring to <xref
bos@559: 	  linkend="fig:tour-merge:sep-repos"/>, we can see that the
bos@559: 	<emphasis>changeset ID</emphasis> remains the same in the new
bos@559: 	repository, but the <emphasis>revision number</emphasis> has
bos@559: 	changed.  (This, incidentally, is a fine example of why it's
bos@559: 	not safe to use revision numbers when discussing changesets.)
bos@559: 	We can view the heads in a repository using the <command
bos@559: 	  role="hg-cmd">hg heads</command> command.</para>
bos@559: 
bos@567:       &interaction.tour.merge.heads;
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Performing the merge</title>
bos@559: 
bos@584:       <para id="x_344">What happens if we try to use the normal <command
bos@559: 	  role="hg-cmd">hg update</command> command to update to the
bos@559: 	new tip?</para>
bos@559: 
bos@567:       &interaction.tour.merge.update;
bos@559: 
bos@584:       <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
bos@559: 	  update</command> command won't do a merge; it won't update
bos@559: 	the working directory when it thinks we might be wanting to do
bos@559: 	a merge, unless we force it to do so.  Instead, we use the
bos@559: 	<command role="hg-cmd">hg merge</command> command to merge the
bos@559: 	two heads.</para>
bos@559: 
bos@567:       &interaction.tour.merge.merge;
bos@559: 
bos@591:       <figure id="fig:tour-merge:merge">
bos@591: 	<title>Working directory and repository during merge, and
bos@591: 	  following commit</title>
bos@591: 	<mediaobject>
bos@591: 	  <imageobject>
bos@594: 	    <imagedata fileref="figs/tour-merge-merge.png"/>
bos@591: 	  </imageobject>
bos@591: 	  <textobject><phrase>XXX add text</phrase></textobject>
bos@559: 	</mediaobject>
bos@591:       </figure>
bos@559: 
bos@584:       <para id="x_347">This updates the working directory so that it contains
bos@559: 	changes from <emphasis>both</emphasis> heads, which is
bos@559: 	reflected in both the output of <command role="hg-cmd">hg
bos@559: 	  parents</command> and the contents of
bos@559: 	<filename>hello.c</filename>.</para>
bos@559: 
bos@567:       &interaction.tour.merge.parents;
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>Committing the results of the merge</title>
bos@559: 
bos@584:       <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
bos@559: 	  parents</command> will display two parents until we <command
bos@559: 	  role="hg-cmd">hg commit</command> the results of the
bos@559: 	  merge.</para>
bos@559: 
bos@567: 	&interaction.tour.merge.commit;
bos@559: 
bos@584:       <para id="x_349">We now have a new tip revision; notice that it has
bos@559: 	<emphasis>both</emphasis> of our former heads as its parents.
bos@559: 	These are the same revisions that were previously displayed by
bos@559: 	<command role="hg-cmd">hg parents</command>.</para>
bos@559: 
bos@567:       &interaction.tour.merge.tip;
bos@559: 
bos@592:       <para id="x_34a">In <xref
bos@559: 	  linkend="fig:tour-merge:merge"/>, you can see a
bos@559: 	representation of what happens to the working directory during
bos@559: 	the merge, and how this affects the repository when the commit
bos@559: 	happens.  During the merge, the working directory has two
bos@559: 	parent changesets, and these become the parents of the new
bos@559: 	changeset.</para>
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1>
bos@559:     <title>Merging conflicting changes</title>
bos@559: 
bos@584:     <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
bos@559:       yourself merging changes where each modifies the same portions
bos@559:       of the same files.  Unless both modifications are identical,
bos@559:       this results in a <emphasis>conflict</emphasis>, where you have
bos@559:       to decide how to reconcile the different changes into something
bos@559:       coherent.</para>
bos@559: 
bos@591:     <figure id="fig:tour-merge:conflict">
bos@591:       <title>Conflicting changes to a document</title>
bos@591:       <mediaobject>
bos@594: 	<imageobject><imagedata fileref="figs/tour-merge-conflict.png"/></imageobject>
bos@559: 	<textobject><phrase>XXX add text</phrase></textobject>
bos@591:       </mediaobject>
bos@591:     </figure>
bos@559: 
bos@592:     <para id="x_34d"><xref linkend="fig:tour-merge:conflict"/> illustrates
bos@559:       an instance of two conflicting changes to a document.  We
bos@559:       started with a single version of the file; then we made some
bos@559:       changes; while someone else made different changes to the same
bos@559:       text.  Our task in resolving the conflicting changes is to
bos@559:       decide what the file should look like.</para>
bos@559: 
bos@584:     <para id="x_34e">Mercurial doesn't have a built-in facility for handling
bos@559:       conflicts. Instead, it runs an external program called
bos@559:       <command>hgmerge</command>.  This is a shell script that is
bos@559:       bundled with Mercurial; you can change it to behave however you
bos@559:       please.  What it does by default is try to find one of several
bos@559:       different merging tools that are likely to be installed on your
bos@559:       system.  It first tries a few fully automatic merging tools; if
bos@559:       these don't succeed (because the resolution process requires
bos@559:       human guidance) or aren't present, the script tries a few
bos@559:       different graphical merging tools.</para>
bos@559: 
bos@584:     <para id="x_34f">It's also possible to get Mercurial to run another program
bos@559:       or script instead of <command>hgmerge</command>, by setting the
bos@559:       <envar>HGMERGE</envar> environment variable to the name of your
bos@559:       preferred program.</para>
bos@559: 
bos@559:     <sect2>
bos@559:       <title>Using a graphical merge tool</title>
bos@559: 
bos@584:       <para id="x_350">My preferred graphical merge tool is
bos@559: 	<command>kdiff3</command>, which I'll use to describe the
bos@559: 	features that are common to graphical file merging tools.  You
bos@559: 	can see a screenshot of <command>kdiff3</command> in action in
bos@592: 	<xref linkend="fig:tour-merge:kdiff3"/>.  The kind of
bos@559: 	merge it is performing is called a <emphasis>three-way
bos@559: 	  merge</emphasis>, because there are three different versions
bos@559: 	of the file of interest to us.  The tool thus splits the upper
bos@559: 	portion of the window into three panes:</para>
bos@559:       <itemizedlist>
bos@584: 	<listitem><para id="x_351">At the left is the <emphasis>base</emphasis>
bos@559: 	    version of the file, i.e. the most recent version from
bos@559: 	    which the two versions we're trying to merge are
bos@559: 	    descended.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_352">In the middle is <quote>our</quote> version of
bos@559: 	    the file, with the contents that we modified.</para>
bos@559: 	</listitem>
bos@584: 	<listitem><para id="x_353">On the right is <quote>their</quote> version
bos@559: 	    of the file, the one that from the changeset that we're
bos@559: 	    trying to merge with.</para>
bos@559: 	</listitem></itemizedlist>
bos@584:       <para id="x_354">In the pane below these is the current
bos@559: 	<emphasis>result</emphasis> of the merge. Our task is to
bos@559: 	replace all of the red text, which indicates unresolved
bos@559: 	conflicts, with some sensible merger of the
bos@559: 	<quote>ours</quote> and <quote>theirs</quote> versions of the
bos@559: 	file.</para>
bos@559: 
bos@584:       <para id="x_355">All four of these panes are <emphasis>locked
bos@559: 	  together</emphasis>; if we scroll vertically or horizontally
bos@559: 	in any of them, the others are updated to display the
bos@559: 	corresponding sections of their respective files.</para>
bos@559: 
bos@591:       <figure id="fig:tour-merge:kdiff3">
bos@591: 	<title>Using <command>kdiff3</command> to merge versions of a
bos@591: 	  file</title>
bos@591: 	<mediaobject>
bos@591: 	  <imageobject>
dongsheng@655: 	    <imagedata width="100%" fileref="figs/kdiff3.png"/></imageobject>
bos@591: 	  <textobject>
bos@591: 	    <phrase>XXX add text</phrase>
bos@591: 	  </textobject>
bos@559: 	</mediaobject>
bos@591:       </figure>
bos@559: 
bos@584:       <para id="x_357">For each conflicting portion of the file, we can choose to
bos@559: 	resolve the conflict using some combination of text from the
bos@559: 	base version, ours, or theirs.  We can also manually edit the
bos@559: 	merged file at any time, in case we need to make further
bos@559: 	modifications.</para>
bos@559: 
bos@584:       <para id="x_358">There are <emphasis>many</emphasis> file merging tools
bos@559: 	available, too many to cover here.  They vary in which
bos@559: 	platforms they are available for, and in their particular
bos@559: 	strengths and weaknesses.  Most are tuned for merging files
bos@559: 	containing plain text, while a few are aimed at specialised
bos@559: 	file formats (generally XML).</para>
bos@559: 
bos@559:     </sect2>
bos@559:     <sect2>
bos@559:       <title>A worked example</title>
bos@559: 
bos@584:       <para id="x_359">In this example, we will reproduce the file modification
bos@592: 	history of <xref linkend="fig:tour-merge:conflict"/>
bos@559: 	above.  Let's begin by creating a repository with a base
bos@559: 	version of our document.</para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.wife;
bos@559: 
bos@584:       <para id="x_35a">We'll clone the repository and make a change to the
bos@559: 	file.</para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.cousin;
bos@559: 
bos@584:       <para id="x_35b">And another clone, to simulate someone else making a
bos@559: 	change to the file. (This hints at the idea that it's not all
bos@559: 	that unusual to merge with yourself when you isolate tasks in
bos@559: 	separate repositories, and indeed to find and resolve
bos@559: 	conflicts while doing so.)</para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.son;
bos@559: 
bos@584:       <para id="x_35c">Having created two
bos@559: 	different versions of the file, we'll set up an environment
bos@559: 	suitable for running our merge.</para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.pull;
bos@559: 
bos@584:       <para id="x_35d">In this example, I won't use Mercurial's normal
bos@559: 	<command>hgmerge</command> program to do the merge, because it
bos@559: 	would drop my nice automated example-running tool into a
bos@559: 	graphical user interface.  Instead, I'll set
bos@559: 	<envar>HGMERGE</envar> to tell Mercurial to use the
bos@559: 	non-interactive <command>merge</command> command.  This is
bos@559: 	bundled with many Unix-like systems. If you're following this
bos@559: 	example on your computer, don't bother setting
bos@559: 	<envar>HGMERGE</envar>.</para>
bos@559: 
bos@584:       <para id="x_35e"><emphasis role="bold">XXX FIX THIS
bos@559: 	  EXAMPLE.</emphasis></para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.merge;
bos@559: 
bos@584:       <para id="x_35f">Because <command>merge</command> can't resolve the
bos@559: 	conflicting changes, it leaves <emphasis>merge
bos@559: 	  markers</emphasis> inside the file that has conflicts,
bos@559: 	indicating which lines have conflicts, and whether they came
bos@559: 	from our version of the file or theirs.</para>
bos@559: 
bos@584:       <para id="x_360">Mercurial can tell from the way <command>merge</command>
bos@559: 	exits that it wasn't able to merge successfully, so it tells
bos@559: 	us what commands we'll need to run if we want to redo the
bos@559: 	merging operation.  This could be useful if, for example, we
bos@559: 	were running a graphical merge tool and quit because we were
bos@559: 	confused or realised we had made a mistake.</para>
bos@559: 
bos@584:       <para id="x_361">If automatic or manual merges fail, there's nothing to
bos@559: 	prevent us from <quote>fixing up</quote> the affected files
bos@559: 	ourselves, and committing the results of our merge:</para>
bos@559: 
bos@567:       &interaction.tour-merge-conflict.commit;
bos@559: 
bos@559:     </sect2>
bos@559:   </sect1>
bos@559:   <sect1 id="sec:tour-merge:fetch">
bos@559:     <title>Simplifying the pull-merge-commit sequence</title>
bos@559: 
bos@584:     <para id="x_362">The process of merging changes as outlined above is
bos@559:       straightforward, but requires running three commands in
bos@559:       sequence.</para>
bos@579:     <programlisting>hg pull
bos@579: hg merge
bos@579: hg commit -m 'Merged remote changes'</programlisting>
bos@584:     <para id="x_363">In the case of the final commit, you also need to enter a
bos@559:       commit message, which is almost always going to be a piece of
bos@559:       uninteresting <quote>boilerplate</quote> text.</para>
bos@559: 
bos@584:     <para id="x_364">It would be nice to reduce the number of steps needed, if
bos@559:       this were possible.  Indeed, Mercurial is distributed with an
bos@559:       extension called <literal role="hg-ext">fetch</literal> that
bos@559:       does just this.</para>
bos@559: 
bos@584:     <para id="x_365">Mercurial provides a flexible extension mechanism that lets
bos@559:       people extend its functionality, while keeping the core of
bos@559:       Mercurial small and easy to deal with.  Some extensions add new
bos@559:       commands that you can use from the command line, while others
bos@559:       work <quote>behind the scenes,</quote> for example adding
bos@559:       capabilities to the server.</para>
bos@559: 
bos@584:     <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a
bos@559:       new command called, not surprisingly, <command role="hg-cmd">hg
bos@559: 	fetch</command>.  This extension acts as a combination of
bos@559:       <command role="hg-cmd">hg pull</command>, <command
bos@559: 	role="hg-cmd">hg update</command> and <command
bos@559: 	role="hg-cmd">hg merge</command>.  It begins by pulling
bos@559:       changes from another repository into the current repository.  If
bos@559:       it finds that the changes added a new head to the repository, it
bos@559:       begins a merge, then commits the result of the merge with an
bos@559:       automatically-generated commit message.  If no new heads were
bos@559:       added, it updates the working directory to the new tip
bos@559:       changeset.</para>
bos@559: 
bos@584:     <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal>
bos@559:       extension is easy.  Edit your <filename
bos@559: 	role="special">.hgrc</filename>, and either go to the <literal
bos@559: 	role="rc-extensions">extensions</literal> section or create an
bos@559:       <literal role="rc-extensions">extensions</literal> section. Then
bos@559:       add a line that simply reads <quote><literal>fetch
bos@559: 	</literal></quote>.</para>
bos@579:     <programlisting>[extensions]
bos@579: fetch =</programlisting>
bos@584:     <para id="x_368">(Normally, on the right-hand side of the
bos@559:       <quote><literal>=</literal></quote> would appear the location of
bos@559:       the extension, but since the <literal
bos@559: 	role="hg-ext">fetch</literal> extension is in the standard
bos@559:       distribution, Mercurial knows where to search for it.)</para>
bos@559: 
bos@559:   </sect1>
bos@559: </chapter>
bos@559: 
bos@559: <!--
bos@559: local variables: 
bos@559: sgml-parent-document: ("00book.xml" "book" "chapter")
bos@559: end:
bos@559: -->