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

sussman svnbook-dev at red-bean.com
Tue Apr 11 17:49:29 CDT 2006


Author: sussman
Date: Tue Apr 11 17:49:29 2006
New Revision: 2121

Modified:
   trunk/src/en/book/appb.xml
   trunk/src/en/book/ch03.xml
   trunk/src/en/book/ch05.xml
   trunk/src/en/book/ch06.xml
   trunk/src/en/book/ch07.xml
   trunk/src/en/book/ch09.xml

Log:
A number of patches and changes for the 1.2 svnbook, taken from Trac.


* ch03.xml:  Small clarifications regarding 'working copy locks'.
             Patch from Gareth McCaughan <gareth.mccaughan at pobox.com>,
             slightly tweaked in places by me.  Part of ticket #5.

* ch05.xml:  Small clarifications regarding 'bdb locks'.
             Patch from Gareth McCaughan <gareth.mccaughan at pobox.com>,
             slightly tweaked in places by me.  Part of ticket #5.

* ch07.xml:  New sidebar explaining three types of "locks".
             Patch from Gareth McCaughan <gareth.mccaughan at pobox.com>,
             slightly tweaked in places by me.  Part of ticket #5.

* ch06.xml:  Clarify behavior of win32 password-caching encryption.
             Based on a discussion with Jack Repenning, covering part
             of ticket #1.

* ch09.xml:  Better explanation of 'R' status code.
             Patch from Eric Hanchrow <offby1 at blarg.net>.
             Completes ticket #4.

             Clarify which sort of "locks" are being referred to.
             Patch from Gareth McCaughan <gareth.mccaughan at pobox.com>,
             slightly tweaked in places by me.  Part of ticket #5.

* appb.xml:  Note the latest Microsoft bugfix release of XP WebFolders.
             Completes ticket #6.



Modified: trunk/src/en/book/appb.xml
==============================================================================
--- trunk/src/en/book/appb.xml	(original)
+++ trunk/src/en/book/appb.xml	Tue Apr 11 17:49:29 2006
@@ -667,6 +667,15 @@
           client for Windows XP, then use a third-party program like
           WebDrive or NetDrive.</para>
 
+        <para>A final tip: if you're attempting to use XP Web Folders,
+          make sure you have the absolute latest version from
+          Microsoft.  For example, Microsoft released a bug-fixed
+          version in January 2005, available at
+          <ulink url="http://support.microsoft.com/?kbid=892211"/>.
+          In particular, this release is known to fix a bug whereby
+          browsing a DAV share shows an unexpected infinite
+          recursion.</para>
+
       </sect3>
 
       <sect3 id="svn.webdav.clients.file-explorer-extensions.linux-de">

Modified: trunk/src/en/book/ch03.xml
==============================================================================
--- trunk/src/en/book/ch03.xml	(original)
+++ trunk/src/en/book/ch03.xml	Tue Apr 11 17:49:29 2006
@@ -1067,8 +1067,10 @@
           switch</command>) to a branch.</para>
 
         <para>The sixth column shows information about locks, which is
-          further explained in <xref
-          linkend="svn.advanced.locking"/>.</para>
+          further explained in <xref linkend="svn.advanced.locking"/>.
+          (These are not the same locks as the ones indicated by an
+          <computeroutput>L</computeroutput> in the third column;
+          see <xref linkend="svn.advanced.locking.meanings"/>.)</para>
         
         <para>If you pass a specific path to <command>svn
           status</command>, it gives you information about that item
@@ -2155,11 +2157,14 @@
       <para>When Subversion modifies your working copy (or any
         information within <filename>.svn</filename>), it tries to do
         so as safely as possible.  Before changing the working copy,
