[svnbook commit] r2658 - trunk/src/en/book

sussman noreply at red-bean.com
Tue Feb 6 00:34:47 CST 2007


Author: sussman
Date: Tue Feb  6 00:34:47 2007
New Revision: 2658

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

Log:
A number of improvements to chapter 4.

* src/en/book/ch-branching-and-merging.xml:

     - a bunch of misc cleanups/rewordings
     - don't mention CVS attic junk
     - don't mention the specific command 'svn obliterate', keep it vague
     - mention pegrev syntax where we can
     - don't talk about svn 1.0, that's so 2004.
     - add new section warning about problems with merging moves/copies





Modified: trunk/src/en/book/ch-branching-and-merging.xml
==============================================================================
--- trunk/src/en/book/ch-branching-and-merging.xml	(original)
+++ trunk/src/en/book/ch-branching-and-merging.xml	Tue Feb  6 00:34:47 2007
@@ -18,7 +18,7 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <sect1 id="svn.branchmerge.whatis">
-    <title>What's a Branch?</title> 
+    <title>What's a Branch?</title>
 
     <para>Suppose it's your job to maintain a document for a division
       in your company, a handbook of some sort.  One day a different
@@ -793,12 +793,13 @@
           this information to help automate merges as much as
           possible.</para>
 
-        <para>Unfortunately, Subversion is not such a system.  Like
-          CVS, Subversion does not yet record any information about
-          merge operations.  When you commit local modifications, the
-          repository has no idea whether those changes came from
-          running <command>svn merge</command>, or from just
-          hand-editing the files.</para>
+        <para>Unfortunately, Subversion is not such a system; it does
+          not yet record any information about merge operations.
+            <footnote><para>However, at the time of writing, this
+             feature is being worked on!</para></footnote>
+          When you commit local modifications, the repository has no
+          idea whether those changes came from running <command>svn
+          merge</command>, or from just hand-editing the files.</para>
 
         <para>What does this mean to you, the user?  It means that
           until the day Subversion grows this feature, you'll have to
@@ -1013,6 +1014,73 @@
 
       </sect3>
 
+      <sect3 id="svn.branchmerge.copychanges.bestprac.moves">
+        <title>Merges and Moves</title>
+
+        <para>A common desire is to <quote>refactor</quote> source
+          code, especially in Java-based software projects.  Files and
+          directories are shuffled around and renamed, often causing
+          great disruption to everyone working on the project.  Sounds
+          like a perfect case to use a branch, doesn't it?  Just
+          create a branch, shuffle things around, then merge the
+          branch back to the trunk, right?</para>
+
+        <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>move</command>
+          and <command>copy</command> commands aren't as robust as
+          they should be.</para>
+
+        <para>When you use <command>svn copy</command> to duplicate a
+          file, the repository remembers where the new file came from,
+          but it fails to transmit that information to the client
+          which is running <command>svn update</command>
+          or <command>svn merge</command>.  Instead of telling the
+          client, <quote>Copy that file you have over there to this
+          new location</quote>, it instead just 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 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>
+
+        <screen>
+$ cd calc/trunk
+
+$ svn merge -r 341:405 http://svn.example.com/repos/calc/branches/my-calc-branch
+D   integer.c
+A   whole.c
+</screen>
+
+        <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 <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 branch has removed
+          Sally's recent changes from the latest revision!</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.  Moral of the story: until
+          Subversion improves, be very careful about merging copies
+          and renames from one branch to another.</para>
+
+      </sect3>
+
     </sect2>
 
 
@@ -1265,7 +1333,7 @@
           <quote>this issue was fixed by revision 9238.</quote>.
           Somebody can then run <command>svn log -r9238</command> to
           read about the exact changeset which fixed the bug, and run
-          <command>svn diff -r9237:9238</command> to see the patch
+          <command>svn diff -c 9238</command> to see the patch
           itself.  And Subversion's <literal>merge</literal> command
           also uses revision numbers.  You can merge specific changesets
           from one branch to another by naming them in the merge
@@ -1305,11 +1373,10 @@
         possibly invalidating all working copies.
         <footnote>
           <para>The Subversion project has plans, however, to someday
-            implement an <command>svnadmin obliterate</command>
-            command that would accomplish the task of permanently
-            deleting information.  In the meantime, see <xref
-            linkend="svn.reposadmin.maint.tk.svndumpfilter"/> for a possible
-            workaround.</para>
+            implement a command that would accomplish the task of
+            permanently deleting information.  In the meantime, see
+            <xref linkend="svn.reposadmin.maint.tk.svndumpfilter"/>
+            for a possible workaround.</para>
         </footnote>
       </para>
 
@@ -1326,25 +1393,21 @@
         One of the most common questions new users ask is, <quote>How
         do I get my old file or directory back?</quote>.</para>
 
-      <para>The first step is to define exactly <emphasis
-        role="bold">which</emphasis> item you're trying to resurrect.
-        Here's a useful metaphor: you can think of every object in the
-        repository as existing in a sort of two-dimensional coordinate
-        system.  The first coordinate is a particular revision tree,
-        and the second coordinate is a path within that tree.  So
-        every version of your file or directory can be defined by a
-        specific coordinate pair.</para>
-
-      <para>Subversion has no <filename>Attic</filename> directory
-        like CVS does,
-        <footnote>
-          <para>Because CVS doesn't version trees, it creates an
-            <filename>Attic</filename> area within each repository
-            directory as a way of remembering deleted files.</para>
-        </footnote>
-        so you need to use <command>svn
-        log</command> to discover the exact coordinate pair you wish
-        to resurrect.  A good strategy is to run <command>svn log
+      <para>The first step is to define
+        exactly <emphasis role="bold">which</emphasis> item you're
+        trying to resurrect.  Here's a useful metaphor: you can think
+        of every object in the repository as existing in a sort of
+        two-dimensional coordinate system.  The first coordinate is a
+        particular revision tree, and the second coordinate is a path
+        within that tree.  So every version of your file or directory
+        can be defined by a specific coordinate pair.  (Remember the
+        familiar <quote>peg revision</quote> syntax — foo.c at 224
+        — mentioned back in
+        <xref linkend="svn.advanced.pegrevs"/>.) </para>
+
+      <para>First, you might need to use <command>svn log</command> to
+        discover the exact coordinate pair you wish to resurrect.  A
+        good strategy is to run <command>svn log
         --verbose</command> in a directory which used to contain your
         deleted item.  The <option>--verbose</option> option shows a
         list of all changed items in each revision; all you need to do
@@ -1732,8 +1795,9 @@
       mixture of repository locations, these locations must all be
       within the <emphasis>same</emphasis> repository.  Subversion
       repositories aren't yet able to communicate with one another;
-      that's a feature planned beyond Subversion
-      1.0.<footnote><para>You <emphasis>can</emphasis>, however, use
+      that's a feature planned for the
+      future.<footnote><para>You <emphasis>can</emphasis>, however,
+      use
       <command>svn switch</command> with the
       <option>--relocate</option> switch if the URL of your server
       changes and you don't want to abandon an existing working copy.




More information about the svnbook-dev mailing list