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

sussman svnbook-dev at red-bean.com
Mon Jul 11 16:20:12 CDT 2005


Author: sussman
Date: Mon Jul 11 16:20:10 2005
New Revision: 1539

Modified:
   trunk/src/en/book/ch02.xml
Log:
* src/en/book/ch02.xml:  new section explaining mixed-revs working copies.

Modified: trunk/src/en/book/ch02.xml
==============================================================================
--- trunk/src/en/book/ch02.xml	(original)
+++ trunk/src/en/book/ch02.xml	Mon Jul 11 16:20:10 2005
@@ -684,49 +684,135 @@
     
     <!-- =============================================================== -->
     <sect2 id="svn.basic.in-action.mixedrevs">
-      <title>The Limitations of Mixed Revisions</title>
+      <title>Mixed Revision Working Copies</title>
 
       <para>As a general principle, Subversion tries to be as flexible
         as possible.  One special kind of flexibility is the ability
-        to have a working copy containing mixed revision
-        numbers.</para>
+        to have a working copy containing files and directories with a
+        mix of different working revision numbers.  Unfortunately,
+        this flexibility tends to confuse a number of new users.  If
+        the earlier example showing mixed revisions perplexed you,
+        here's a primer on both why the feature exists and how to make
+        use of it.</para>
+
+      <sect3 id="svn.basic.in-action.mixedrevs.update-commit">
+        <title>Updates and Commits are Separate</title>
+
+        <para>One of the fundamental rules of Subversion is that
+          a <quote>push</quote> action does not cause
+          a <quote>pull</quote>, nor the other way around.  Just
+          because you're ready to submit new changes to the repository
+          doesn't mean you're ready to receive changes from other
+          people.  And if you have new changes still in progress,
+          then <command>svn update</command> should gracefully merge
+          repository changes into your own, rather than forcing you to
+          publish them.</para>
+
+        <para>The main side-effect of this rule is that it means a
+          working copy has to do extra bookkeeping to track mixed
+          revisions, and be tolerant of the mixture as well.  It's
+          made more complicated by the fact that directories
+          themselves are versioned.</para>
+
+        <para>For example, suppose you have a working copy entirely at
+          revision 10.  You edit the
+          file <filename>foo.html</filename> and then perform
+          an <command>svn commit</command>, which creates revision 15
+          in the repository.  After the commit succeeds, many new
+          users would expect the working copy to be entirely at
+          revision 15, but that's not the case!  Any number of changes
+          might have happened in the repository between revisions 10
+          and 15.  It would be a lie to claim that we had a working
+          copy of revision 15, the client simply doesn't know.  If, on
+          the other hand, <command>svn commit</command> were to
+          automatically download the newest changes, then it would be
+          possible to set the entire working copy to revision
+          15—but then we'd be breaking the fundamental rule
+          of <quote>push</quote> and <quote>pull</quote> remaining
+          separate actions.  Therefore the only safe thing the
+          Subversion client can do is mark the one
+          file—<filename>foo.html</filename>—as being at
+          revision 15.  The rest of the working copy remains at
+          revision 10.  Only by running <command>svn update</command>
+          can the latest changes be downloaded, and the whole working
+          copy be marked as revision 15.</para>
+
+        </sect3>
+
+        <sect3 id="svn.basic.in-action.mixedrevs.normal">
+          <title>Mixed revisions are normal</title>
+          
+          <para>The fact is, <emphasis>every time</emphasis> you
+            run <command>svn commit</command>, your working copy ends
+            up with some mixture of revisions.  The things you just
+            committed are marked as having larger working revisions
+            than everything else.  After several commits (with no
+            updates in-between) your working copy will contain a whole
+            mixture of revisions.  Even if you're the only person
+            using the repository, you will still see this phenomenon.
+            To examine your mixture of working revisions, use
+            the <command>svn status --verbose</command> command (see
+            <xref linkend="svn.tour.cycle.examine.status"/> for more
+            information.)</para>
+
+          <para>Often, new users are completely unaware that their
+            working copy contains mixed revisions.  This can be
+            confusing, because many client commands are sensitive to
+            the working revision of the item they're examining.  For
+            example, the <command>svn log</command> command is used to
+            display the history of changes to a file or directory (see
+            <xref linkend="svn.tour.history.log"/>).  When the user
+            invokes this command on a working copy object, they expect
+            to see the entire history of the object.  But if the
+            object's working revision is quite old (often
+            because <command>svn update</command> hasn't been run in a
+            long time), then the history of
+            the <emphasis>older</emphasis> version of the object is
+            shown.</para>
+        </sect3>
+
+        <sect3 id="svn.basic.in-action.mixedrevs.useful">
+          <title>Mixed revisions are useful</title>
+
+          <para>If your project is sufficiently complex, you'll
+            discover that it's sometimes nice to forcibly
+            <quote>backdate</quote> portions of your working copy to
+            an earlier revision; you'll learn how to do that in
+            Chapter 3.  Perhaps you'd like to test an earlier version
+            of a sub-module contained in a subdirectory, or perhaps
+            you'd like to figure out when a bug first came into
+            existence in a specific file.  This is the <quote>time
+            machine</quote> aspect of a version control system —
+            the feature which allows you to move any portion of your
+            working copy forward and backward in history.</para>
+
+        </sect3>
+
+        <sect3 id="svn.basic.in-action.mixedrevs.limits">
+          <title>Mixed revisions have limitations</title>
+
+          <para>However you make use of mixed revisions in your
+            working copy, there are limitations to this
+            flexibility.</para>
+          
+          <para>First, you cannot commit the deletion of a file or
+            directory which isn't fully up-to-date.  If a newer
+            version of the item exists in the repository, your attempt
+            to delete will be rejected, to prevent you from
+            accidentally destroying changes you've not yet
+            seen.</para>
+
+          <para>Second, you cannot commit a metadata change to a
+            directory unless it's fully up-to-date.  You'll learn
+            about attaching
+            <quote>properties</quote> to items in Chapter 6.  A
+            directory's working revision defines a specific set of
+            entries and properties, and thus committing a property
+            change to an out-of-date directory may destroy properties
+            you've not yet seen.</para>
+
+        </sect3>
 