-        Subversion writes its intentions to a log file.  Next it executes
-        the commands in the log file to apply the requested change.
-        Finally, Subversion removes the log file.  Architecturally, this
-        is similar to a journaled filesystem.  If a Subversion operation is
-        interrupted (if the process is killed, or if the machine
+        Subversion writes its intentions to a log file.  Next it
+        executes the commands in the log file to apply the requested
+        change, holding a lock on the relevant part of the working
+        copy while it works — to prevent othe Subversion clients
+        from accessing the working copy in mid-change.  Finally,
+        Subversion removes the log file.  Architecturally, this is
+        similar to a journaled filesystem.  If a Subversion operation
+        is interrupted (if the process is killed, or if the machine
         crashes, for example), the log files remain on disk.  By
         re-executing the log files, Subversion can complete the
         previously started operation, and your working copy can get
@@ -2167,9 +2172,9 @@
 
       <para>And this is exactly what <command>svn cleanup</command>
         does: it searches your working copy and runs any leftover
-        logs, removing locks in the process.  If Subversion ever tells
-        you that some part of your working copy is
-        <quote>locked</quote>, then this is the command that you
+        logs, removing working copy locks in the process.
+        If Subversion ever tells you that some part of your working copy
+        is <quote>locked</quote>, then this is the command that you
         should run.  Also, <command>svn status</command> will display
         an <literal>L</literal> next to locked items:</para>
 
@@ -2183,6 +2188,13 @@
 M      somedir/foo.c
 </screen>
 
+      <para>Don't confuse these working copy locks with the ordinary
+        locks that Subversion users create when using
+        the <quote>lock-modify-unlock</quote> model of concurrent
+        version control; see
+        <xref linkend="svn.advanced.locking.meanings"/> for
+        clarification.</para>
+
     </sect2>
 
 

Modified: trunk/src/en/book/ch05.xml
==============================================================================
--- trunk/src/en/book/ch05.xml	(original)
+++ trunk/src/en/book/ch05.xml	Tue Apr 11 17:49:29 2006
@@ -902,7 +902,7 @@
       <para>A Berkeley DB environment is an encapsulation of one or
         more databases, log files, region files and configuration
         files.  The Berkeley DB environment has its own set of default
-        configuration values for things like the number of locks
+        configuration values for things like the number of database locks
         allowed to be taken out at any given time, or the maximum size
         of the journaling log files, etc.  Subversion's filesystem
         code additionally chooses default values for some of the
@@ -2070,7 +2070,11 @@
         data, makes the change it wants to make, and then unlocks the
         data.  Other processes are forced to wait until that lock is
         removed before they are permitted to continue accessing that
-        section of the database.</para>
+        section of the database. (This has nothing to do with the
+        locks that you, as a user, can apply to versioned files within
+        the repository; see
+        <xref linkend="svn.advanced.locking.meanings"/> for more
+        information.)</para>
 
       <para>In the course of using your Subversion repository, fatal
         errors (such as running out of disk space or available memory)

Modified: trunk/src/en/book/ch06.xml
==============================================================================
--- trunk/src/en/book/ch06.xml	(original)
+++ trunk/src/en/book/ch06.xml	Tue Apr 11 17:49:29 2006
@@ -215,8 +215,9 @@
       <para>Happily, the Subversion client has a remedy for this: a
         built-in system for caching authentication credentials on
         disk.  By default, whenever the command-line client
-        successfully authenticates itself to a server, it saves the
-        credentials in the user's private runtime configuration
+        successfully responds to a server's authentication challenge,
+        it saves the credentials in the user's private runtime
+        configuration
         area—in <filename>~/.subversion/auth/</filename> on
         Unix-like systems or
         <filename>%APPDATA%/Subversion/auth/</filename> on Windows.
@@ -226,8 +227,8 @@
         authentication realm.</para>  
 
       <para>When the client receives an authentication challenge, it
-        first looks for the appropriate credentials in the disk cache;
-        if not present, or if the cached credentials fail to
+        first looks for the appropriate credentials in the user's disk
+        cache; if not present, or if the cached credentials fail to
         authenticate, then the client simply prompts the user for the
         information.</para>
 
@@ -252,10 +253,10 @@
             password on disk.  Because the encryption key is managed
             by Windows and is tied to the user's own login
             credentials, only the user can decrypt the cached
-            password.  (Note: if the user's Windows account
-            password is changed, all of the cached passwords become
-            undecipherable.  The Subversion client will behave as if
-            they don't exist, prompting for passwords when
+            password.  (Note: if the user's Windows account password
+            is reset by an administrator, all of the cached passwords
+            become undecipherable.  The Subversion client will behave
+            as if they don't exist, prompting for passwords when
             required.)</para>
         </listitem>
 

Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml	(original)
+++ trunk/src/en/book/ch07.xml	Tue Apr 11 17:49:29 2006
@@ -1929,6 +1929,46 @@
       only—it's not yet possible to reserve access to a whole
       directory tree.</para>
 
+    <sidebar id="svn.advanced.locking.meanings">
+      <title>Three meanings of <quote>lock</quote></title>
+
+      <para>In this section, and almost everywhere in this book, the
+        words <quote>lock</quote> and <quote>locking</quote> describe
+        a mechanism for mutual exclusion between users to avoid
+        clashing commits. Unfortunately, there are two other sorts
+        of <quote>lock</quote> with which Subversion, and therefore
+        this book, sometimes needs to be concerned.</para>
+
+      <itemizedlist>
+
+        <listitem><para><firstterm>Working copy locks</firstterm>,
+          used internally by Subversion to prevent clashes between
+          multiple Subversion clients operating on the same working
+          copy. This is the sort of lock indicated by
+          an <computeroutput>L</computeroutput> in the third column
+          of <command>svn status</command> output, and removed by
+          the <command>svn cleanup</command> command, as described in
+          <xref linkend="svn.tour.other.cleanup"/>.</para>
+        </listitem>
+
+        <listitem><para><firstterm>Database locks</firstterm>, used
+          internally by the Berkeley DB backend to prevent clashes
+          between multiple programs trying to access the
+          database. This is the sort of lock whose unwanted
+          persistence after an error can cause a repository to
+          be <quote>wedged</quote>, as described in
+          <xref linkend="svn.reposadmin.maint.recovery"/>.</para>
+        </listitem>
+
+      </itemizedlist>
+
+      <para>You can generally forget about these other sorts of lock,
+        until something goes wrong that requires you to care about
+        them. In this book, <quote>lock</quote> means the first sort
+        unless the contrary is either clear from context or explicitly
+        stated.</para>
+    </sidebar>
+
     <!-- =============================================================== -->
     <sect2 id="svn.advanced.locking.creation">
       <title>Creating locks</title>

Modified: trunk/src/en/book/ch09.xml
==============================================================================
--- trunk/src/en/book/ch09.xml	(original)
+++ trunk/src/en/book/ch09.xml	Tue Apr 11 17:49:29 2006
@@ -910,9 +910,9 @@
           <title>Description</title>
 
           <para>Recursively clean up the working copy, removing
-            locks resuming unfinished operations.  If you ever get a
-            <quote>working copy locked</quote> error, run this
-            command to remove stale locks and get your working copy
+            working copy locks and resuming unfinished operations.
+            If you ever get a <quote>working copy locked</quote> error,
+            run this command to remove stale locks and get your working copy
             into a usable state again.</para>
 
           <para>If, for some reason, an <command>svn update</command>
@@ -3397,7 +3397,10 @@
             <varlistentry>
               <term>'R'</term>
               <listitem>
-                <para>Item has been replaced in your working copy.</para>
+                <para>Item has been replaced in your working copy.
+                This means the file was scheduled for deletion, and
+                then a new file with the same name was scheduled for
+                addition in its place.</para>
               </listitem>
             </varlistentry>
 
@@ -3485,7 +3488,8 @@
           </variablelist>
 
           <para>The third column is populated only if the
-            working copy directory is locked.</para>
+            working copy directory is locked. (See
+            <xref linkend="svn.tour.other.cleanup"/>.)</para>
 
           <variablelist>
             
@@ -3992,7 +3996,9 @@
             synchronizes the working copy to the revision given by the
             <option>--revision</option> switch.  As part of the
             synchronization, <command>svn update</command> also
-            removes any stale locks found in the working copy.</para>
+            removes any stale locks (see <xref
+            linkend="svn.tour.other.cleanup"/>) found in the
+            working copy.</para>
 
           <para>For each updated item a line will start with a
             character reporting the action taken.  These characters
@@ -4748,9 +4754,10 @@
 </screen>
 
           <para>Recovering the database requires an exclusive lock on
-            the repository.  If another process is accessing the
-            repository, then <command>svnadmin recover</command> will
-            error:</para>
+            the repository. (This is a <quote>database lock</quote>;
+            see <xref linkend="svn.advanced.locking.meanings"/>.)
+            If another process is accessing the repository,
+            then <command>svnadmin recover</command> will error:</para>
           <screen>
 $ svnadmin recover /usr/local/svn/repos
 svn: Failed to get exclusive repository access; perhaps another process




More information about the svnbook-dev mailing list