[svnbook] r4141 committed - Without going too crazy, try to explain subtree merges...

[svnbook at googlecode.com]

Revision: 4141
Author:   ptburba at gmail.com
Date:     Thu Nov  3 10:35:48 2011
Log:      Without going too crazy, try to explain subtree merges
and subtree mergeinfo.

* en/book/ch04-branching-and-merging.xml
   (svn.branchemerge.basicmerging.stayinsync.subtree): New sidebar
    covering the basics of subtree merges and subtree mergeinfo.

   (svn.branchmerge.basicmerging.mergeinfo.inheritance): Add an id
    attribute to the sidebar on mergeinfo inheritance, so we can
    reference it from the new sidebar above.


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

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

=======================================
--- /trunk/en/book/ch04-branching-and-merging.xml	Tue Nov  1 15:27:02 2011
+++ /trunk/en/book/ch04-branching-and-merging.xml	Thu Nov  3 10:35:48 2011
@@ -757,6 +757,103 @@
          build, test, and <command>svn commit</command> the local
          modifications to your branch.</para>

+      <sidebar id="svn.branchemerge.basicmerging.stayinsync.subtree">
+        <title>Subtree Merges and Subtree Mergeinfo</title>
+        <para>
+          <indexterm  
zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+            <primary>subtree merge</primary>
+          </indexterm>
+          <indexterm  
zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+            <primary>subtree mergeinfo</primary>
+          </indexterm>
+          In most of the examples in this chapter the merge target is
+          the root directory of a branch (see
+          <xref linkend="svn.branchmerge.whatis"/>). While this is a
+          best practice, you may occasionally need to merge directly to
+          some child of the branch root. This type of merge is called a
+          <firstterm>subtree merge</firstterm> and the mergeinfo recorded
+          to describe it is called
+          <firstterm>subtree mergeinfo</firstterm>. There is nothing
+          special about subtree merges or subtree mergeinfo, in fact
+          there is really only one important point to keep in mind about
+          it: The complete record of merges to a branch may not be
+          contained solely in the mergeinfo on the branch root, we may have
+          to look to any subtree mergeinfo to get the full picture.
+          Fortunately Subversion does this <quote>accounting</quote> for
+          you and rarely will you need to concern yourself with it.  A
+          brief example will help explain:</para>
+
+        <informalexample>
+          <screen>
+# We need to merge r958 from trunk to branches/proj-X/doc/INSTALL
+# but that revision also affects main.c, which we don't want to merge
+$ svn log --verbose --quiet -r 958 ^/
+------------------------------------------------------------------------
+r958 | bruce | 2011-10-20 13:28:11 -0400 (Thu, 20 Oct 2011)
+Changed paths:
+   M /trunk/doc/INSTALL
+   M /trunk/src/main.c
+------------------------------------------------------------------------
+
+# No problem, we'll do a subtree merge targeting the INSTALL file
+# directly, but first take a note of what mergeinfo exists on the
+# root of the branch:
+$ cd branches/proj-X
+
+$ svn propget svn:mergeinfo --recursive
+Properties on '.':
+  svn:mergeinfo
+    /trunk:651-652
+
+# Now we perform the subtree merge, note that merge source
+# and target both point to INSTALL:
+$ svn merge ^/trunk/doc/INSTALL doc/INSTALL -c 958
+--- Merging r958 into 'doc/INSTALL':
+U    doc/INSTALL
+--- Recording mergeinfo for merge of r958 into 'doc/INSTALL':
+ G   doc/INSTALL
+
+# Once the merge is complete there is now subtree mergeinfo on INSTALL:
+$ svn propget svn:mergeinfo --recursive
+Properties on '.':
+  svn:mergeinfo
+    /trunk:651-652
+Properties on 'doc/INSTALL':
+  svn:mergeinfo
+    /trunk/doc/INSTALL:651-652,958
+
+# What if we then decide we do want all of r958? All we need do is
+# merge that revision to the root of the branch, Subversion notices
+# the subtree mergeinfo on INSTALL and doesn't try to merge any changes
+# to it, only the changes to main.c are merged:
+$ svn merge ^/subversion/trunk . -c 958
+--- Merging r958 into '.':
+U    src/main.c
+--- Recording mergeinfo for merge of r958 into '.':
+ U   .
+--- Eliding mergeinfo from 'doc/INSTALL':
+ U   doc/INSTALL
+          </screen>
+        </informalexample>
+
+        <indexterm zone="svn.branchemerge.basicmerging.stayinsync.subtree">
+          <primary>mergeinfo elision</primary>
+        </indexterm>
+
+        <para>You might be wondering why <filename>INSTALL</filename> in
+          the above example has mergeinfo for r651-652, when we only
+          merged r958. This is due to mergeinfo inheritance, which we'll
+          cover shortly in the
+          <xref  
linkend="svn.branchmerge.basicmerging.mergeinfo.inheritance"/>
+          sidebar. Also note that the subtree mergeinfo on
+          <filename>doc/INSTALL</filename> was removed, or
+          <quote>elided</quote>.  This is called
+          <firstterm>mergeinfo elision</firstterm> and it occurs
+          whenever Subversion detects redundant subtree mergeinfo.
+      </para>
+
+      </sidebar>
+
      </sect2>

      <!-- ===============================================================  
-->
@@ -1031,7 +1128,7 @@
          receiving changes to <filename>/branches/mybranch</filename>
          from the specified trunk URL.</para>

-      <sidebar>
+      <sidebar id="svn.branchmerge.basicmerging.mergeinfo.inheritance">
          <title>Mergeinfo Inheritance</title>

          <para>