comparison en/ch02-tour-merge.xml @ 826:a17d6390a480

More fixes to chapters 1 and 2.

825:d7d09cda83d2

  <sect1>
    <title>Merging streams of work</title>

    <para id="x_339">Merging is a fundamental part of working with a distributed
      revision control tool.</para>
    <itemizedlist>
      <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
	  repository for a project they're collaborating on.  Alice
	  fixes a bug in her repository; Bob adds a new feature in
	  his.  They want the shared repository to contain both the
	  bug fix and the new feature.</para>
      </listitem>
      <listitem><para id="x_33b">I frequently work on several different tasks for
	  a single project at once, each safely isolated in its own
	  repository. Working this way means that I often need to
	  merge one piece of my own work with another.</para>
      </listitem></itemizedlist>

    <para id="x_33c">Because merging is such a common thing to need to do,
      Mercurial makes it easy.  Let's walk through the process.  We'll
      begin by cloning yet another repository (see how often they
      spring up?) and making a change in it.</para>

    &interaction.tour.merge.clone;

    <para id="x_33d">We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in <xref
	linkend="fig:tour-merge:sep-repos"/>.</para>

    &interaction.tour.merge.cat;

    <figure id="fig:tour-merge:sep-repos">
      <title>Divergent recent histories of the <filename
	  class="directory">my-hello</filename> and <filename
	  class="directory">my-new-hello</filename>

      command says something about <quote>heads</quote>.</para>

    <sect2>
      <title>Head changesets</title>

      <para id="x_341">A head is a change that has no descendants, or children,
	as they're also known.  The tip revision is thus a head,
	because the newest revision in a repository doesn't have any
	children, but a repository can contain more than one
	head.</para>

      <figure id="fig:tour-merge:pull">
	<title>Repository contents after pulling from <filename
	    class="directory">my-hello</filename> into <filename

	not safe to use revision numbers when discussing changesets.)
	We can view the heads in a repository using the <command
	  role="hg-cmd">hg heads</command> command.</para>

      &interaction.tour.merge.heads;

    </sect2>
    <sect2>
      <title>Performing the merge</title>

      <para id="x_344">What happens if we try to use the normal <command
	  role="hg-cmd">hg update</command> command to update to the
	new tip?</para>

      &interaction.tour.merge.update;

      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
	  update</command> command won't do a merge; it won't update
	the working directory when it thinks we might want to do
	a merge, unless we force it to do so.  Instead, we use the
	<command role="hg-cmd">hg merge</command> command to merge the
	two heads.</para>

      &interaction.tour.merge.merge;

      <para id="x_347">This updates the working directory so that it contains
	changes from <emphasis>both</emphasis> heads, which is
	reflected in both the output of <command role="hg-cmd">hg
	  parents</command> and the contents of
	<filename>hello.c</filename>.</para>

      &interaction.tour.merge.parents;

    </sect2>
    <sect2>
      <title>Committing the results of the merge</title>

      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg

      system.  It first tries a few fully automatic merging tools; if
      these don't succeed (because the resolution process requires
      human guidance) or aren't present, it tries a few
      different graphical merging tools.</para>

    <para id="x_34f">It's also possible to get Mercurial to run another program
      or script instead of <command>hgmerge</command>, by setting the
      <envar>HGMERGE</envar> environment variable to the name of your
      preferred program.</para>

    <sect2>
      <title>Using a graphical merge tool</title>

      <para id="x_35d">In this example, I'll set
	<envar>HGMERGE</envar> to tell Mercurial to use the
	non-interactive <command>merge</command> command.  This is
	bundled with many Unix-like systems. (If you're following this
	example on your computer, don't bother setting
	<envar>HGMERGE</envar>.)</para>

      &interaction.tour-merge-conflict.merge;

      <para id="x_35f">Because <command>merge</command> can't resolve the
	conflicting changes, it leaves <emphasis>merge

	prevent us from <quote>fixing up</quote> the affected files
	ourselves, and committing the results of our merge:</para>

      &interaction.tour-merge-conflict.commit;

    </sect2>
  </sect1>
  <sect1 id="sec:tour-merge:fetch">
    <title>Simplifying the pull-merge-commit sequence</title>

    <para id="x_365">Mercurial provides a flexible extension mechanism that lets
      people extend its functionality, while keeping the core of
      Mercurial small and easy to deal with.  Some extensions add new
      commands that you can use from the command line, while others
      work <quote>behind the scenes,</quote> for example adding
      capabilities to the server.</para>

    <para id="x_366">The <literal role="hg-ext">fetch</literal>
      extension adds a new command called, not surprisingly, <command
	role="hg-cmd">hg fetch</command>.  This extension acts as a
      combination of <command role="hg-cmd">hg pull -u</command>,
      <command role="hg-cmd">hg merge</command> and <command
	role="hg-cmd">hg commit</command>.  It begins by pulling
      changes from another repository into the current repository.  If
      it finds that the changes added a new head to the repository, it
      begins a merge, then (if the merge succeeded) commits the result
      of the merge with an automatically-generated commit message.  If
      no new heads were added, it updates the working directory to the
      new tip changeset.</para>

    <para id="x_367">Enabling the <literal
	role="hg-ext">fetch</literal> extension is easy.  Edit the
      <filename role="special">.hgrc</filename> file in your home
      directory, and either go to the <literal

