# HG changeset patch
# User Bryan O'Sullivan <bos@serpentine.com>
# Date 1239080744 25200
# Node ID 4e23c220d1b0dea899dae81e84398c23a9f2d302
# Parent 2b193ab0df9a86f021ab6ce6836cd6d60d39f2db
Update chapter 2
diff -r 2b193ab0df9a -r 4e23c220d1b0 en/ch02-tour-merge.xml
--- a/en/ch02-tour-merge.xml Tue Mar 31 22:56:37 2009 -0700
+++ b/en/ch02-tour-merge.xml Mon Apr 06 22:05:44 2009 -0700
@@ -112,13 +112,47 @@
<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;
+ <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
+ parents</command> will display two parents until we <command
+ role="hg-cmd">hg commit</command> the results of the
+ merge.</para>
+
+ &interaction.tour.merge.commit;
+
+ <para id="x_349">We now have a new tip revision; notice that it has
+ <emphasis>both</emphasis> of our former heads as its parents.
+ These are the same revisions that were previously displayed by
+ <command role="hg-cmd">hg parents</command>.</para>
+
+ &interaction.tour.merge.tip;
+
+ <para id="x_34a">In <xref
+ linkend="fig:tour-merge:merge"/>, you can see a
+ representation of what happens to the working directory during
+ the merge, and how this affects the repository when the commit
+ happens. During the merge, the working directory has two
+ 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>
@@ -130,47 +164,20 @@
</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
- 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
- parents</command> will display two parents until we <command
- role="hg-cmd">hg commit</command> the results of the
- merge.</para>
-
- &interaction.tour.merge.commit;
-
- <para id="x_349">We now have a new tip revision; notice that it has
- <emphasis>both</emphasis> of our former heads as its parents.
- These are the same revisions that were previously displayed by
- <command role="hg-cmd">hg parents</command>.</para>
-
- &interaction.tour.merge.tip;
-
- <para id="x_34a">In <xref
- linkend="fig:tour-merge:merge"/>, you can see a
- representation of what happens to the working directory during
- the merge, and how this affects the repository when the commit
- happens. During the merge, the working directory has two
- parent changesets, and these become the parents of the new
- changeset.</para>
-
+ <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
@@ -192,14 +199,13 @@
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
@@ -299,18 +305,12 @@
&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;
@@ -341,7 +341,7 @@
<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
@@ -360,30 +360,33 @@
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>
-
- <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
+ 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
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>
diff -r 2b193ab0df9a -r 4e23c220d1b0 en/examples/tour
--- a/en/examples/tour Tue Mar 31 22:56:37 2009 -0700
+++ b/en/examples/tour Mon Apr 06 22:05:44 2009 -0700
@@ -146,12 +146,17 @@
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
diff -r 2b193ab0df9a -r 4e23c220d1b0 en/examples/tour-merge-conflict
--- a/en/examples/tour-merge-conflict Tue Mar 31 22:56:37 2009 -0700
+++ b/en/examples/tour-merge-conflict Mon Apr 06 22:05:44 2009 -0700
@@ -56,7 +56,6 @@
#$ ignore: [<>]{7} /tmp/.*
export HGMERGE=merge
-echo 'XXX this is broken and must be fixed'
hg merge
cat letter.txt