1.1 --- a/en/ch02-tour-merge.xml	Thu Apr 16 23:46:45 2009 -0700
     1.2 +++ b/en/ch02-tour-merge.xml	Sun May 03 20:27:09 2009 -0700
     1.3 @@ -13,24 +13,29 @@
     1.4      <title>Merging streams of work</title>
     1.5  
     1.6      <para id="x_339">Merging is a fundamental part of working with a distributed
     1.7 -      revision control tool.</para>
     1.8 +      revision control tool.  Here are a few cases in which the need
     1.9 +      to merge work arises.</para>
    1.10      <itemizedlist>
    1.11 -      <listitem><para id="x_33a">Alice and Bob each have a personal copy of a
    1.12 +      <listitem>
    1.13 +	<para id="x_33a">Alice and Bob each have a personal copy of a
    1.14  	  repository for a project they're collaborating on.  Alice
    1.15  	  fixes a bug in her repository; Bob adds a new feature in
    1.16  	  his.  They want the shared repository to contain both the
    1.17  	  bug fix and the new feature.</para>
    1.18        </listitem>
    1.19 -      <listitem><para id="x_33b">I frequently work on several different tasks for
    1.20 -	  a single project at once, each safely isolated in its own
    1.21 -	  repository. Working this way means that I often need to
    1.22 -	  merge one piece of my own work with another.</para>
    1.23 -      </listitem></itemizedlist>
    1.24 -
    1.25 -    <para id="x_33c">Because merging is such a common thing to need to do,
    1.26 -      Mercurial makes it easy.  Let's walk through the process.  We'll
    1.27 -      begin by cloning yet another repository (see how often they
    1.28 -      spring up?) and making a change in it.</para>
    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 @@ -38,9 +43,15 @@
    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"/>.</para>
    1.50 -
    1.51 -    &interaction.tour.merge.cat;
    1.52 +	linkend="fig:tour-merge:sep-repos"/>.  Here is a copy of our
    1.53 +      file from one repository.</para>
    1.54 +
    1.55 +    &interaction.tour.merge.cat1;
    1.56 +
    1.57 +    <para>And here is our slightly different version from the other
    1.58 +      repository.</para>
    1.59 +
    1.60 +    &interaction.tour.merge.cat2;
    1.61  
    1.62      <figure id="fig:tour-merge:sep-repos">
    1.63        <title>Divergent recent histories of the <filename
    1.64 @@ -65,10 +76,12 @@
    1.65      <sect2>
    1.66        <title>Head changesets</title>
    1.67  
    1.68 -      <para id="x_341">A head is a change that has no descendants, or children,
    1.69 -	as they're also known.  The tip revision is thus a head,
    1.70 -	because the newest revision in a repository doesn't have any
    1.71 -	children, but a repository can contain more than one
    1.72 +      <para id="x_341">Remember that Mercurial records what the parent
    1.73 +	of each change is.  If a change has a parent, we call it a
    1.74 +	child or descendant of the parent.  A head is a change that
    1.75 +	has no children.  The tip revision is thus a head, because the
    1.76 +	newest revision in a repository doesn't have any children.
    1.77 +	There are times when a repository can contain more than one
    1.78  	head.</para>
    1.79  
    1.80        <figure id="fig:tour-merge:pull">
    1.81 @@ -99,8 +112,8 @@
    1.82  	  role="hg-cmd">hg heads</command> command.</para>
    1.83  
    1.84        &interaction.tour.merge.heads;
    1.85 -
    1.86      </sect2>
    1.87 +
    1.88      <sect2>
    1.89        <title>Performing the merge</title>
    1.90  
    1.91 @@ -110,23 +123,28 @@
    1.92  
    1.93        &interaction.tour.merge.update;
    1.94  
    1.95 -      <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
    1.96 -	  update</command> command won't do a merge; it won't update
    1.97 -	the working directory when it thinks we might want to do
    1.98 -	a merge, unless we force it to do so.  Instead, we use the
    1.99 -	<command role="hg-cmd">hg merge</command> command to merge the
   1.100 -	two heads.</para>
   1.101 +      <para id="x_345">Mercurial is telling us that the <command
   1.102 +	  role="hg-cmd">hg update</command> command won't do a merge;
   1.103 +	it won't update the working directory when it thinks we might
   1.104 +	want to do a merge, unless we force it to do so.
   1.105 +	(Incidentally, forcing the update with <command>hg update
   1.106 +	  -C</command> would revert any uncommitted changes in the
   1.107 +	working directory.)</para>
   1.108 +
   1.109 +      <para>To start a merge between the two heads, we use the
   1.110 +	<command role="hg-cmd">hg merge</command> command.</para>
   1.111  
   1.112        &interaction.tour.merge.merge;
   1.113  
   1.114 -      <para id="x_347">This updates the working directory so that it contains
   1.115 -	changes from <emphasis>both</emphasis> heads, which is
   1.116 -	reflected in both the output of <command role="hg-cmd">hg
   1.117 +      <para id="x_347">We resolve the contents of <filename>hello.c</filename>
   1.118 +
   1.119 +This updates the working directory so that it
   1.120 +	contains changes from <emphasis>both</emphasis> heads, which
   1.121 +	is reflected in both the output of <command role="hg-cmd">hg
   1.122  	  parents</command> and the contents of
   1.123  	<filename>hello.c</filename>.</para>
   1.124  
   1.125        &interaction.tour.merge.parents;
   1.126 -
   1.127      </sect2>
   1.128      <sect2>
   1.129        <title>Committing the results of the merge</title>
   1.130 @@ -208,8 +226,8 @@
   1.131        human guidance) or aren't present, it tries a few
   1.132        different graphical merging tools.</para>
   1.133  
   1.134 -    <para id="x_34f">It's also possible to get Mercurial to run another program
   1.135 -      or script instead of <command>hgmerge</command>, by setting the
   1.136 +    <para id="x_34f">It's also possible to get Mercurial to run a
   1.137 +      specific program or script, by setting the
   1.138        <envar>HGMERGE</envar> environment variable to the name of your
   1.139        preferred program.</para>
   1.140  
   1.141 @@ -310,7 +328,8 @@
   1.142  	non-interactive <command>merge</command> command.  This is
   1.143  	bundled with many Unix-like systems. (If you're following this
   1.144  	example on your computer, don't bother setting
   1.145 -	<envar>HGMERGE</envar>.)</para>
   1.146 +	<envar>HGMERGE</envar>.  You'll get dropped into a GUI file
   1.147 +	merge tool instead, which is much preferable.)</para>
   1.148  
   1.149        &interaction.tour-merge-conflict.merge;
   1.150  
   1.151 @@ -333,6 +352,17 @@
   1.152  
   1.153        &interaction.tour-merge-conflict.commit;
   1.154  
   1.155 +      <note>
   1.156 +	<title>Where is the <command>hg resolve</command> command?</title>
   1.157 +
   1.158 +	<para>The <command>hg resolve</command> command was introduced
   1.159 +	  in Mercurial 1.1, which was released in December 2008. If
   1.160 +	  you are using an older version of Mercurial (run <command>hg
   1.161 +	    version</command> to see), this command will not be
   1.162 +	  present.  If your version of Mercurial is older than 1.1,
   1.163 +	  you should strongly consider upgrading to a newer version
   1.164 +	  before trying to tackle complicated merges.</para>
   1.165 +      </note>
   1.166      </sect2>
   1.167    </sect1>
   1.168    <sect1 id="sec:tour-merge:fetch">
   1.169 @@ -358,7 +388,7 @@
   1.170        Mercurial small and easy to deal with.  Some extensions add new
   1.171        commands that you can use from the command line, while others
   1.172        work <quote>behind the scenes,</quote> for example adding
   1.173 -      capabilities to the server.</para>
   1.174 +      capabilities to Mercurial's built-in server mode.</para>
   1.175  
   1.176      <para id="x_366">The <literal role="hg-ext">fetch</literal>
   1.177        extension adds a new command called, not surprisingly, <command
   1.178 @@ -368,10 +398,11 @@
   1.179  	role="hg-cmd">hg commit</command>.  It begins by pulling
   1.180        changes from another repository into the current repository.  If
   1.181        it finds that the changes added a new head to the repository, it
   1.182 -      begins a merge, then (if the merge succeeded) commits the result
   1.183 -      of the merge with an automatically-generated commit message.  If
   1.184 -      no new heads were added, it updates the working directory to the
   1.185 -      new tip changeset.</para>
   1.186 +      updates to the new head, begins a merge, then (if the merge
   1.187 +      succeeded) commits the result of the merge with an
   1.188 +      automatically-generated commit message.  If no new heads were
   1.189 +      added, it updates the working directory to the new tip
   1.190 +      changeset.</para>
   1.191  
   1.192      <para id="x_367">Enabling the <literal
   1.193  	role="hg-ext">fetch</literal> extension is easy.  Edit the