826:a17d6390a480

  <sect1>
    <title>Merging streams of work</title>

    <para id="x_339">Merging is a fundamental part of working with a distributed
      revision control tool.  Here are a few cases in which the need
      to merge work arises.</para>
    <itemizedlist>
      <listitem>
	<para id="x_33a">Alice and Bob each have a personal copy of a
	  repository for a project they're collaborating on.  Alice
	  fixes a bug in her repository; Bob adds a new feature in
	  his.  They want the shared repository to contain both the
	  bug fix and the new feature.</para>
      </listitem>
      <listitem>
	<para id="x_33b">Cynthia frequently works on several different
	  tasks for a single project at once, each safely isolated in
	  its own repository. Working this way means that she often
	  needs to merge one piece of her own work with
	  another.</para>
      </listitem>
    </itemizedlist>

    <para id="x_33c">Because we need to merge often, Mercurial makes
      the process easy.  Let's walk through a merge.  We'll begin by
      cloning yet another repository (see how often they spring up?)
      and making a change in it.</para>

    &interaction.tour.merge.clone;

    <para id="x_33d">We should now have two copies of
      <filename>hello.c</filename> with different contents.  The
      histories of the two repositories have also diverged, as
      illustrated in <xref
	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
      file from one repository.</para>

    &interaction.tour.merge.cat1;

    <para>And here is our slightly different version from the other
      repository.</para>

    &interaction.tour.merge.cat2;

    <figure id="fig:tour-merge:sep-repos">
      <title>Divergent recent histories of the <filename
	  class="directory">my-hello</filename> and <filename
	  class="directory">my-new-hello</filename>

      command says something about <quote>heads</quote>.</para>

    <sect2>
      <title>Head changesets</title>

      <para id="x_341">Remember that Mercurial records what the parent
	of each change is.  If a change has a parent, we call it a
	child or descendant of the parent.  A head is a change that
	has no children.  The tip revision is thus a head, because the
	newest revision in a repository doesn't have any children.
	There are times when a repository can contain more than one
	head.</para>

      <figure id="fig:tour-merge:pull">
	<title>Repository contents after pulling from <filename
	    class="directory">my-hello</filename> into <filename

	not safe to use revision numbers when discussing changesets.)
	We can view the heads in a repository using the <command
	  role="hg-cmd">hg heads</command> command.</para>

      &interaction.tour.merge.heads;
    </sect2>

    <sect2>
      <title>Performing the merge</title>

      <para id="x_344">What happens if we try to use the normal <command
	  role="hg-cmd">hg update</command> command to update to the
	new tip?</para>

      &interaction.tour.merge.update;

      <para id="x_345">Mercurial is telling us that the <command
	  role="hg-cmd">hg update</command> command won't do a merge;
	it won't update the working directory when it thinks we might
	want to do a merge, unless we force it to do so.
	(Incidentally, forcing the update with <command>hg update
	  -C</command> would revert any uncommitted changes in the
	working directory.)</para>

      <para>To start a merge between the two heads, we use the
	<command role="hg-cmd">hg merge</command> command.</para>

      &interaction.tour.merge.merge;

      <para id="x_347">We resolve the contents of <filename>hello.c</filename>

