changeset 769:e9ef075327c1

Merge with http://bitbucket.org/dongsheng/hgbook/

--- a/en/ch02-tour-merge.xml	Tue Apr 07 11:04:18 2009 +0800
+++ b/en/ch02-tour-merge.xml	Mon Apr 06 23:15:52 2009 -0700
@@ -112,24 +112,13 @@
 
       <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
@@ -164,13 +153,31 @@
 	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 role="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>
+      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>

--- a/en/ch03-concepts.xml	Tue Apr 07 11:04:18 2009 +0800
+++ b/en/ch03-concepts.xml	Mon Apr 06 23:15:52 2009 -0700
@@ -4,14 +4,16 @@
   <?dbhtml filename="behind-the-scenes.html"?>
   <title>Behind the scenes</title>
 
-  <para id="x_2e8">Unlike many revision control systems, the concepts upon which
-    Mercurial is built are simple enough that it's easy to understand
-    how the software really works.  Knowing this certainly isn't
-    necessary, but I find it useful to have a <quote>mental
-      model</quote> of what's going on.</para>
+  <para id="x_2e8">Unlike many revision control systems, the concepts
+    upon which Mercurial is built are simple enough that it's easy to
+    understand how the software really works.  Knowing these details
+    certainly isn't necessary, so it is certainly safe to skip this
+    chapter.  However, I think you will get more out of the software
+    with a <quote>mental model</quote> of what's going on.</para>
 
-  <para id="x_2e9">This understanding gives me confidence that Mercurial has been
-    carefully designed to be both <emphasis>safe</emphasis> and
+  <para id="x_2e9">Being able to understand what's going on behind the
+    scenes gives me confidence that Mercurial has been carefully
+    designed to be both <emphasis>safe</emphasis> and
     <emphasis>efficient</emphasis>.  And just as importantly, if it's
     easy for me to retain a good idea of what the software is doing
     when I perform a revision control task, I'm less likely to be
@@ -436,19 +438,19 @@
 	  a new head, because your working directory isn't synced to
 	  whatever the current tip is.</para>
 
-	<para id="x_316">  I put the word <quote>error</quote> in quotes because
-	  all that you need to do to rectify this situation is
-	  <command role="hg-cmd">hg merge</command>, then <command
-	    role="hg-cmd">hg commit</command>.  In other words, this
-	  almost never has negative consequences; it just surprises
-	  people.  I'll discuss other ways to avoid this behaviour,
-	  and why Mercurial behaves in this initially surprising way,
-	  later on.</para>
+	<para id="x_316">  I put the word <quote>error</quote> in
+	  quotes because all that you need to do to rectify this
+	  situation is <command role="hg-cmd">hg merge</command>, then
+	  <command role="hg-cmd">hg commit</command>.  In other words,
+	  this almost never has negative consequences; it's just
+	  something of a surprise for newcomers.  I'll discuss other
+	  ways to avoid this behaviour, and why Mercurial behaves in
+	  this initially surprising way, later on.</para>
       </note>
 
     </sect2>
     <sect2>
-      <title>Merging heads</title>
+      <title>Merging changes</title>
 
       <para id="x_317">When you run the <command role="hg-cmd">hg
 	  merge</command> command, Mercurial leaves the first parent
@@ -518,7 +520,25 @@
 	merge immediately becomes overwhelming.</para>
 
     </sect2>
+
+    <sect2>
+      <title>Merging and renames</title>
+
+      <para>A surprising number of revision control systems pay little
+	or no attention to a file's <emphasis>name</emphasis> over
+	time.  For instance, it used to be common that if a file got
+	renamed on one side of a merge, the changes from the other
+	side would be silently dropped.</para>
+
+      <para>Mercurial records metadata when you tell it to perform a
+	rename or copy. It uses this metadata during a merge to do the
+	right thing in the case of a merge.  For instance, if I rename
+	a file, and you edit it without renaming it, when we merge our
+	work the file will be renamed and have your edits
+	applied.</para>
+    </sect2>
   </sect1>
+
   <sect1>
     <title>Other interesting design features</title>
 
@@ -575,8 +595,8 @@
 	  compression package).  This combination of algorithm and
 	  compression of the entire stream (instead of a revision at a
 	  time) substantially reduces the number of bytes to be
-	  transferred, yielding better network performance over almost
-	  all kinds of network.</para>
+	  transferred, yielding better network performance over most
+	  kinds of network.</para>
 
 	<para id="x_329">(If the connection is over <command>ssh</command>,
 	  Mercurial <emphasis>doesn't</emphasis> recompress the

--- a/en/examples/tour	Tue Apr 07 11:04:18 2009 +0800
+++ b/en/examples/tour	Mon Apr 06 23:15:52 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

--- a/en/examples/tour-merge-conflict	Tue Apr 07 11:04:18 2009 +0800
+++ b/en/examples/tour-merge-conflict	Mon Apr 06 23:15:52 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
 

--- a/en/figs/filelog.svg	Tue Apr 07 11:04:18 2009 +0800
+++ b/en/figs/filelog.svg	Mon Apr 06 23:15:52 2009 -0700
@@ -2,7 +2,7 @@
 <!-- Created with Inkscape (http://www.inkscape.org/) -->
 <svg
    xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:cc="http://creativecommons.org/ns#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns="http://www.w3.org/2000/svg"
@@ -13,12 +13,19 @@
    height="1052.3622047"
    id="svg2"
    sodipodi:version="0.32"
-   inkscape:version="0.45.1"
+   inkscape:version="0.46"
    sodipodi:docname="filelog.svg"
    sodipodi:docbase="/home/arun/hgbook/en"
    inkscape:output_extension="org.inkscape.output.svg.inkscape">
   <defs
      id="defs4">
+    <inkscape:perspective
+       sodipodi:type="inkscape:persp3d"
+       inkscape:vp_x="0 : 526.18109 : 1"
+       inkscape:vp_y="0 : 1000 : 0"
+       inkscape:vp_z="744.09448 : 526.18109 : 1"
+       inkscape:persp3d-origin="372.04724 : 350.78739 : 1"
+       id="perspective57" />
     <marker
        inkscape:stockid="Arrow1Mend"
        orient="auto"
@@ -189,11 +196,12 @@
      inkscape:cx="455.8122"
      inkscape:cy="520"
      inkscape:document-units="px"
-     inkscape:current-layer="layer1"
+     inkscape:current-layer="g2940"
      inkscape:window-width="1680"
      inkscape:window-height="970"
-     inkscape:window-x="0"
-     inkscape:window-y="54" />
+     inkscape:window-x="3"
+     inkscape:window-y="46"
+     showgrid="false" />
   <metadata
      id="metadata7">
     <rdf:RDF>
@@ -245,7 +253,7 @@
              id="tspan2920"
              x="323.72824"
              y="416.7626"
-             style="font-family:Courier">.hg/store/data/README.i</tspan></text>
+             style="font-family:Courier">.hg/store/data/_r_e_a_d_m_e.i</tspan></text>
       </g>
       <g
          transform="translate(3.79093e-5,-80.1853)"