-      <para>At first, it may not be entirely clear why this sort of
-        flexibility is considered a feature, and not a liability.
-        After completing a commit to the repository, the freshly
-        committed files and directories are at a more recent working
-        revision than the rest of the working copy.  It looks like a
-        bit of a mess.  As demonstrated earlier, the working copy can
-        always be brought to a single working revision by running
-        <command>svn update</command>.  Why would someone
-        <emphasis>deliberately</emphasis> want a mixture of working
-        revisions?</para>
-
-      <para>Assuming your project is sufficiently complex, you'll
-        discover that it's sometimes nice to forcibly
-        <quote>backdate</quote> portions of your working copy to an
-        earlier revision; you'll learn how to do that in Chapter 3.
-        Perhaps you'd like to test an earlier version of a sub-module,
-        contained in a subdirectory, or perhaps you'd like to examine
-        a number of previous versions of a file in the context of the
-        latest tree.</para>
-        
-      <para>However you make use of mixed-revisions in your working
-        copy, there are limitations to this flexibility.</para>
-
-      <para>First, you cannot commit the deletion of a file or
-        directory which isn't fully up-to-date.  If a newer version of
-        the item exists in the repository, your attempt to delete will
-        be rejected, to prevent you from accidentally
-        destroying changes you've not yet seen.</para>
-
-      <para>Second, you cannot commit a metadata change to a directory
-        unless it's fully up-to-date.  You'll learn about attaching
-        <quote>properties</quote> to items in Chapter 6.  A
-        directory's working revision defines a specific set of entries
-        and properties, and thus committing a property change to an
-        out-of-date directory may destroy properties you've not yet
-        seen.</para>
 
     </sect2>
 



More information about the svnbook-dev mailing list