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

sussman svnbook-dev at red-bean.com
Thu Jun 2 13:11:08 CDT 2005


Author: sussman
Date: Thu Jun  2 13:11:07 2005
New Revision: 1396

Modified:
   trunk/src/en/book/appc.xml
   trunk/src/en/book/ch02.xml
   trunk/src/en/book/ch03.xml
   trunk/src/en/book/ch05.xml
   trunk/src/en/book/ch07.xml
Log:
A bunch of changes related to locking. 
(Also, a few extra cleanups that I notice along the way.)

I've started work on the new chapter 7 section, which will be a more
conversational expansion of the 'locking' section of the svn 1.2
releasenotes.  The changes below are all the "other" places in the
book that needed locking updates -- excluding chapter 9.

* src/en/book/ch02.xml 
  (When Locking is Necessary): new sidebar in 'versioning models'
       section which explains that locking is occasionally necessary.

* src/en/book/ch03.xml
  (Examine your changes):  tweak 'svn status' chart to show new KOBT
       codes, also clarify a couple of existing code descriptions.
  (svn import):  add a -m flag to the example for accuracy.

* src/en/book/appc.xml 
  (Autoversioning): Style cleanup; change wording of 1st paragraph not
      to depend on the previous section.

* src/en/book/ch05.xml 
  (svnlook):   add 'svnlook lock' entry to table.
  (svnadmin):  add 'svnadmin lslocks/rmlocks' entries to table.
  (Repository Creation and Configuration):  FSFS is now the default back-end.

* src/en/book/ch07.xml 
  (svn:needs-lock):  describe in the 'special properties' section.


Modified: trunk/src/en/book/appc.xml
==============================================================================
--- trunk/src/en/book/appc.xml	(original)
+++ trunk/src/en/book/appc.xml	Thu Jun  2 13:11:07 2005
@@ -305,10 +305,10 @@
   <sect1 id="svn.webdav.autoversioning">
     <title>Autoversioning </title>
 
-    <para>All is not lost.  There's still a bright gleam of
-      interoperability around this cloud, one which justifies
-      Subversion's original adoption of WebDAV: it's called
-      autoversioning.</para>
+    <para>While the Subversion client is not a full DeltaV client, nor
+      the Subversion server a full DeltaV server, there's still a
+      glimmer of WebDAV interoperability to be happy about:  it's
+      called autoversioning.</para>
 
     <para>Autoversioning is an optional feature defined in the DeltaV
       standard.  A typical DeltaV server will reject an ignorant

Modified: trunk/src/en/book/ch02.xml
==============================================================================
--- trunk/src/en/book/ch02.xml	(original)
+++ trunk/src/en/book/ch02.xml	Thu Jun  2 13:11:07 2005
@@ -242,6 +242,32 @@
         in practice, locking seems to inhibit productivity more than
         anything else.</para>
       
+      <sidebar id="svn.basic.vsn-models.copy-merge.sb-1">
+        <title>When Locking is Necessary</title>
+        
+        <para>While the lock-modify-unlock model is considered
+          generally harmful to collaboration, there are still times
+          when locking is appropriate.</para>
+
+        <para>The copy-modify-merge model is based on the assumption
+          that files are contextually mergeable: that is, that the
+          majority of the files in the repository are line-based text
+          files (such as program source code.)  But for files with
+          binary formats, such as artwork or sound, it's often
+          impossible to merge conflicting changes.  In these
+          situations, it really is necessary to users to take strict
+          turns when changing the file.  Without serialized access,
+          somebody ends up wasting their time on changes that are
+          ultimately discarded.</para>
+
+        <para>While CVS and Subversion are still primarily
+          copy-modify-merge systems, they both recognize the need to
+          lock an occasional file and provide mechanisms for this.
+          See <xref linkend="svn.advanced.locking"/>.</para>
+
+      </sidebar>
+
+
     </sect2>
     
   </sect1>

Modified: trunk/src/en/book/ch03.xml
==============================================================================
--- trunk/src/en/book/ch03.xml	(original)
+++ trunk/src/en/book/ch03.xml	Thu Jun  2 13:11:07 2005
@@ -808,22 +808,27 @@
           actually printed by <command>svn status</command>.)</para>
       
         <screen>
