Commits

Bryan O'Sullivan committed 4e23c22

Update chapter 2

Comments (0)

Files changed (3)

en/ch02-tour-merge.xml

 
       <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 be wanting to do
+	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;
 
-      <figure id="fig:tour-merge:merge">
-	<title>Working directory and repository during merge, and
-	  following commit</title>
-	<mediaobject>
-	  <imageobject>
-	    <imagedata fileref="figs/tour-merge-merge.png"/>
-	  </imageobject>
-	  <textobject><phrase>XXX add text</phrase></textobject>
-	</mediaobject>
-      </figure>
-
       <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
 	parent changesets, and these become the parents of the new
 	changeset.</para>
 
+      <figure id="fig:tour-merge:merge">
+	<title>Working directory and repository during merge, and
+	  following commit</title>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="figs/tour-merge-merge.png"/>
+	  </imageobject>
+	  <textobject><phrase>XXX add text</phrase></textobject>
+	</mediaobject>
+      </figure>
+
+      <para>We sometimes talk about a merge having
+	<emphasis>sides</emphasis>: the left side is the first parent
+	in the output of <command rold="hg-cmd">hg parents</command>,
+	and the right side is the second.  If the working directory
+	was at e.g. revision 5 before we began a merge, that revision
+	will become the left side of the merge.</para>
     </sect2>
   </sect1>
+
   <sect1>
     <title>Merging conflicting changes</title>
 
     <para id="x_34b">Most merges are simple affairs, but sometimes you'll find
-      yourself merging changes where each modifies the same portions
+      yourself merging changes where each side modifies the same portions
       of the same files.  Unless both modifications are identical,
       this results in a <emphasis>conflict</emphasis>, where you have
       to decide how to reconcile the different changes into something
       decide what the file should look like.</para>
 
     <para id="x_34e">Mercurial doesn't have a built-in facility for handling
-      conflicts. Instead, it runs an external program called
-      <command>hgmerge</command>.  This is a shell script that is
-      bundled with Mercurial; you can change it to behave however you
-      please.  What it does by default is try to find one of several
+      conflicts. Instead, it runs an external program, usually one
+      that displays some kind of graphical conflict resolution
+      interface.  By default, Mercurial tries to find one of several
       different merging tools that are likely to be installed on your
       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, the script tries a few
+      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
 
       &interaction.tour-merge-conflict.pull;
 
-      <para id="x_35d">In this example, I won't use Mercurial's normal
-	<command>hgmerge</command> program to do the merge, because it
-	would drop my nice automated example-running tool into a
-	graphical user interface.  Instead, I'll set
+      <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
+	bundled with many Unix-like systems. (If you're following this
 	example on your computer, don't bother setting
-	<envar>HGMERGE</envar>.</para>
-
-      <para id="x_35e"><emphasis role="bold">XXX FIX THIS
-	  EXAMPLE.</emphasis></para>
+	<envar>HGMERGE</envar>.)</para>
 
       &interaction.tour-merge-conflict.merge;
 
     <para id="x_362">The process of merging changes as outlined above is
       straightforward, but requires running three commands in
       sequence.</para>
-    <programlisting>hg pull
+    <programlisting>hg pull -u
 hg merge
 hg commit -m 'Merged remote changes'</programlisting>
     <para id="x_363">In the case of the final commit, you also need to enter a
       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</command>, <command
-	role="hg-cmd">hg update</command> and <command
-	role="hg-cmd">hg merge</command>.  It begins by pulling
+    <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 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>
+      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 your <filename
-	role="special">.hgrc</filename>, and either go to the <literal
+    <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
 	role="rc-extensions">extensions</literal> section or create an
       <literal role="rc-extensions">extensions</literal> section. Then
-      add a line that simply reads <quote><literal>fetch
-	</literal></quote>.</para>
+      add a line that simply reads
+      <quote><literal>fetch=</literal></quote>.</para>
+
     <programlisting>[extensions]
 fetch =</programlisting>
-    <para id="x_368">(Normally, on the right-hand side of the
-      <quote><literal>=</literal></quote> would appear the location of
+
+    <para id="x_368">(Normally, the right-hand side of the
+      <quote><literal>=</literal></quote> would indicate where to find
       the extension, but since the <literal
 	role="hg-ext">fetch</literal> extension is in the standard
       distribution, Mercurial knows where to search for it.)</para>
 
 hg push http://hg.serpentine.com/tutorial/hello
 
+#$ name:
+cp hello.c ../new-hello.c
+sed -i '/printf/i\\tprintf("once more, hello.\\n");' ../new-hello.c
+
 #$ name: merge.clone
 
 cd ..
 hg clone hello my-new-hello
 cd my-new-hello
-sed -i '/printf/i\\tprintf("once more, hello.\\n");' hello.c
+# The file new-hello.c is lightly edited.
+cp ../new-hello.c hello.c
 hg commit -m 'A new hello for a new day.'
 
 #$ name: merge.dummy2

en/examples/tour-merge-conflict

 #$ ignore: [<>]{7} /tmp/.*
 
 export HGMERGE=merge
-echo 'XXX this is broken and must be fixed'
 hg merge
 cat letter.txt