[svnbook] r4453 committed - Last of the chapter 4 review and update for 1.8 (for now at...
svnbook at googlecode.com
svnbook at googlecode.com
Tue Feb 26 17:23:35 CST 2013
Revision: 4453
Author: ptburba
Date: Tue Feb 26 15:23:29 2013
Log: Last of the chapter 4 review and update for 1.8 (for now at
least; the ongoing local move work might necessitate further
changes).
* en/book/ch04-branching-and-merging.xml
(svn.branchmerge.advanced.moves): Use sample repos for
example and fix the example -- what is described produces
a tree conflict, not a clean merge!
(svn.branchmerge.advanced.pre1.5clients): Rename a section
title, all clients are merge aware, it's *merge tracking*
awareness that we care about here.
(svn.branchmerge.advanced.finalword): Back off on the "merge
tracking is a nightmare" tone, while still admitting it can
be tricky. Add a final warning about violating best practices.
(svn.branchmerge.maint.lifetime): Tweak examples to use the sample
repos. Add an example of what to do if your WCs cwd is deleted
during an update. Use repos relative URLs. Use the term
'cherrypick' in place of 'port'.
(svn.branchmerge.commonpatterns.release): Use the term
'cherrypick' in place of 'port'.
(svn.branchmerge.commonpatterns.feature): Use the new "automatic"
merge terminology.
(svn.branchmerge.summary.tbl-1): Remove the deprecated --reintegrate
option from the summary table.
http://code.google.com/p/svnbook/source/detail?r=4453
Modified:
/trunk/en/book/ch04-branching-and-merging.xml
=======================================
--- /trunk/en/book/ch04-branching-and-merging.xml Mon Feb 25 17:10:55 2013
+++ /trunk/en/book/ch04-branching-and-merging.xml Tue Feb 26 15:23:29 2013
@@ -3034,7 +3034,7 @@
<para>Alas, this scenario doesn't work so well right now and
is considered one of Subversion's current weak spots. The
- problem is that Subversion's <command>svn update</command>
+ problem is that Subversion's <command>svn merge</command>
command isn't as robust as it should be, particularly when
dealing with copy and move operations.</para>
@@ -3045,59 +3045,132 @@
merge</command>. Instead of telling the client, <quote>Copy
that file you already have to this new location,</quote> it
sends down an entirely new file. This can lead to
- problems, especially because the same thing happens with
- renamed files. A lesser-known fact about Subversion is that
+ problems, particularly tree conflicts in the case of renames,
+ which involve not only the new copy, but a deletion of the old
+ path—a lesser-known fact about Subversion is that
it lacks <quote>true renames</quote>—the <command>svn
move</command> command is nothing more than an aggregation
of <command>svn copy</command> and <command>svn
delete</command>.</para>
- <para>For example, suppose that while working on your private
- branch, you rename <filename>integer.c</filename>
- to <filename>whole.c</filename>. Effectively you've created
- a new file in your branch that is a copy of the original
- file, and deleted the original file. Meanwhile, back
- on <filename>trunk</filename>, Sally has committed some
- improvements to <filename>integer.c</filename>. Now you
- decide to merge your branch to the trunk:</para>
+ <para>For example, suppose that you want to make some changes on
+ your private branch <filename>/calc/branch/my-calc-branch
+ </filename>. First you perform an automatic sync merge with
+ <filename>/calc/trunk</filename> and commit that in r470:</para>
<informalexample>
<screen>
$ cd calc/trunk
-$ svn merge --reintegrate ^/calc/branches/my-calc-branch
+$ svn merge ^/calc/trunk
--- Merging differences between repository URLs into '.':
-D integer.c
-A whole.c
-U .
+U doc/INSTALL
+A FAQ
+U src/main.c
+U src/button.c
+U src/integer.c
+U Makefile
+U README
+ U .
--- Recording mergeinfo for merge between repository URLs into '.':
U .
+
+$ svn ci -m "Sync all changes from ^/calc/trunk through r469."
+Sending .
+Sending Makefile
+Sending README
+Sending FAQ
+Sending doc/INSTALL
+Sending src/main.c
+Sending src/button.c
+Sending src/integer.c
+Transmitting file data ....
+Committed revision 470.
</screen>
</informalexample>
- <para>This doesn't look so bad at first glance, but it's also
- probably not what you or Sally expected. The merge operation
- has deleted the latest version of
- the <filename>integer.c</filename> file (the one containing
- Sally's latest changes), and blindly added your
- new <filename>whole.c</filename> file—which is a
- duplicate of the <emphasis>older</emphasis> version
- of <filename>integer.c</filename>. The net effect is that
- merging your <quote>rename</quote> to the trunk has removed
- Sally's recent changes from the latest revision!</para>
+ <para>Then you rename <filename>integer.c</filename> to <filename>
+ whole.c</filename> in r471 and then make some edits to the same
+ file in r473. Effectively you've created a new file in your branch
+ (that is a copy of the original file plus some edits) and deleted
+ the original file. Meanwhile, back on <filename>/calc/trunk
+ </filename>, Sally has committed some improvements of her own to
+ <filename>integer.c</filename> in r472:</para>
+
+ <informalexample>
+ <screen>
+$ svn log -v -r472 ^/calc/trunk
+------------------------------------------------------------------------
+r472 | sally | 2013-02-26 12:59:54 -0500 (Tue, 26 Feb 2013) | 1 line
+Changed paths:
+ M /calc/trunk/src/integer.c
+
+Trunk work on integer.c.
+------------------------------------------------------------------------
+</screen>
+ </informalexample>
+
+ <para>Now you decide to merge your branch back to the trunk.
+ How will Subversion combine the rename and edits you made
+ with Sally's edits?</para>
+
+ <informalexample>
+ <screen>
+$ svn merge ^/calc/branches/my-calc-branch
+--- Merging differences between repository URLs into '.':
+ C src/integer.c
+ U src/real.c
+A src/whole.c
+--- Recording mergeinfo for merge between repository URLs into '.':
+ U .
+Summary of conflicts:
+ Tree conflicts: 1
+
+$ svn st
+ M .
+ C src/integer.c
+ > local file edit, incoming file delete upon merge
+ M src/real.c
+A + src/whole.c
+Summary of conflicts:
+ Tree conflicts: 1
+</screen>
+ </informalexample>
+
+ <para>The answer is that Subversion <emphasis>won't</emphasis>
+ combine those changes, but rather raises a tree conflict<footnote>
+ <para>If Sally hadn't made her change in r472, then Subversion
would
+ notice that <filename>integer.c</filename> in the
+ target working copy is identical to <filename>integer.c</filename>
+ in the left-side of the merge and would allow your rename to
+ succeed without a tree conflict:</para>
+ <informalexample>
+ <screen>
+$ svn merge ^/calc/branches/my-calc-branch
+--- Merging differences between repository URLs into '.':
+ U src/real.c
+A src/whole.c
+D src/integer.c
+--- Recording mergeinfo for merge between repository URLs into '.':
+ U .
+</screen>
+ </informalexample></footnote>because it needs your help
+ to figure out what part of your changes and what part of Sally's
+ changes should ultimately end up in <filename>whole.c</filename>
+ or even if the rename should take place at all!</para>
- <para>This isn't true data loss. Sally's changes are still in
- the repository's history, but it may not be immediately
- obvious that this has happened. The moral of this story is
- that until Subversion improves, be very careful about
- merging copies and renames from one branch to
- another.</para>
+ <para>You will need to resolve this tree conflict before committing
+ the merge and this may require some manual intervention on your
+ part, see <xref linkend="svn.tour.treeconflicts"/>. The moral of
+ this story is that until Subversion improves, be careful about
+ merging copies and renames from one branch to another and when you
+ do, be prepared for some manual resolution.</para>
</sect2>
<!-- ===============================================================
-->
<sect2 id="svn.branchmerge.advanced.pre1.5clients">
- <title>Blocking Merge-Unaware Clients</title>
+ <title>Blocking Merge Tracking Unaware Clients</title>
<para>If you've just upgraded your server to Subversion 1.5 or
later, there's a risk that pre-1.5 Subversion
@@ -3166,17 +3239,15 @@
<title>The Final Word on Merge Tracking</title>
<para>The bottom line is that Subversion's merge-tracking
- feature has an extremely complex internal implementation, and
+ feature has an complex internal implementation, and
the <literal>svn:mergeinfo</literal> property is the only
window the user has into the machinery.</para>
- <para>Sometimes mergeinfo will appear on paths that you didn't
- expect to be touched by an operation. Sometimes mergeinfo
- won't be generated at all, when you expect it to.
- Furthermore, the management of mergeinfo metadata has a whole
- set of taxonomies and behaviors around it, such
- as <quote>explicit</quote> versus <quote>implicit</quote>
- mergeinfo, <quote>operative</quote>
+ <para>How and when mergeinfo is recorded by a merge can sometimes
+ be difficult to understand. Furthermore, the management of
+ mergeinfo metadata has a whole set of taxonomies and behaviors
+ around it, such as <quote>explicit</quote> versus <quote>implicit
+ </quote> mergeinfo, <quote>operative</quote>
versus <quote>inoperative</quote> revisions, specific
mechanisms of mergeinfo <quote>elision,</quote> and
even <quote>inheritance</quote> from parent to child
@@ -3184,10 +3255,10 @@
<para>We've chosen to only briefly cover, if at all, these detailed
topics for a couple of reasons. First, the level of detail is
- absolutely overwhelming for a typical user. Second, and more
- importantly, the typical user <emphasis>shouldn't</emphasis> have
- to understand these concepts; they should typically remain in the
- background as pesky implementation details. All that said, if you
+ overwhelming for a typical user. Second, and more
+ importantly, the typical user <emphasis>doesn't</emphasis> need
+ to understand these concepts; typically they remain in the
+ background as implementation details. All that said, if you
enjoy this sort of thing, you can get a fantastic overview in a
paper posted at CollabNet's website: <ulink
url="http://www.open.collab.net/community/subversion/articles/merge-info.html"
@@ -3224,8 +3295,9 @@
repository at a single point in time:
<itemizedlist>
<listitem>
- <para>Don't use the
<option>--allow-mixed-revisions</option>
- option to merge into mixed-revision working copies.</para>
+ <para>Update before you merge! Don't use the <option>
+ --allow-mixed-revisions</option> option to merge into
+ mixed-revision working copies.</para>
</listitem>
<listitem>
<para>Don't merge to targets with <quote>switched</quote>
@@ -3247,6 +3319,10 @@
</listitem>
</itemizedlist>
+ <para>Of course sometimes you may need to violate some of these
+ best practices. Don't worry if you need to, just be sure you
+ understand the ramifications of doing so.</para>
+
</sect2>
</sect1>
@@ -3693,10 +3769,37 @@
$ svn delete http://svn.example.com/repos/calc/branches/my-calc-branch \
-m "Removing obsolete branch of calc project."
-Committed revision 375.
+Committed revision 474.
</screen>
</informalexample>
+ <tip>
+ <para>Recall from the previous section that if the repository
+ location your working copy refers to is deleted, then when
+ you try to update you will receive an error:</para>
+ <informalexample>
+ <screen>
+$ svn up
+Updating '.':
+svn: E160005: Target path '/calc/branches/my-calc-branch' does not exist
+</screen>
+ </informalexample>
+
+ <para>All you need to do in this situation is switch your working
+ copy to a location that still exits:</para>
+
+ <informalexample>
+ <screen>
+$ svn sw ^/calc/trunk
+D src/whole.c
+ U src/real.c
+A src/integer.c
+ U .
+Updated to revision 474.
+</screen>
+ </informalexample>
+ </tip>
+
<para>And now your branch is gone. Of course, it's not really
gone: the directory is simply missing from the
<literal>HEAD</literal> revision, no longer distracting
@@ -3714,11 +3817,11 @@
<informalexample>
<screen>
-$ svn copy http://svn.example.com/repos/calc/branches/my-calc-branch@374 \
- http://svn.example.com/repos/calc/branches/my-calc-branch \
+$ svn copy ^/calc/branches/my-calc-branch at 473 \
+ ^/calc/branches/my-calc-branch \
-m "Restore my-calc-branch."
-Committed revision 376.
+Committed revision 475.
</screen>
</informalexample>
@@ -3738,11 +3841,10 @@
<informalexample>
<screen>
-$ svn copy http://svn.example.com/repos/calc/trunk \
- http://svn.example.com/repos/calc/branches/stable-1.0 \
+$ svn copy ^/calc/trunk ^/calc/branches/stable-1.0 \
-m "Creating stable branch of calc project."
-Committed revision 377.
+Committed revision 476.
</screen>
</informalexample>
@@ -3752,7 +3854,7 @@
project policy that only bug fixes are to be committed to
<filename>/calc/branches/stable-1.0</filename>. That is, as
people continue to work on the trunk, a human selectively
- ports bug fixes over to the stable branch. Even after the
+ cherrypicks bug fixes over to the stable branch. Even after the
stable branch has shipped, you'll probably continue to
maintain the branch for a long time—that is, as long
as you continue to support that release for customers. We'll
@@ -3823,7 +3925,7 @@
parallel.</emphasis> One team begins rigorous testing of
the release branch, while another team continues new work
(say, for version 2.0) on <filename>/trunk</filename>. If
- bugs are discovered in either location, fixes are ported
+ bugs are discovered in either location, fixes are cherrypicked
back and forth as necessary. At some point, however, even
that process stops. The branch is <quote>frozen</quote>
for final testing right before a release.</para>
@@ -3915,17 +4017,18 @@
development differ so greatly that it may become a nightmare
trying to merge the branch back to the trunk.</para>
- <para>This situation is best avoided by regularly merging trunk
- changes to the branch. Make up a policy: once a week, merge
- the last week's worth of trunk changes to the branch.</para>
+ <para>This situation is best avoided by regularly running an
+ automatic merge from trunk to the branch. Make up a policy:
+ once a week, merge the last week's worth of trunk changes to
+ the branch.</para>
<para>When you are eventually ready to merge the
<quote>synchronized</quote> feature branch back to the trunk,
- begin by doing a final merge of the latest trunk
+ begin by doing a final automatic merge of the latest trunk
changes to the branch. When that's done, the latest versions
of branch and trunk are absolutely identical except for
- your branch changes. You then merge back with
- the <option>--reintegrate</option> option:</para>
+ your branch changes. You can then run an automatic reintegrate
+ merge from the branch back to the trunk:</para>
<informalexample>
<screen>
@@ -3935,7 +4038,7 @@
Updating '.':
At revision 1910.
-$ svn merge --reintegrate ^/calc/branches/mybranch
+$ svn merge ^/calc/branches/mybranch
--- Merging differences between repository URLs into '.':
U real.c
U integer.c
@@ -4732,7 +4835,7 @@
<row>
<entry>Merge a branch back into trunk</entry>
- <entry><userinput>svn merge --reintegrate
<replaceable>branchURL</replaceable>; svn commit</userinput></entry>
+ <entry><userinput>svn merge
<replaceable>branchURL</replaceable>; svn commit</userinput></entry>
</row>
<row>
More information about the svnbook-dev
mailing list