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@699:       revision control tool.  Here are a few cases in which the need
bos@699:       to merge work arises.</para>
bos@559:     <itemizedlist>
bos@699:       <listitem>
bos@699: 	<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@699:       <listitem>
bos@699: 	<para id="x_33b">Cynthia frequently works on several different
bos@699: 	  tasks for a single project at once, each safely isolated in
bos@699: 	  its own repository. Working this way means that she often
bos@699: 	  needs to merge one piece of her own work with
bos@699: 	  another.</para>
bos@699:       </listitem>
bos@699:     </itemizedlist>
bos@699: 
bos@699:     <para id="x_33c">Because we need to merge often, Mercurial makes
bos@699:       the process easy.  Let's walk through a merge.  We'll begin by
bos@699:       cloning yet another repository (see how often they spring up?)
bos@699:       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@699: 	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
bos@699:       file from one repository.</para>
bos@699: 
bos@699:     &interaction.tour.merge.cat1;
bos@699: 
bos@700:     <para id="x_722">And here is our slightly different version from the other
bos@699:       repository.</para>
bos@699: 
bos@699:     &interaction.tour.merge.cat2;
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@699:       <para id="x_341">Remember that Mercurial records what the parent
bos@699: 	of each change is.  If a change has a parent, we call it a
bos@699: 	child or descendant of the parent.  A head is a change that
bos@699: 	has no children.  The tip revision is thus a head, because the
bos@699: 	newest revision in a repository doesn't have any children.
bos@699: 	There are times when 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:     </sect2>
bos@699: 
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@699:       <para id="x_345">Mercurial is telling us that the <command
bos@699: 	  role="hg-cmd">hg update</command> command won't do a merge;
bos@699: 	it won't update the working directory when it thinks we might
bos@699: 	want to do a merge, unless we force it to do so.
bos@699: 	(Incidentally, forcing the update with <command>hg update
bos@699: 	  -C</command> would revert any uncommitted changes in the
bos@699: 	working directory.)</para>
bos@699: 
bos@700:       <para id="x_723">To start a merge between the two heads, we use the
bos@699: 	<command role="hg-cmd">hg merge</command> command.</para>
bos@559: 
bos@567:       &interaction.tour.merge.merge;
bos@559: 
bos@699:       <para id="x_347">We resolve the contents of <filename>hello.c</filename>
bos@699: 
bos@699: This updates the working directory so that it
bos@699: 	contains changes from <emphasis>both</emphasis> heads, which
bos@699: 	is reflected in both the output of <command role="hg-cmd">hg
bos@619: 	  parents</command> and the contents of
bos@619: 	<filename>hello.c</filename>.</para>
bos@619: 
bos@619:       &interaction.tour.merge.parents;
bos@619:     </sect2>
bos@701: 
bos@619:     <sect2>
bos@619:       <title>Committing the results of the merge</title>
bos@619: 
bos@619:       <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
bos@619: 	  parents</command> will display two parents until we <command
bos@619: 	  role="hg-cmd">hg commit</command> the results of the
bos@619: 	  merge.</para>
bos@619: 
bos@619: 	&interaction.tour.merge.commit;
bos@619: 
bos@619:       <para id="x_349">We now have a new tip revision; notice that it has
bos@619: 	<emphasis>both</emphasis> of our former heads as its parents.
bos@619: 	These are the same revisions that were previously displayed by
bos@619: 	<command role="hg-cmd">hg parents</command>.</para>
bos@619: 
bos@619:       &interaction.tour.merge.tip;
bos@619: 
bos@619:       <para id="x_34a">In <xref
bos@619: 	  linkend="fig:tour-merge:merge"/>, you can see a
bos@619: 	representation of what happens to the working directory during
bos@619: 	the merge, and how this affects the repository when the commit
bos@619: 	happens.  During the merge, the working directory has two
bos@619: 	parent changesets, and these become the parents of the new
bos@619: 	changeset.</para>
bos@619: 
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@676:       <para id="x_69c">We sometimes talk about a merge having
bos@619: 	<emphasis>sides</emphasis>: the left side is the first parent
bos@670: 	in the output of <command role="hg-cmd">hg parents</command>,
bos@619: 	and the right side is the second.  If the working directory
bos@619: 	was at e.g. revision 5 before we began a merge, that revision
bos@619: 	will become the left side of the merge.</para>
bos@559:     </sect2>
bos@559:   </sect1>
bos@619: 
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@619:       yourself merging changes where each side 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@619:       conflicts. Instead, it runs an external program, usually one
bos@619:       that displays some kind of graphical conflict resolution
bos@619:       interface.  By default, Mercurial tries 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@619:       human guidance) or aren't present, it tries a few
bos@559:       different graphical merging tools.</para>
bos@559: 
bos@699:     <para id="x_34f">It's also possible to get Mercurial to run a
bos@699:       specific program or script, 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:     </sect2>
bos@701: 
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@619:       <para id="x_35d">In this example, 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@619: 	bundled with many Unix-like systems. (If you're following this
bos@559: 	example on your computer, don't bother setting
bos@699: 	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
bos@699: 	merge tool instead, which is much preferable.)</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@699:       <note>
bos@699: 	<title>Where is the <command>hg resolve</command> command?</title>
bos@699: 
bos@700: 	<para id="x_724">The <command>hg resolve</command> command was introduced
bos@699: 	  in Mercurial 1.1, which was released in December 2008. If
bos@699: 	  you are using an older version of Mercurial (run <command>hg
bos@699: 	    version</command> to see), this command will not be
bos@699: 	  present.  If your version of Mercurial is older than 1.1,
bos@699: 	  you should strongly consider upgrading to a newer version
bos@699: 	  before trying to tackle complicated merges.</para>
bos@699:       </note>
bos@559:     </sect2>
bos@559:   </sect1>
bos@701: 
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@619:     <programlisting>hg pull -u
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@699:       capabilities to Mercurial's built-in server mode.</para>
bos@559: 
bos@619:     <para id="x_366">The <literal role="hg-ext">fetch</literal>
bos@619:       extension adds a new command called, not surprisingly, <command
bos@619: 	role="hg-cmd">hg fetch</command>.  This extension acts as a
bos@619:       combination of <command role="hg-cmd">hg pull -u</command>,
bos@619:       <command role="hg-cmd">hg merge</command> and <command
bos@619: 	role="hg-cmd">hg commit</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@699:       updates to the new head, begins a merge, then (if the merge
bos@699:       succeeded) commits the result of the merge with an
bos@699:       automatically-generated commit message.  If no new heads were
bos@699:       added, it updates the working directory to the new tip
bos@699:       changeset.</para>
bos@619: 
bos@619:     <para id="x_367">Enabling the <literal
bos@619: 	role="hg-ext">fetch</literal> extension is easy.  Edit the
bos@619:       <filename role="special">.hgrc</filename> file in your home
bos@619:       directory, 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@619:       add a line that simply reads
bos@619:       <quote><literal>fetch=</literal></quote>.</para>
bos@619: 
bos@579:     <programlisting>[extensions]
bos@579: fetch =</programlisting>
bos@619: 
bos@619:     <para id="x_368">(Normally, the right-hand side of the
bos@619:       <quote><literal>=</literal></quote> would indicate where to find
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@701:   </sect1>
bos@701: 
bos@701:   <sect1>
bos@701:     <title>Renaming, copying, and merging</title>
bos@701: 
bos@702:     <para id="x_729">During the life of a project, we will often want to change
bos@701:       the layout of its files and directories. This can be as simple
bos@701:       as renaming a single file, or as complex as restructuring the
bos@701:       entire hierarchy of files within the project.</para>
bos@701: 
bos@702:     <para id="x_72a">Mercurial supports these kinds of complex changes fluently,
bos@701:       provided we tell it what we're doing.  If we want to rename a
bos@701:       file, we should use the <command>hg rename</command><footnote>
bos@702: 	<para id="x_72b">If you're a Unix user, you'll be glad to know that the
bos@701: 	  <command>hg rename</command> command can be abbreviated as
bos@701: 	  <command>hg mv</command>.</para>
bos@701:       </footnote> command to rename it, so that Mercurial can do the
bos@701:       right thing later when we merge.</para>
bos@701: 
bos@702:     <para id="x_72c">We will cover the use of these commands in more detail in
bos@701:       <xref linkend="chap:daily.copy"/>.</para>
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: -->