[svnbook] r3891 committed - Finish issue #74 ('Term "natural history" lacks definition/...

[svnbook at googlecode.com]

Revision: 3891
Author:   ptburba at gmail.com
Date:     Thu Jul  7 09:32:16 2011
Log:      Finish issue #74 ('Term "natural history" lacks definition/
explanation').

* src/en/book/ch04-branching-and-merging.xml
   (svn.branchmerge.nomergedata): Add a sidebar with a brief
    description of natural history/implicit mergeinfo.  Resist
    urge to over-explain.

http://code.google.com/p/svnbook/source/detail?r=3891

Modified:
  /trunk/src/en/book/ch04-branching-and-merging.xml

=======================================
--- /trunk/src/en/book/ch04-branching-and-merging.xml	Tue Jul  5 12:18:43  
2011
+++ /trunk/src/en/book/ch04-branching-and-merging.xml	Thu Jul  7 09:32:16  
2011
@@ -1609,6 +1609,38 @@
          </varlistentry>
        </variablelist>

+    <sidebar>
+      <title>Natural History and Implicit Mergeinfo</title>
+
+      <para>When a path has the <literal>svn:mergeinfo</literal>
+        property set on it we speak of it as having 'explicit' mergeinfo.
+        Yes, this implies a path can have 'implicit' mergeinfo!  Implicit
+        mergeinfo, sometimes called 'natural history', is simply a path's
+        own history (see <xref linkend="svn.tour.history"/>) interpreted
+        as mergeinfo.  While implicit mergeinfo is largely an
+        implementation detail, it can be a useful abstraction for
+        understanding merge tracking behavior.</para>
+        <para>Let's say you created <literal>^/trunk</literal> in revision
+        100 and then copied <literal>^/trunk at 200</literal> to
+        <literal>^/branches/feature-branch-1</literal> in revision 201.
+        The implicit mergeinfo of <literal>^/branches/feature-branch-1
+        </literal> is then:</para>
+          <screen>
+/trunk:100-200
+/branches/feature-branch-1:201</screen>
+        <para>Implicit mergeinfo does not actually show up in the
+        <literal>svn:mergeinfo</literal> property, but Subversion acts
+        like it does.  That is why if you checked out
+        <literal>^/branches/feature-branch-1 at 201</literal> and tried
+        the following merge nothing would happen:</para>
+          <screen>
+svn merge ^/trunk feature-branch-working-copy -c 58</screen>
+        <para>Subversion sees that revision 58 of
+        <literal>^/trunk</literal> is already present in the target's
+        natural history so it doesn't repeat the merge (avoiding repeat
+        merges being a primary goal of merge tracking).</para>
+    </sidebar>
+
      </sect2>

      <!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->