1.1 --- a/en/ch02-tour-merge.xml	Thu Mar 26 22:00:53 2009 -0700
     1.2 +++ b/en/ch02-tour-merge.xml	Mon Apr 06 22:05:44 2009 -0700
     1.3 @@ -112,13 +112,47 @@
     1.4  
     1.5        <para id="x_345">Mercurial is telling us that the <command role="hg-cmd">hg
     1.6  	  update</command> command won't do a merge; it won't update
     1.7 -	the working directory when it thinks we might be wanting to do
     1.8 +	the working directory when it thinks we might want to do
     1.9  	a merge, unless we force it to do so.  Instead, we use the
    1.10  	<command role="hg-cmd">hg merge</command> command to merge the
    1.11  	two heads.</para>
    1.12  
    1.13        &interaction.tour.merge.merge;
    1.14  
    1.15 +      <para id="x_347">This updates the working directory so that it contains
    1.16 +	changes from <emphasis>both</emphasis> heads, which is
    1.17 +	reflected in both the output of <command role="hg-cmd">hg
    1.18 +	  parents</command> and the contents of
    1.19 +	<filename>hello.c</filename>.</para>
    1.20 +
    1.21 +      &interaction.tour.merge.parents;
    1.22 +
    1.23 +    </sect2>
    1.24 +    <sect2>
    1.25 +      <title>Committing the results of the merge</title>
    1.26 +
    1.27 +      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
    1.28 +	  parents</command> will display two parents until we <command
    1.29 +	  role="hg-cmd">hg commit</command> the results of the
    1.30 +	  merge.</para>
    1.31 +
    1.32 +	&interaction.tour.merge.commit;
    1.33 +
    1.34 +      <para id="x_349">We now have a new tip revision; notice that it has
    1.35 +	<emphasis>both</emphasis> of our former heads as its parents.
    1.36 +	These are the same revisions that were previously displayed by
    1.37 +	<command role="hg-cmd">hg parents</command>.</para>
    1.38 +
    1.39 +      &interaction.tour.merge.tip;
    1.40 +
    1.41 +      <para id="x_34a">In <xref
    1.42 +	  linkend="fig:tour-merge:merge"/>, you can see a
    1.43 +	representation of what happens to the working directory during
    1.44 +	the merge, and how this affects the repository when the commit
    1.45 +	happens.  During the merge, the working directory has two
    1.46 +	parent changesets, and these become the parents of the new
    1.47 +	changeset.</para>
    1.48 +
    1.49        <figure id="fig:tour-merge:merge">
    1.50  	<title>Working directory and repository during merge, and
    1.51  	  following commit</title>
    1.52 @@ -130,47 +164,20 @@
    1.53  	</mediaobject>
    1.54        </figure>
    1.55  
    1.56 -      <para id="x_347">This updates the working directory so that it contains
    1.57 -	changes from <emphasis>both</emphasis> heads, which is
    1.58 -	reflected in both the output of <command role="hg-cmd">hg
    1.59 -	  parents</command> and the contents of
    1.60 -	<filename>hello.c</filename>.</para>
    1.61 -
    1.62 -      &interaction.tour.merge.parents;
    1.63 -
    1.64 -    </sect2>
    1.65 -    <sect2>
    1.66 -      <title>Committing the results of the merge</title>
    1.67 -
    1.68 -      <para id="x_348">Whenever we've done a merge, <command role="hg-cmd">hg
    1.69 -	  parents</command> will display two parents until we <command
    1.70 -	  role="hg-cmd">hg commit</command> the results of the
    1.71 -	  merge.</para>
    1.72 -
    1.73 -	&interaction.tour.merge.commit;
    1.74 -
    1.75 -      <para id="x_349">We now have a new tip revision; notice that it has
    1.76 -	<emphasis>both</emphasis> of our former heads as its parents.
    1.77 -	These are the same revisions that were previously displayed by
    1.78 -	<command role="hg-cmd">hg parents</command>.</para>
    1.79 -
    1.80 -      &interaction.tour.merge.tip;
    1.81 -
    1.82 -      <para id="x_34a">In <xref
    1.83 -	  linkend="fig:tour-merge:merge"/>, you can see a
    1.84 -	representation of what happens to the working directory during
    1.85 -	the merge, and how this affects the repository when the commit
    1.86 -	happens.  During the merge, the working directory has two
    1.87 -	parent changesets, and these become the parents of the new
    1.88 -	changeset.</para>
    1.89 -
    1.90 +      <para>We sometimes talk about a merge having
    1.91 +	<emphasis>sides</emphasis>: the left side is the first parent
    1.92 +	in the output of <command rold="hg-cmd">hg parents</command>,
    1.93 +	and the right side is the second.  If the working directory
    1.94 +	was at e.g. revision 5 before we began a merge, that revision
    1.95 +	will become the left side of the merge.</para>
    1.96      </sect2>
    1.97    </sect1>
    1.98 +
    1.99    <sect1>
   1.100      <title>Merging conflicting changes</title>
   1.101  
   1.102      <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
   1.103 -      yourself merging changes where each modifies the same portions
   1.104 +      yourself merging changes where each side modifies the same portions
   1.105        of the same files.  Unless both modifications are identical,
   1.106        this results in a <emphasis>conflict</emphasis>, where you have
   1.107        to decide how to reconcile the different changes into something
   1.108 @@ -192,14 +199,13 @@
   1.109        decide what the file should look like.</para>
   1.110  
   1.111      <para id="x_34e">Mercurial doesn't have a built-in facility for handling
   1.112 -      conflicts. Instead, it runs an external program called
   1.113 -      <command>hgmerge</command>.  This is a shell script that is
   1.114 -      bundled with Mercurial; you can change it to behave however you
   1.115 -      please.  What it does by default is try to find one of several
   1.116 +      conflicts. Instead, it runs an external program, usually one
   1.117 +      that displays some kind of graphical conflict resolution
   1.118 +      interface.  By default, Mercurial tries to find one of several
   1.119        different merging tools that are likely to be installed on your
   1.120        system.  It first tries a few fully automatic merging tools; if
   1.121        these don't succeed (because the resolution process requires
   1.122 -      human guidance) or aren't present, the script tries a few
   1.123 +      human guidance) or aren't present, it tries a few
   1.124        different graphical merging tools.</para>
   1.125  
   1.126      <para id="x_34f">It's also possible to get Mercurial to run another program
   1.127 @@ -299,18 +305,12 @@
   1.128  
   1.129        &interaction.tour-merge-conflict.pull;
   1.130  
   1.131 -      <para id="x_35d">In this example, I won't use Mercurial's normal
   1.132 -	<command>hgmerge</command> program to do the merge, because it
   1.133 -	would drop my nice automated example-running tool into a
   1.134 -	graphical user interface.  Instead, I'll set
   1.135 +      <para id="x_35d">In this example, I'll set
   1.136  	<envar>HGMERGE</envar> to tell Mercurial to use the
   1.137  	non-interactive <command>merge</command> command.  This is
   1.138 -	bundled with many Unix-like systems. If you're following this
   1.139 +	bundled with many Unix-like systems. (If you're following this
   1.140  	example on your computer, don't bother setting
   1.141 -	<envar>HGMERGE</envar>.</para>
   1.142 -
   1.143 -      <para id="x_35e"><emphasis role="bold">XXX FIX THIS
   1.144 -	  EXAMPLE.</emphasis></para>
   1.145 +	<envar>HGMERGE</envar>.)</para>
   1.146  
   1.147        &interaction.tour-merge-conflict.merge;
   1.148  
   1.149 @@ -341,7 +341,7 @@
   1.150      <para id="x_362">The process of merging changes as outlined above is
   1.151        straightforward, but requires running three commands in
   1.152        sequence.</para>
   1.153 -    <programlisting>hg pull
   1.154 +    <programlisting>hg pull -u
   1.155  hg merge
   1.156  hg commit -m 'Merged remote changes'</programlisting>
   1.157      <para id="x_363">In the case of the final commit, you also need to enter a
   1.158 @@ -360,30 +360,33 @@
   1.159        work <quote>behind the scenes,</quote> for example adding
   1.160        capabilities to the server.</para>
   1.161  
   1.162 -    <para id="x_366">The <literal role="hg-ext">fetch</literal> extension adds a
   1.163 -      new command called, not surprisingly, <command role="hg-cmd">hg
   1.164 -	fetch</command>.  This extension acts as a combination of
   1.165 -      <command role="hg-cmd">hg pull</command>, <command
   1.166 -	role="hg-cmd">hg update</command> and <command
   1.167 -	role="hg-cmd">hg merge</command>.  It begins by pulling
   1.168 +    <para id="x_366">The <literal role="hg-ext">fetch</literal>
   1.169 +      extension adds a new command called, not surprisingly, <command
   1.170 +	role="hg-cmd">hg fetch</command>.  This extension acts as a
   1.171 +      combination of <command role="hg-cmd">hg pull -u</command>,
   1.172 +      <command role="hg-cmd">hg merge</command> and <command
   1.173 +	role="hg-cmd">hg commit</command>.  It begins by pulling
   1.174        changes from another repository into the current repository.  If
   1.175        it finds that the changes added a new head to the repository, it
   1.176 -      begins a merge, then commits the result of the merge with an
   1.177 -      automatically-generated commit message.  If no new heads were
   1.178 -      added, it updates the working directory to the new tip
   1.179 -      changeset.</para>
   1.180 -
   1.181 -    <para id="x_367">Enabling the <literal role="hg-ext">fetch</literal>
   1.182 -      extension is easy.  Edit your <filename
   1.183 -	role="special">.hgrc</filename>, and either go to the <literal
   1.184 +      begins a merge, then (if the merge succeeded) commits the result
   1.185 +      of the merge with an automatically-generated commit message.  If
   1.186 +      no new heads were added, it updates the working directory to the
   1.187 +      new tip changeset.</para>
   1.188 +
   1.189 +    <para id="x_367">Enabling the <literal
   1.190 +	role="hg-ext">fetch</literal> extension is easy.  Edit the
   1.191 +      <filename role="special">.hgrc</filename> file in your home
   1.192 +      directory, and either go to the <literal
   1.193  	role="rc-extensions">extensions</literal> section or create an
   1.194        <literal role="rc-extensions">extensions</literal> section. Then
   1.195 -      add a line that simply reads <quote><literal>fetch
   1.196 -	</literal></quote>.</para>
   1.197 +      add a line that simply reads
   1.198 +      <quote><literal>fetch=</literal></quote>.</para>
   1.199 +
   1.200      <programlisting>[extensions]
   1.201  fetch =</programlisting>
   1.202 -    <para id="x_368">(Normally, on the right-hand side of the
   1.203 -      <quote><literal>=</literal></quote> would appear the location of
   1.204 +
   1.205 +    <para id="x_368">(Normally, the right-hand side of the
   1.206 +      <quote><literal>=</literal></quote> would indicate where to find
   1.207        the extension, but since the <literal
   1.208  	role="hg-ext">fetch</literal> extension is in the standard
   1.209        distribution, Mercurial knows where to search for it.)</para>