[svnbook commit] r1458 - in trunk/src/en: . book
sussman
svnbook-dev at red-bean.com
Thu Jun 16 14:28:37 CDT 2005
Author: sussman
Date: Thu Jun 16 14:28:36 2005
New Revision: 1458
Modified:
trunk/src/en/TODO
trunk/src/en/book/ch07.xml
Log:
* src/en/book/ch07.xml
(Locking): finish this section.
* src/en/TODO: remove to-done, add work for ch09 for fitz.
Modified: trunk/src/en/TODO
==============================================================================
--- trunk/src/en/TODO (original)
+++ trunk/src/en/TODO Thu Jun 16 14:28:36 2005
@@ -4,9 +4,6 @@
NEEDED FOR 1.2 COMPLETION
============================================================================
- * the new locking feature, and all of its many tendrils.
- touches chapters 2, 3, 5, 9 at a minimum. [MIKE, BEN, FITZ]
-
* ch00: "what's new in svn 1.2". [BEN]
* ch05: comparison of bdb and fsfs: make it clear that fsfs is now
@@ -27,6 +24,14 @@
* ch09: add autoversioning to mod_dav_svn directives. [FITZ]
+ * ch09: add locking-feature stuff to reference section: [FITZ]
+
+ svn lock/unlock
+ svn info [-r] URL|wcpath
+ new 'svn status' codes (KOBT)
+ svnadmin lslocks/rmlocks
+ svnlook lock
+
* Possibly document mod_mime's interaction with Autoversioning: (BEN)
Make autoversioning more friendly, by cooperating with httpd's
@@ -161,3 +166,4 @@
berlios.de
+0: cmpilato
+
Modified: trunk/src/en/book/ch07.xml
==============================================================================
--- trunk/src/en/book/ch07.xml (original)
+++ trunk/src/en/book/ch07.xml Thu Jun 16 14:28:36 2005
@@ -1693,25 +1693,10 @@
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>
+ <para>To learn more about how, when, and why this property
+ should be used, see
+ <xref
+ linkend="svn.advanced.locking.lock-communication"/>.</para>
</sect3>
</sect2>
@@ -2248,16 +2233,88 @@
</sect2>
- <sect2 id="svn.advanced.locking.prevent-wasted-time">
- <title>Preventing wasted time</title>
+ <sect2 id="svn.advanced.locking.lock-communication">
+ <title>Lock Communication</title>
+ <para>We've seen how <command>svn lock</command>
+ and <command>svn unlock</command> can be used to create,
+ release, break, and steal locks. This satisifies the goal of
+ serializing commit access to a file. But what about the
+ larger problem of preventing wasted time?</para>
+
+ <para>For example, suppose Harry locks an image file and then
+ begins editing it. Meanwhile, miles away, Sally wants to do
+ the same thing. She doesn't think to run <command>svn status
+ --show-updates</command>, so she has no idea that Harry has
+ already locked the file. She spends hours editing the file,
+ and when she tries to commit her change, she discovers that
+ either the file is locked or that she's out-of-date.
+ Regardless, her changes aren't mergeable with Harry's. One of
+ these two people has to throw away their work, and a lot of
+ time has been wasted.</para>
+ <para>Subversion's solution to this problem is provide a
+ mechanism to remind users that a file ought to be locked
+ <emphasis>before</emphasis> the editing begins.</para>
+
+ <para>The mechanism is a special
+ property, <literal>svn:needs-lock</literal>. If the property
+ is attached to a file (the value is irrelevant), then the file
+ will have read-only permissions. When the user locks the file
+ and receives a lock token, the file becomes read-write. When
+ the lock is released—either explicitly unlocked, or
+ released via commit—the file returns to read-only
+ again.</para>
+ <para>The theory, then, is that if the image file has this
+ property attached, then Sally would immediately notice
+ something is strange when she opens the file for editing. Her
+ application would be unable to save changes, or (better yet)
+ tell her that the file is read-only. This reminds her to lock
+ the file before editing, whereby she discovers the
+ pre-existing lock:</para>
+ <screen>
+$ /usr/local/bin/gimp raisin.jpg
+gimp: error: file is read-only!
- </sect2>
+$ ls -l raisin.jpg
+-r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
+$ svn lock raisin.jpg
+svn: Lock request failed: 423 Locked (http://svn.example.com)
+$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
+Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
+Lock Owner: harry
+Lock Created: 2005-06-08 07:29:18 -0500 (Thu, 08 June 2005)
+Lock Comment (1 line):
+Making some tweaks. Locking for the next two hours.
+
+</screen>
+
+ <para>As a matter of <quote>best practice</quote>, both users
+ and administrators are encouraged to attach
+ the <literal>svn:needs-lock</literal> property to any file
+ which cannot be contextually merged. It's the main
+ technique for encouraging good locking habits and preventing
+ wasted effort.</para>
+
+ <para>Note that this property is a communication tool which
+ works independently from 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 when
+ committing.</para>
+
+ <para>The system isn't flawless, either. It's possible that
+ even when a file has the property, the read-only reminder
+ won't always work. Sometimes applications misbehave and
+ <quote>hijack</quote> the read-only file, silently allowing
+ users to edit and save the file anyway. Unfortunately,
+ there's not much Subversion can do about this.</para>
+
+ </sect2>
</sect1>
More information about the svnbook-dev
mailing list