This updates the working directory so that it
	contains changes from <emphasis>both</emphasis> heads, which
	is reflected in both the output of <command role="hg-cmd">hg
	  parents</command> and the contents of
	<filename>hello.c</filename>.</para>

      &interaction.tour.merge.parents;
    </sect2>
    <sect2>
      <title>Committing the results of the merge</title>

      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg

      system.  It first tries a few fully automatic merging tools; if
      these don't succeed (because the resolution process requires
      human guidance) or aren't present, it tries a few
      different graphical merging tools.</para>

    <para id="x_34f">It's also possible to get Mercurial to run a
      specific program or script, by setting the
      <envar>HGMERGE</envar> environment variable to the name of your
      preferred program.</para>

    <sect2>
      <title>Using a graphical merge tool</title>

      <para id="x_35d">In this example, I'll set
	<envar>HGMERGE</envar> to tell Mercurial to use the
	non-interactive <command>merge</command> command.  This is
	bundled with many Unix-like systems. (If you're following this
	example on your computer, don't bother setting
	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
	merge tool instead, which is much preferable.)</para>

      &interaction.tour-merge-conflict.merge;

      <para id="x_35f">Because <command>merge</command> can't resolve the
	conflicting changes, it leaves <emphasis>merge

	prevent us from <quote>fixing up</quote> the affected files
	ourselves, and committing the results of our merge:</para>

      &interaction.tour-merge-conflict.commit;

      <note>
	<title>Where is the <command>hg resolve</command> command?</title>

	<para>The <command>hg resolve</command> command was introduced
	  in Mercurial 1.1, which was released in December 2008. If
	  you are using an older version of Mercurial (run <command>hg
	    version</command> to see), this command will not be
	  present.  If your version of Mercurial is older than 1.1,
	  you should strongly consider upgrading to a newer version
	  before trying to tackle complicated merges.</para>
      </note>
    </sect2>
  </sect1>
  <sect1 id="sec:tour-merge:fetch">
    <title>Simplifying the pull-merge-commit sequence</title>

    <para id="x_365">Mercurial provides a flexible extension mechanism that lets
      people extend its functionality, while keeping the core of
      Mercurial small and easy to deal with.  Some extensions add new
      commands that you can use from the command line, while others
      work <quote>behind the scenes,</quote> for example adding
      capabilities to Mercurial's built-in server mode.</para>

    <para id="x_366">The <literal role="hg-ext">fetch</literal>
      extension adds a new command called, not surprisingly, <command
	role="hg-cmd">hg fetch</command>.  This extension acts as a
      combination of <command role="hg-cmd">hg pull -u</command>,
      <command role="hg-cmd">hg merge</command> and <command
	role="hg-cmd">hg commit</command>.  It begins by pulling
      changes from another repository into the current repository.  If
      it finds that the changes added a new head to the repository, it
      updates to the new head, begins a merge, then (if the merge
      succeeded) commits the result of the merge with an
      automatically-generated commit message.  If no new heads were
      added, it updates the working directory to the new tip
      changeset.</para>

    <para id="x_367">Enabling the <literal
	role="hg-ext">fetch</literal> extension is easy.  Edit the
      <filename role="special">.hgrc</filename> file in your home
      directory, and either go to the <literal