[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