[svnbook] r4191 committed - Close issue #75 'ch04: svn merge --reintegrate does not match...
svnbook at googlecode.com
svnbook at googlecode.com
Thu Nov 10 11:21:59 CST 2011
Revision: 4191
Author: ptburba at gmail.com
Date: Thu Nov 10 09:20:50 2011
Log: Close issue #75 'ch04: svn merge --reintegrate does not match
any of the 3 usage patterns' and issue #134 'ch09: merge
reference should mirror changes made to 'svn merge --help'
text in 1.7'.
* en/book/ch09-reference.xml
(svn.ref.svn.sw): Note --ignore-ancestry's rather important
effect on 'svn merge' beyond what it shares with 'svn diff'.
(svn.ref.svn.c.merge): Rework 'svn merge' reference to more
closely track the revised 'svn merge --help' text for 1.7.
http://code.google.com/p/svnbook/source/detail?r=4191
Modified:
/trunk/en/book/ch09-reference.xml
=======================================
--- /trunk/en/book/ch09-reference.xml Thu Nov 10 08:05:17 2011
+++ /trunk/en/book/ch09-reference.xml Thu Nov 10 09:20:50 2011
@@ -467,7 +467,10 @@
<term><option>--ignore-ancestry</option></term>
<listitem>
<para>Tells Subversion to ignore ancestry when calculating
- differences (rely on path contents alone).</para>
+ differences (rely on path contents alone). Also disables
+ <xref linkend="svn.branchmerge.basicmerging.mergetracking"/>
+ when used with the <command>svn merge</command> subcommand.
+ </para>
</listitem>
</varlistentry>
@@ -3524,64 +3527,125 @@
</refnamediv>
<refsect1>
<title>Synopsis</title>
- <para><literal>svn merge sourceURL1[@N] sourceURL2[@M]
[WCPATH]</literal></para>
- <para><literal>svn merge sourceWCPATH1 at N sourceWCPATH2 at M
[WCPATH]</literal></para>
- <para><literal>svn merge [[-c M]... | [-r N:M]...] [SOURCE[@REV]
[WCPATH]]</literal></para>
+ <para><literal>svn merge [-c M[,N...] | -r N:M ...] SOURCE[@REV]
[TARGET_WCPATH]</literal></para>
+ <para><literal>svn merge --reintegrate SOURCE[@REV]
[TARGET_WCPATH]</literal></para>
+ <para><literal>svn merge SOURCE1[@N] SOURCE2[@M]
[TARGET_WCPATH]</literal></para>
</refsect1>
<refsect1>
<title>Description</title>
- <para>In the first form, the source URLs are specified at
- revisions <replaceable>N</replaceable> and
<replaceable>M</replaceable>.
- These are the two sources to be compared. The revisions
- default to <literal>HEAD</literal> if omitted.</para>
-
- <para>In the second form, the URLs corresponding to the
- source working copy paths define the sources to be
- compared. The revisions must be specified.</para>
-
- <para>In the third form, <replaceable>SOURCE</replaceable>
- can be either a URL or a working copy path (in which case
- its corresponding URL is used). If not specified,
- <replaceable>SOURCE</replaceable> will be the same as
- <replaceable>WCPATH</replaceable>.
- <replaceable>SOURCE</replaceable> in revision
- <replaceable>REV</replaceable> is compared as it existed
- between revisions <replaceable>N</replaceable> and
- <replaceable>M</replaceable> for each revision range
- provided. If <replaceable>REV</replaceable> is not
- specified, <literal>HEAD</literal> is assumed.</para>
-
- <para><literal>-c M</literal> is equivalent to <literal>-r
- <M-1>:M</literal>, and <literal>-c -M</literal> does
- the reverse: <literal>-r M:<M-1></literal>. If no
- revision ranges are specified, the default range of
- <literal>1:HEAD</literal> is used. Multiple
- <literal>-c</literal> and/or <literal>-r</literal>
- instances may be specified, and mixing of forward and
- reverse ranges is allowed—the ranges are internally
- compacted to their minimum representation before merging
- begins (which may result in no-op).</para>
-
- <para><replaceable>WCPATH</replaceable> is the working copy
- path that will receive the changes. If
- <replaceable>WCPATH</replaceable> is omitted, a default
- value of <quote><filename>.</filename></quote> is assumed,
+ <para>In all three forms
+ <replaceable>TARGET_WCPATH</replaceable> is
+ the working copy path that will receive the differences. If
+ <replaceable>TARGET_WCPATH</replaceable> is omitted, the
+ changes are applied to the current working directory,
unless the sources have identical basenames that match a
- file within <quote><filename>.</filename></quote>. In
+ file within the current working directory. In
this case, the differences will be applied to that
file.</para>
- <para>Subversion will internally track metadata about
- the merge operation only if the two sources are ancestrally
+ <para>In the first two forms, <replaceable>SOURCE</replaceable>
+ can be either a URL or a working copy path (in which case its
+ corresponding URL is used). If the peg revision
+ <replaceable>REV</replaceable> is not specified, then
+ <literal>HEAD</literal> is assumed. In the third form the
+ same rules apply for
+ <replaceable>SOURCE1</replaceable>,
+ <replaceable>SOURCE2</replaceable>,
+ <replaceable>M</replaceable>, and <replaceable>N</replaceable>
+ with the only difference being that if either source is a
+ working copy path, then the peg revisions
+ <emphasis>must</emphasis> be explicitly stated.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Sync and Cherrypick Merges</para>
+ <para>The first form, when used without either the
+ <option>-c</option> or <option>-r</option> options, is
+ called a <quote>sync</quote> merge and
+ <literal>-r 1:REV</literal> is implied. This variant is
+ used to merge all eligible changes to a branch from its
+ immediate ancestor branch, see
+ <xref linkend="svn.branchemerge.basicmerging.stayinsync"/>.
+ </para>
+ <para>When the first form is used with the
+ <option>-c</option> or <option>-r</option> options, this
+ is called a <quote>cherrypick</quote> merge and is used
+ to merge an explicitly defined set of changes from one
+ branch to another, see
+ <xref linkend="svn.branchmerge.cherrypicking"/></para>
+ <tip>
+ <para>Multiple <literal>-c</literal> and/or
+ <literal>-r</literal> instances may be specified, and
+ mixing of forward and reverse ranges is allowed—
+ the ranges are internally compacted to their minimum
+ representation before merging begins (which may result
+ in a no-op merge or conflicts that cause the merge to
+ stop before merging all of the requested
revisions).</para>
+ </tip>
+ <para>In both variants of the first form,
+ <replaceable>SOURCE</replaceable> in revision
+ <replaceable>REV</replaceable> is compared as it existed
+ between revisions <replaceable>N</replaceable> and
+ <replaceable>M</replaceable> for each revision range
+ provided.</para>
+ </listitem>
+ <listitem>
+ <para>Reintegrate Merges</para>
+ <para>The second form is called a <quote>reintegrate
+ merge</quote> and is used to bring changes from a feature
+ branch (<replaceable>SOURCE</replaceable>)
+ back into the feature branch's immediate ancestor branch
+ (<replaceable>TARGET_WCPATH</replaceable>).</para>
+ <tip>
+ <para>Reintegrate merges support only this specialized
+ use case and as such have a number of special
+ requirements and limitations that the other two merge
+ forms do not posses. See
+ <xref
linkend="svn.branchemerge.basicmerging.stayinsync"/>,
+ <xref
linkend="svn.branchemerge.basicmerging.reintegrate"/>,
+ <xref
linkend="svn.branchmerge.advanced.reintegratetwice"/>,
+ and
+ <xref linkend="svn.branchmerge.commonpatterns.feature"/>.
+ </para>
+ </tip>
+ </listitem>
+ <listitem>
+ <para>2-URL Merges</para>
+ <para>In the third form, called a <quote>2-URL Merge</quote>,
+ the difference between <replaceable>SOURCE1</replaceable>
+ at revision <replaceable>N</replaceable> and
+ <replaceable>SOURCE2</replaceable> at revision
+ <replaceable>M</replaceable> is generated and applied to
+ <replaceable>TARGET_WCPATH</replaceable>. The revisions
+ default to <literal>HEAD</literal> if omitted.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>If
+ <xref linkend="svn.branchmerge.basicmerging.mergetracking"/>
+ is active, then Subversion will internally track metadata
+ (i.e. the <literal>svn:mergeinfo</literal> property) about
+ merge operations when the two merge sources are ancestrally
related—if the first source is an ancestor of the
- second or vice versa. This is guaranteed to be the case
- when using the third form. Unlike <command>svn
- diff</command>, the merge command takes the ancestry of a
- file into consideration when performing a merge operation.
- This is very important when you're merging changes from
- one branch into another and you've renamed a file on one
- branch but not the other.</para>
+ second or vice versa—this is guaranteed to be the case
+ when using the first two forms. Subversion will also take
+ preexisting merge metadata on the working copy target into
+ account when determining what revisions to merge and in an
+ effort to avoid repeat merges and needless conflicts it may
+ only merge a subset of the requested ranges.</para>
+
+ <tip>
+ <para><xref
linkend="svn.branchmerge.basicmerging.mergetracking"/>
+ can be disabled by using the
<option>--ignore-ancestry</option>
+ option.</para>
+ </tip>
+
+ <para>Unlike <command>svn diff</command>, the merge command
+ takes the ancestry of a file into consideration when
+ performing a merge operation. This is very important when
+ you're merging changes from one branch into another and you've
+ renamed a file on one branch but not the other.</para>
</refsect1>
More information about the svnbook-dev
mailing list