-  L    abc.c               # svn has a lock in its .svn directory for abc.c
-M      bar.c               # the content in bar.c has local modifications
- M     baz.c               # baz.c has property but no content modifications
-X      3rd_party           # this dir is part of an externals definition
-?      foo.o               # svn doesn't manage foo.o
-!      some_dir            # svn manages this, but it's either missing or incomplete
-~      qux                 # versioned as file/dir/link, but type has changed
-I      .screenrc           # svn doesn't manage this, and is configured to ignore it
-A  +   moved_dir           # added with history of where it came from
-M  +   moved_dir/README    # added with history and has local modifications
-D      stuff/fish.c        # this file is scheduled for deletion
-A      stuff/loot/bloo.h   # this file is scheduled for addition
-C      stuff/loot/lump.c   # this file has textual conflicts from an update
- C     stuff/loot/glub.c   # this file has property conflicts from an update
-R      xyz.c               # this file is scheduled for replacement
-    S  stuff/squawk        # this file or dir has been switched to a branch
+  L     some_dir            # svn left a lock in the .svn area of some_dir
+M       bar.c               # the content in bar.c has local modifications
+ M      baz.c               # baz.c has property but no content modifications
+X       3rd_party           # dir is part of an externals definition
+?       foo.o               # svn doesn't manage foo.o
+!       some_dir            # svn manages this, but it's missing or incomplete
+~       qux                 # versioned as file/dir/link, but type has changed
+I       .screenrc           # svn doesn't manage this, and is set to ignore it
+A  +    moved_dir           # added with history of where it came from
+M  +    moved_dir/README    # added with history and has local modifications
+D       stuff/fish.c        # file is scheduled for deletion
+A       stuff/loot/bloo.h   # file is scheduled for addition
+C       stuff/loot/lump.c   # file has textual conflicts from an update
+ C      stuff/loot/glub.c   # file has property conflicts from an update
+R       xyz.c               # file is scheduled for replacement
+    S   stuff/squawk        # file or dir has been switched to a branch
+     K  dog.jpg             # file is locked locally; lock-token present 
+     O  cat.jpg             # file is locked in the repository by other user
+     B  bird.jpg            # file is locked locally, but lock has been broken
+     T  fish.jpg            # file is locked locally, but lock has been stolen
+
 </screen>
       
         <para>In this output format <command>svn status</command>
@@ -970,8 +975,8 @@
         
         <para>The third column will only show whitespace or an
           <computeroutput>L</computeroutput> which means that
-          Subversion has locked the item in
-          the <filename>.svn</filename> working area.  You will see an
+          Subversion has locked the direcotry's
+          <filename>.svn</filename> working area.  You will see an
           <computeroutput>L</computeroutput> if you run <command>svn
           status</command> in a directory where an <command>svn
           commit</command> is in progress—perhaps when you are
