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

sussman svnbook-dev at red-bean.com
Tue Jun 14 17:48:09 CDT 2005

Author: sussman
Date: Tue Jun 14 17:48:08 2005
New Revision: 1442


* src/en/book/ch07.xml 
  (Locking):  start fleshing out the new locking section.

* src/en/book/ch02.xml
  (When Locking is Necessary):  fix wording.

Modified: trunk/src/en/book/ch02.xml
--- trunk/src/en/book/ch02.xml	(original)
+++ trunk/src/en/book/ch02.xml	Tue Jun 14 17:48:08 2005
@@ -257,8 +257,8 @@
           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>
+          somebody ends up wasting 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

Modified: trunk/src/en/book/ch07.xml
--- trunk/src/en/book/ch07.xml	(original)
+++ trunk/src/en/book/ch07.xml	Tue Jun 14 17:48:08 2005
@@ -1777,6 +1777,162 @@
   <sect1 id="svn.advanced.locking">
+    <para>Subversion's <quote>copy-modify-merge</quote> model is
+      optimal when users are collaborating on projects that consist of
+      line-based text files, such as program source code.  However, as
+      discussed in <xref
+      linkend="svn.basic.vsn-models.copy-merge.sb-1"/>, sometimes one
+      has to use the <quote>lock-modify-unlock</quote> model instead
+      of Subversion's standard concurrent model.  When a file consists
+      of binary data, it's often difficult or impossible to merge two
+      sets of changes made in parallel by different users.  For this
+      reason, Subversion 1.2 and later offers a feature known as
+      <firstterm>locking</firstterm>, often known as <quote>reserved
+      checkouts</quote> in other version control systems.</para>
+    <para>Subversion's locking feature has two main goals:</para>
+    <itemizedlist>
+      <listitem><para><emphasis>Serializing access to a
+          resource</emphasis>.  Allow a user to grab an exclusive
+          right to change to a file in the repository.  If Harry
+          reserves the right to change <filename>foo.jpg</filename>,
+          then Sally should not be able to commit a change to that
+          file.</para>
+      </listitem>
+      <listitem><para><emphasis>Aiding communication</emphasis>.
+          Prevent users from wasting time on unmergeable changes.  If
+          Harry has reserved the right to change
+          <filename>foo.jpg</filename>, then it should be easy for
+          Sally to notice this fact and avoid working on the
+          file.</para>
+      </listitem>
+    </itemizedlist>
+    <para>Subversion's locking feature is currently limited to files
+      only; it's not yet possible to recursively reserve access to a
+      whole directory tree.</para>
+    <sect2 id="svn.advanced.locking.file-reservation">
+      <title>Reserving a file</title>
+      <para>In the Subverison repository, a
+        <firstterm>lock</firstterm> is a piece of metadata which
+        grants exclusive access to one user to change a file.  This
+        user is said to be the <firstterm>lock owner</firstterm>.
+        Each lock also has a unique identifier, typically a long
+        string of characters, known as the <firstterm>lock
+        token</firstterm>.  The repository manages locks in a separate
+        table, and enforces locks during commit.  If any commit
+        transaction attempts to modify or delete the file (or delete a
+        parent of the file), the repository will demand two pieces of
+        information:</para>
+      <orderedlist>
+        <listitem><para><emphasis role="bold">User
+          authentication</emphasis>.  The client performing the commit
+          must be authenticated as the lock owner.</para>
+        </listitem>
+        <listitem><para><emphasis role="bold">Software
+          authorization</emphasis>.  The user's working copy must send
+          the lock token with the commit, proving that it knows
+          exactly which lock it's using.</para>
+        </listitem>
+      </orderedlist>
+      <para>An example is in order, to demonstrate.  Let's say that
+        Harry has decided to change a JPEG image.  To prevent other
+        people from committing changes to the file, he locks the file
+        in the repository using the <command>svn lock</command>
+        command:</para>
+      <screen>
+$ svn lock banana.jpg -m "Editing file for tomorrow's release."
+'banana.jpg' locked by user 'harry'.
+$ svn status
+     K banana.jpg
+$ svn info banana.jpg
+Path: banana.jpg
+Name: banana.jpg
+URL: http://svn.example.com/repos/project/banana.jpg
+Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
+Revision: 2198
+Node Kind: file
+Schedule: normal
+Last Changed Author: frank
+Last Changed Rev: 1950
+Last Changed Date: 2005-03-15 12:43:04 -0600 (Tue, 15 Mar 2005)
+Text Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
+Properties Last Updated: 2005-06-08 19:23:07 -0500 (Wed, 08 Jun 2005)
+Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
+Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
+Lock Owner: harry
+Lock Created: 2005-06-14 17:20:31 -0500 (Tue, 14 Jun 2005)
+Lock Comment (1 line):
+Editing file for tomorrow's release.
+      <para>There are a number of new things demonstrated in the
+        previous example.  First, notice that Harry passed the
+        <option>-m</option> option to <command>svn lock</command>.
+        Similar to <command>svn commit</command>, the <command>svn
+        lock</command> command can take comments (either via
+        <option>-m</option> or <option>-F</option>) to describe the
+        reason for locking the file.  Unlike <command>svn
+        commit</command>, however, <command>svn lock</command> will
+        not demand a message by launching <literal>$EDITOR</literal>
+        or <literal>$SVN_EDITOR</literal>.  Lock comments are strictly
+        optional.</para>
+      <para>Also notice that after creating the lock in the
+        repository, the working copy has cached detailed information
+        about the lock—most importantly, the lock token.  The
+        presence of the lock token is critical;  it gives the working
+        copy authorization to make use of the lock later on.  The
+        <command>svn status</command> command shows a
+        <literal>K</literal> next to the file (short for locKed),
+        indicating that the lock token is present.</para>
+      <sidebar>
+        <title>Regarding lock tokens</title>
+        <para>A lock token isn't an authentication token, so much as
+          an <emphasis>authorization</emphasis> token.  The token
+          isn't a protected secret;  in fact, a lock's unique token is
+          discoverable by anyone who runs <command>svn info
+          URL</command>.</para>
+        <para>A lock token special only when it lives inside a working
+          copy.  It's proof that the lock was created in that
+          particular working copy, and not some other piece of
+          software.  Merely authenticating as the lock-owner isn't
+          enough to prevent chaos.</para>
+        <para>For example: suppose you lock an unmergeable file using
+         a computer at your office, perhaps as part of a changeset in
+         progress.  It should not be possible for a working copy (or
+         alternate Subversion client) on your home computer to
+         accidentally commit a change to that same file, just because
+         you've authenticated as the lock's owner.  In other words,
+         the lock token prevents one piece of Subversion-related
+         software from undermining the work of another.  (In our
+         example, if you really need to change the file from an
+         alternate working copy, you would need to break the lock and
+         re-lock the file.)</para>
+      </sidebar>
+    </sect2>

More information about the svnbook-dev mailing list