[svnbook] r5366 committed - trunk/en/book/ch04-branching-and-merging.xml
cmpilato at users.sourceforge.net
cmpilato at users.sourceforge.net
Fri Jul 21 10:07:31 CDT 2017
Revision: 5366
http://sourceforge.net/p/svnbook/source/5366
Author: cmpilato
Date: 2017-07-21 15:07:31 +0000 (Fri, 21 Jul 2017)
Log Message:
-----------
* en/book/ch04-branching-and-merging.xml
Relocate the Subtree Merges section for consistent flow and concept
introduction.
Modified Paths:
--------------
trunk/en/book/ch04-branching-and-merging.xml
Modified: trunk/en/book/ch04-branching-and-merging.xml
===================================================================
--- trunk/en/book/ch04-branching-and-merging.xml 2017-07-21 14:59:49 UTC (rev 5365)
+++ trunk/en/book/ch04-branching-and-merging.xml 2017-07-21 15:07:31 UTC (rev 5366)
@@ -980,6 +980,105 @@
test, and <command>svn commit</command> the local modifications
to your branch.</para>
+ </sect2>
+
+ <!-- =============================================================== -->
+ <sect2 id="svn.branchmerge.basicmerging.stayinsync.subtree">
+ <title>Subtree Merges and Subtree Mergeinfo</title>
+ <para>
+ <indexterm>
+ <primary>merging</primary>
+ <secondary>subtree merge</secondary>
+ </indexterm>
+ <indexterm>
+ <primary>mergeinfo</primary>
+ <secondary>subtree mergeinfo</secondary>
+ </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 these concepts: the complete record of merges to a
+ branch may not be contained solely in the mergeinfo on the
+ branch root. You may have to consider subtree mergeinfo
+ to get a full accounting. Fortunately Subversion does this
+ 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? Easy, all we need do is
+# repeat the merge of that revision, but this time 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>
+
+ <para>
+ <indexterm>
+ <primary>mergeinfo</primary>
+ <secondary>elision</secondary>
+ </indexterm>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 in the
+ sidebar
+ <xref linkend="svn.branchmerge.basicmerging.mergeinfo.inheritance"
+ />. 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>
+
<tip>
<para>Prior to Subversion 1.7, merges unconditionally updated
<emphasis>all</emphasis> of the subtree mergeinfo under the
@@ -2492,107 +2591,7 @@
</sect2>
-
<!-- =============================================================== -->
- <sect2 id="svn.branchmerge.basicmerging.stayinsync.subtree">
- <title>Subtree Merges and Subtree Mergeinfo</title>
- <para>
- <indexterm>
- <primary>merging</primary>
- <secondary>subtree merge</secondary>
- </indexterm>
- <indexterm>
- <primary>mergeinfo</primary>
- <secondary>subtree mergeinfo</secondary>
- </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 these concepts: the complete record of merges to a
- branch may not be contained solely in the mergeinfo on the
- branch root. You may have to consider subtree mergeinfo
- to get a full accounting. Fortunately Subversion does this
- 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? Easy, all we need do is
-# repeat the merge of that revision, but this time 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>
-
- <para>
- <indexterm>
- <primary>mergeinfo</primary>
- <secondary>elision</secondary>
- </indexterm>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 in the
- sidebar
- <xref linkend="svn.branchmerge.basicmerging.mergeinfo.inheritance"
- />. 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>
-
- </sect2>
-
- <!-- =============================================================== -->
<sect2 id="svn.branchmerge.advanced.blockchanges">
<title>Blocking Changes</title>
More information about the svnbook-dev
mailing list