@@ -1006,6 +1011,10 @@
           file or directory has been switched from the path of the
           rest of the working copy (using <command>svn
           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>
         
         <para>If you pass a specific path to <command>svn
           status</command>, it gives you information about that item
@@ -2118,7 +2127,8 @@
 
       <screen>
 $ svnadmin create /usr/local/svn/newrepos
-$ svn import mytree file:///usr/local/svn/newrepos/some/project
+$ svn import mytree file:///usr/local/svn/newrepos/some/project \
+             -m "Initial import"
 Adding         mytree/foo.c
 Adding         mytree/bar.c
 Adding         mytree/subdir

Modified: trunk/src/en/book/ch05.xml
==============================================================================
--- trunk/src/en/book/ch05.xml	(original)
+++ trunk/src/en/book/ch05.xml	Thu Jun  2 13:11:07 2005
@@ -461,10 +461,11 @@
       property, <literal>svn:date</literal>, set to the time at which
       the repository was created.</para>
 
-    <para>In Subversion 1.1, a repository is created with a Berkeley
-      DB back-end by default.  This behavior may change in future
-      releases.  Regardless, the type can be explicitly chosen with
-      the <option>--fs-type</option> argument:</para>
+    <para>In Subversion 1.2, a repository is created with a FSFS
+      back-end by default (see <xref
+      linkend="svn.reposadmin.basics.backends"/>). The back-end can be
+      explicitly chosen with the <option>--fs-type</option>
+      argument:</para>
 
     <screen>
 $ svnadmin create --fs-type fsfs /path/to/repos
@@ -605,9 +606,9 @@
             
       <screen>
 $ ls repos/hooks/
-post-commit.tmpl          pre-revprop-change.tmpl
-post-revprop-change.tmpl  start-commit.tmpl
-pre-commit.tmpl           
+post-commit.tmpl          post-unlock.tmpl          pre-revprop-change.tmpl
+post-lock.tmpl            pre-commit.tmpl           pre-unlock.tmpl
+post-revprop-change.tmpl  pre-lock.tmpl             start-commit.tmpl
 </screen>
             
       <para>There is one template for each hook that the Subversion
@@ -653,8 +654,8 @@
         programs.</para>
       </tip>
 
-      <para>Currently there are five hooks implemented by the
-        Subversion repository:</para>
+      <para>There are nine hooks implemented by the Subversion
+        repository:</para>
 
       <variablelist>
         <varlistentry>
@@ -792,6 +793,70 @@
               value.</para>
           </listitem>
         </varlistentry>
+
+        <varlistentry>
+          <term><filename>pre-lock</filename></term>
+          <listitem>
+            <para>This hook runs whenever someone attempts to lock a
+              file.  It can be used to prevent locks altogether, or to
+              create a more complex policy specifying exactly which
+              users are allowed to lock particular paths.  If the hook
+              notices a pre-existing lock, then it can also decide
+              whether a user is allowed to "steal" the existing lock.
+              The repository passes three arguments to the hook: the
+              path to the repository, the path being locked, and the
+              user attempting to perform the lock.  If the program
+              returns a non-zero exit value, the lock action is
+              aborted and anything printed to stderr is marshalled
+              back to the client.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>post-lock</filename></term>
+          <listitem>
+            <para>This hook runs after a path is locked.  The locked
+              path is passed to the hook's stdin, and the hook also
+              receives two arguments:  the path to the repository, and
+              the user who performed the lock.  The hook is then free
+              to send email notification or record the event in any
+              way it chooses.  Because the lock already happened, the
+              output of the hook is ignored.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>pre-unlock</filename></term>
+          <listitem>
+            <para>This hook runs whenever someone attempts to remove a
+              lock on a file.  It can be used to create policies that
+              specify which users are allowed to unlock particular
+              paths.  It's particularly important for determining
+              policies about lock breakage.  If user A locks a file,
+              is user B allowed to break the lock?  What if the lock
+              is more than a week old?  These sorts of things can be
+              decided and enforced by the hook.  The repository passes
+              three arguments to the hook: the path to the repository,
+              the path being unlocked, and the user attempting to
+              remove the lock.  If the program returns a non-zero exit
+              value, the unlock action is aborted and anything printed
+              to stderr is marshalled back to the client.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term><filename>post-unlock</filename></term>
+          <listitem>
+            <para>This hook runs after a path is unlocked.  The
+              unlocked path is passed to the hook's stdin, and the
+              hook also receives two arguments: the path to the
+              repository, and the user who removed the lock.  The hook
+              is then free to send email notification or record the
+              event in any way it chooses.  Because the lock removal
+              already happened, the output of the hook is
+              ignored.</para>
+          </listitem>
+        </varlistentry>
       </variablelist>
 
       <warning>
@@ -1133,6 +1198,13 @@
           </varlistentry>
 
           <varlistentry>
+            <term><literal>lock</literal></term>
+            <listitem>
+              <para>If a path is locked, describe the lock attributes.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
             <term><literal>propget</literal></term>
             <listitem>
               <para>Print the value of a property on a path in the
@@ -1280,6 +1352,14 @@
           <varlistentry>
             <term><literal>lstxns</literal></term>
             <listitem>
+              <para>List and describe any locks that exist in the
+                repository.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term><literal>lstxns</literal></term>
+            <listitem>
               <para>List the names of uncommitted Subversion
                 transactions that currently exist in the repository.</para>
             </listitem>
@@ -1296,6 +1376,14 @@
           </varlistentry>
 
           <varlistentry>
+            <term><literal>rmlocks</literal></term>
+            <listitem>
+              <para>Unconditionally remove locks from listed
+                paths.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
             <term><literal>rmtxns</literal></term>
             <listitem>
               <para>Cleanly remove Subversion transactions from the

Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml	(original)
+++ trunk/src/en/book/ch07.xml	Thu Jun  2 13:11:07 2005
@@ -1680,6 +1680,40 @@
           the working copy.</para>
       </sect3>
 
+      <sect3 id="svn.advanced.props.special.needs-lock">
+        <title><literal>svn:needs-lock</literal></title>
+
+        <para>This property is used to signify that the file it's
+          attached to ought to be locked before editing.  The value of
+          the property is irrelevant; Subversion will normalize its
+          value to <literal>*</literal>.  When present, the file will
+          be read-only <emphasis>unless</emphasis> the user has
+          explicitly locked the file.  When a lock-token is present
+          (as a result of running <command>svn lock</command>), the
+          file becomes read-write.  When the lock is released, the
+          file becomes read-only again.</para>
+
+        <para>Users and administrators are encouraged to attach this
+          property to any file which cannot be contextually merged,
+          such as binary or proprietary-formatted files.  The main
+          idea is to prevent wasted time;  if the file is normally
+          read-only, then users will be reminded to lock the file
+          before editing, thus discovering any pre-existing
+          locks.</para>
+
+        <para>Note that this property is a communication system which
+          works independent of the locking system.  In other words,
+          any file can be locked, whether or not this property is
+          present.  And conversely, the presence of this property
+          doesn't make the repository require a lock.  It's possible
+          for a misbehaving application to "hijack" the read-only
+          file, edit it anyway, then allow the user to commit without
+          a lock.</para>
+
+        <para>For more on locking, see <xref
+        linkend="svn.advanced.locking"/>.</para>
+      </sect3>
+
     </sect2>
 
     <!-- ***************************************************************** -->
@@ -1738,6 +1772,16 @@
   </sect1>
 
   <!-- ******************************************************************* -->
+  <!-- *** LOCKING                                                     *** -->
+  <!-- ******************************************************************* -->
+  <sect1 id="svn.advanced.locking">
+    <title>Locking</title>
+
+
+  </sect1>
+
+
+  <!-- ******************************************************************* -->
   <!-- *** SECTION 2 1/2:  PEG AND OPERATIVE REVISIONS                 *** -->
   <!-- ******************************************************************* -->
   <sect1 id="svn.advanced.pegrevs">



More information about the svnbook-dev mailing list