[svnbook commit] r2585 - branches/ora-2e-reorg/src/en/book
cmpilato
noreply at red-bean.com
Fri Dec 29 23:26:57 CST 2006
Author: cmpilato
Date: Fri Dec 29 23:26:56 2006
New Revision: 2585
Modified:
branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
Log:
Branch: ora-2e-reorg
Finish my first pass over Chapter 3. If I had to turn this chapter in
to Tatiana today, I'd be comfortable doing so.
* src/en/book/ch-advanced-topics.xml
(Locking, Externals Definitions): Tweaky, tweaky...
Modified: branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml
==============================================================================
--- branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml (original)
+++ branches/ora-2e-reorg/src/en/book/ch-advanced-topics.xml Fri Dec 29 23:26:56 2006
@@ -443,8 +443,8 @@
Properties)</title>
<para>For all their utility, Subversion properties—or,
- more accurately, the user's interface to them—has a
- major shortcoming which diminishes their practicality.
+ more accurately, the available interfaces to them—have
+ a major shortcoming which diminishes their practicality.
While it is a simple matter to set a custom property,
<emphasis>finding</emphasis> that property later is whole
different ball of wax.</para>
@@ -467,8 +467,8 @@
metadata to the revision's log message, using some
policy-driven (and perhaps programmatically-enforced)
formatting that is designed to be quickly parsed from the
- output of <command>svn log</command>. You might see the
- likes of:</para>
+ output of <command>svn log</command>. It is quite common to
+ see in Subversion log messages the likes of:</para>
<programlisting>
Issue(s): IZ2376, IZ1919
@@ -1675,42 +1675,125 @@
<sect1 id="svn.advanced.locking">
<title>Locking</title>
- <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 copy-modify-merge version control model lives
+ and dies by the granularity of the data merging algorithms
+ employed when trying to resolve conflicts caused by multiple
+ users modifying the same file concurrently. Subversion itself
+ provides only one such algorithm, a three-way differencing
+ algorithm which is smart enough to handle data at a granularity
+ of a single line of text. Subversion also allows you to
+ supplement its content merge processing with external
+ differencing utilities (as described in <xref
+ linkend="svn.advanced.externaldifftools.diff3" />), some of which
+ may do an even better job, perhaps providing granularity of a
+ word or a single character of text. But common among those
+ algorithms is that they generally work only on text files. The
+ landscape starts to look pretty grim when you start talking
+ about content merges of non-textual file formats. And when you
+ can't find a tool that can handle that type of merging, you
+ begin to run into problems with the copy-modify-merge
+ model.</para>
+
+ <para>Let's look at a real-life example of where this model runs
+ aground. Harry and Sally are both graphic designers working on
+ the same project, a bit of marketing collateral for an
+ automobile mechanic. Central to the design of a particular
+ poster is an image of a car in need of some body work, stored in
+ a file using the PNG image format. The poster's layout is
+ almost finished, and both Harry and Sally are pleased with the
+ particular photo they chose for their damaged car—a baby
+ blue 1967 Ford Mustang with an unfortunate bit of crumpling on
+ the left front fender.</para>
+
+ <para>Now, as is common in graphic design work, there's a change
+ in plans which causes the car's color to be a concern. So Sally
+ updates her working copy to <literal>HEAD</literal>, fires up
+ her photo editing software, and sets about tweaking the image so
+ that the car is now cherry red. Meanwhile, Harry, feeling
+ particularly inspired that day, decides that the image would
+ have greater impact if the car also appears to have suffered
+ greater impact. He, too, updates to <literal>HEAD</literal>,
+ and then draws some cracks on the vehicle's windshield. He
+ manages to finish his work before Sally finishes hers, and after
+ admiring the fruits of his undeniable talent, commits the
+ modified image. Shortly thereafter, Sally is finished with the
+ car's new finish, and tries to commit her changes. But, as
+ expected, Subversion fails the commit, informing Sally that now
+ her version of the image is out of date.</para>
+
+ <para>Here's where the difficulty sets in. Were Harry and Sally
+ making changes to a text file, Sally would simply update her
+ working copy, receiving Harry's changes in the process. In the
+ worst possible case, they would have modified the same region of
+ the file, and Sally would have to work out by hand the proper
+ resolution to the conflict. But these aren't text
+ files—they are binary images. And while it's a simple
+ matter to describe what one would expect the results of this
+ content merge to be, there is precious little chance that any
+ software exists which is smart enough to examine the common
+ baseline image that each of these graphic artists worked
+ against, the changes that Harry made, and the changes that Sally
+ made, and spit out an image of a busted-up red Mustang with a
+ cracked windshield!</para>
+
+ <para>Clearly, things would have gone more smoothly if Harry and
+ Sally had serialized their modifications to the image. If, say,
+ Harry had waited to draw his windshield cracks on Sally's
+ now-red car, or if Sally had tweaked the color of a car whose
+ windshield was already cracked. As is discussed in <xref
+ linkend="svn.basic.vsn-models.copy-merge" />, much of these
+ types problems go away entirely where perfect communication
+ between Harry and Sally exists.
+ <footnote>
+ <para>Communication wouldn't have been such bad medicine for
+ Harry and Sally's Hollywood namesakes, either, for that
+ matter.</para>
+ </footnote>
+ But as one's version control system is, in fact, one form of
+ communication, it follows that having that software facilitate
+ the serialization of non-parallelizable energies is no bad
+ thing. And this where Subversion's implementation of the
+ lock-modify-unlock model steps into the spotlight. This is
+ where we talk about Subversion's <firstterm>locking</firstterm>
+ feature, which is similar to the reserved checkouts mechanisms
+ of other version control systems.</para>
- <para>Subversion's locking feature has two main goals:</para>
+ <para>Subversion's locking feature serves two main
+ purposes:</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 it.</para>
+ <para><emphasis>Serializing access to a versioned
+ resource</emphasis>. But allowing a user to
+ programmatically claim the exclusive right to change to a
+ file in the repository, that user can be reasonably
+ confident that energy invested on unmergeable changes won't
+ be wasted; that his commit of those changes will
+ succeed.</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>
+ <para><emphasis>Aiding communication</emphasis>. By alerting
+ other users that serialization is in effect for particular
+ versioned resource, those other users can reasonably expect
+ that the resource is about to be changed by someone else,
+ and they, too, can avoid wasting their time and energy on
+ unmergeable changes that won't be committable due to eventual
+ out-of-dateness.</para>
</listitem>
</itemizedlist>
- <para>Subversion's locking feature is currently limited to files
- only—it's not yet possible to reserve access to a whole
- directory tree.</para>
+ <para>When referring to Subversion's locking feature, one is
+ actually talking about a fairly diverse collection of behaviors
+ which include the ability to lock a versioned file
+ <footnote>
+ <para>Subversion does not currently allow locks on directories.</para>
+ </footnote>
+ (claiming the exclusive right to modify the file), to unlock
+ that file (yielding that exclusive right to modify), to see
+ reports about which files are locked and by whom, to annotate
+ files for which locking before editing is strongly advised, and
+ so on. In this section, we'll cover all of these facets of the
+ larger locking feature.</para>
<sidebar id="svn.advanced.locking.meanings">
<title>Three meanings of <quote>lock</quote></title>
@@ -1722,34 +1805,28 @@
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>The first is <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>
+
+ <para>Secondly, there are <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>
<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
+ them. In this book, <quote>lock</quote> means the first sort
unless the contrary is either clear from context or explicitly
stated.</para>
+
</sidebar>
<!-- =============================================================== -->
@@ -1762,38 +1839,62 @@
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 a commit operation. 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>
+ token</firstterm>. The repository manages locks, ultimately
+ handling their creation, enforcement, and removal. If any
+ commit transaction attempts to modify or delete a locked file
+ (or delete one of the parent directories of the file), the
+ repository will demand two pieces of information—that
+ the client performing the commit be authenticated as the lock
+ owner, and that the lock token has been provided as part of
+ the commit process as a sort of proof that client knows which
+ lock it is using.</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>
+ <para>To demonstrate lock creation, let's refer back to our
+ example of multiple graphic designers working with on the same
+ binary image files. Harry has decided to change a JPEG image.
+ To prevent other people from committing changes to the file
+ while he is modifying it (as well as alerting them that he is
+ about to change it), he locks the file in the repository using
+ the <command>svn lock</command> command.</para>
<screen>
-$ svn lock banana.jpg --message "Editing file for tomorrow's release."
+[harry] $ svn lock banana.jpg --message "Editing file for tomorrow's release."
'banana.jpg' locked by user 'harry'.
+[harry] $
+</screen>
-$ svn status
+ <para>There are a number of new things demonstrated in the
+ previous example. First, notice that Harry passed the
+ <option>--message</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>--message (-m)</option> or <option>--file
+ (-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 your
+ preferred text editor. Lock comments are optional, but still
+ recommended to aid communication.</para>
+
+ <para>Secondly, the lock attempt succeeded. This means that the
+ file wasn't already locked, and that Harry had the latest
+ version of the file. If Harry's working copy of the file had
+ been out-of-date, the repository would have rejected the
+ request, forcing Harry to <command>svn update</command> and
+ reattempt the locking command. The locking command would also
+ have failed if the file already been locked by someone
+ else.</para>
+
+ <para>As you can see, the <command>svn lock</command> command
+ prints confirmation of the successful lock. At this point,
+ the fact that the file is locked becomes apparent in the
+ output of the <command>svn status</command> and <command>svn
+ info</command> reporting subcommands.</para>
+
+ <screen>
+[harry] $ svn status
K banana.jpg
-$ svn info banana.jpg
+[harry] $ svn info banana.jpg
Path: banana.jpg
Name: banana.jpg
URL: http://svn.example.com/repos/project/banana.jpg
@@ -1813,34 +1914,16 @@
Lock Comment (1 line):
Editing file for tomorrow's release.
+[harry] $
</screen>
- <para>There are a number of new things demonstrated in the
- previous example. First, notice that Harry passed the
- <option>--message</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>--message (-m)</option> or <option>--file
- (-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 your
- preferred text editor. Lock comments are optional, but still
- recommended to aid communication.</para>
-
- <para>Second, the lock attempt succeeded. This means that the
- file wasn't already locked, and that Harry had the latest
- version of the file. If Harry's working copy of the file had
- been out-of-date, the repository would have rejected the
- request, forcing harry to <command>svn update</command> and
- reattempt the locking command.</para>
-
- <para>Also notice that after creating the lock in the
- repository, the working copy has cached 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
+ <para>That the <command>svn info</command> command, which does
+ not contact the repository when run against working copy
+ paths, can display the lock token reveals an important fact
+ about lock tokens—that they are cached in the working
+ copy. The presence of the lock token is critical. It gives
+ the working copy authorization to make use of the lock later
+ on. Also, 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>
@@ -1851,19 +1934,17 @@
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 is special only when it lives inside a
- working copy. It's proof that the lock was created in that
- particular working copy, and not somewhere else by some
- other client. Merely authenticating as the lock owner isn't
- enough to prevent accidents.</para>
-
- <para>For example: suppose you lock a 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
+ URL</command>. A lock token is special only when it lives
+ inside a working copy. It's proof that the lock was created
+ in that particular working copy, and not somewhere else by
+ some other client. Merely authenticating as the lock owner
+ isn't enough to prevent accidents.</para>
+
+ <para>For example, suppose you lock a file using a computer at
+ your office, but leave work for the day before you finish
+ your changes to that file. It should not be possible to
+ accidentally commit changes to that same file from your home
+ computer later that evening simply 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
@@ -1877,19 +1958,15 @@
Sally is unable to change or delete that file:</para>
<screen>
-$ whoami
-sally
-
-$ svn delete banana.jpg
+[sally] $ svn delete banana.jpg
D banana.jpg
-
-$ svn commit -m "Delete useless file."
+[sally] $ svn commit -m "Delete useless file."
Deleting banana.jpg
svn: Commit failed (details follow):
svn: DELETE of
'/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/banana.jpg':
423 Locked (http://svn.example.com)
-
+[sally] $
</screen>
<para>But Harry, after touching up the banana's shade of yellow,
@@ -1898,57 +1975,49 @@
copy holds the correct lock token:</para>
<screen>
-$ whoami
-harry
-
-$ svn status
+[harry] $ svn status
M K banana.jpg
-
-$ svn commit -m "Make banana more yellow"
+[harry] $ svn commit -m "Make banana more yellow"
Sending banana.jpg
Transmitting file data .
Committed revision 2201.
-
-$ svn status
-$
+[harry] $ svn status
+[harry] $
</screen>
<para>Notice that after the commit is finished, <command>svn
status</command> shows that the lock token is no longer
present in working copy. This is the standard behavior of
- <command>svn commit</command>: it walks the working copy (or
- list of targets, if you provide such a list), and sends all
- lock tokens it encounters to the server as part of the commit
- transaction. After the commit completes successfully, all of
- the repository locks that were mentioned are
+ <command>svn commit</command>—it searches the working
+ copy (or list of targets, if you provide such a list) for
+ local modifications, and sends all the lock tokens it
+ encounters during this walk to the server as part of the
+ commit transaction. After the commit completes successfully,
+ all of the repository locks that were mentioned are
released—<emphasis>even on files that weren't
- committed.</emphasis> The rationale here is to discourage
- users from being sloppy about locking, or from holding locks
- for too long. For example, suppose Harry were to haphazardly
- lock thirty files in a directory named
- <filename>images</filename>, because he's unsure of which
- files he needs to change. He ends up making changes to only
- four files. When he runs <command>svn commit
- images</command>, the process would still release all thirty
- locks.</para>
+ committed</emphasis>. This is meant to discourage users from
+ being sloppy about locking, or from holding locks for too
+ long. If Harry haphazardly locks thirty files in a directory
+ named <filename>images</filename> because he's unsure of which
+ files he needs to change, yet only only changes four of those
+ file, when he runs <command>svn commit images</command>, the
+ process will still release all thirty locks.</para>
<para>This behavior of automatically releasing locks can be
overridden with the <option>--no-unlock</option> option to
<command>svn commit</command>. This is best used for those
times when you want to commit changes, but still plan to make
- more changes and thus need to retain existing locks. This
- behavior is also semi-permanently tweakable, by setting
- <literal>no-unlock = yes</literal> in your run-time
- <filename>config</filename> file (see <xref
- linkend="svn.advanced.confarea"/>).</para>
+ more changes and thus need to retain existing locks. You can
+ also make this your default behavior by setting the
+ <literal>no-unlock</literal> runtime configuration option (see
+ <xref linkend="svn.advanced.confarea" />).</para>
<para>Of course, locking a file doesn't oblige one to commit a
change to it. The lock can be released at any time with a
- simple
- <command>svn unlock</command> command:</para>
+ simple <command>svn unlock</command> command:</para>
<screen>
-$ svn unlock banana.c
+[harry] $ svn unlock banana.c
'banana.c' unlocked.
</screen>
@@ -1963,14 +2032,12 @@
these is <command>svn status --show-updates</command>:</para>
<screen>
-$ whoami
-sally
-
-$ svn status --show-updates
+[sally] $ svn status --show-updates
M 23 bar.c
M O 32 raisin.jpg
* 72 foo.h
Status against revision: 105
+[sally] $
</screen>
<para>In this example, Sally can see not only that her copy of
@@ -1985,7 +2052,7 @@
answers:</para>
<screen>
-$ svn info http://svn.example.com/repos/project/raisin.jpg
+[sally] $ svn info http://svn.example.com/repos/project/raisin.jpg
Path: raisin.jpg
Name: raisin.jpg
URL: http://svn.example.com/repos/project/raisin.jpg
@@ -2000,6 +2067,7 @@
Lock Created: 2005-02-16 13:29:18 -0500 (Wed, 16 Feb 2005)
Lock Comment (1 line):
Need to make a quick tweak to this image.
+[sally] $
</screen>
<para>Just as <command>svn info</command> can be used to examine
@@ -2013,8 +2081,8 @@
path will show no lock information at all). If the main
argument to <command>svn info</command> is a URL, then the
information reflects the latest version of an object in the
- repository; any mention of a lock describes the current lock
- on the object.</para>
+ repository, and any mention of a lock describes the current
+ lock on the object.</para>
<para>So in this particular example, Sally can see that Harry
locked the file on February 16th to <quote>make a quick
@@ -2030,8 +2098,9 @@
<sect2 id="svn.advanced.locking.break-steal">
<title>Breaking and stealing locks</title>
- <para>A repository lock isn't sacred; it can be released not
- only by the person who created it, but by anyone at all. When
+ <para>A repository lock isn't sacred—in Subversion's
+ default configuration state, locks can be released not only by
+ the person who created them, but by anyone at all. When
somebody other than the original lock creator destroys a lock,
we refer to this as <firstterm>breaking</firstterm> the
lock.</para>
@@ -2044,7 +2113,7 @@
<xref linkend="svn.reposadmin.maint.tk"/>.)</para>
<screen>
-$ svnadmin lslocks /usr/local/svn/repos
+[admin] $ svnadmin lslocks /usr/local/svn/repos
Path: /project2/images/banana.jpg
UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Owner: frank
@@ -2061,8 +2130,9 @@
Comment (1 line):
Need to make a quick tweak to this image.
-$ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
+[admin] $ svnadmin rmlocks /usr/local/svn/repos /project/raisin.jpg
Removed lock on '/project/raisin.jpg'.
+[admin] $
</screen>
<para>The more interesting option is allowing users to break
@@ -2071,26 +2141,20 @@
command:</para>
<screen>
-$ whoami
-sally
-
-$ svn status --show-updates
+[sally] $ svn status --show-updates
M 23 bar.c
M O 32 raisin.jpg
* 72 foo.h
Status against revision: 105
-
-$ svn unlock raisin.jpg
+[sally] $ svn unlock raisin.jpg
svn: 'raisin.jpg' is not locked in this working copy
-
-$ svn info raisin.jpg | grep URL
+[sally] $ svn info raisin.jpg | grep URL
URL: http://svn.example.com/repos/project/raisin.jpg
-
-$ svn unlock http://svn.example.com/repos/project/raisin.jpg
+[sally] $ svn unlock http://svn.example.com/repos/project/raisin.jpg
svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
-
-$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
+[sally] $ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
'raisin.jpg' unlocked.
+[sally] $
</screen>
<para>Sally's initial attempt to unlock failed because she
@@ -2116,82 +2180,73 @@
do this, pass the <option>--force</option> option
to <command>svn lock</command>:</para>
- <screen>
-$ svn lock raisin.jpg
+ <screen>
+[sally] $ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
-
-$ svn lock --force raisin.jpg
+[sally] $ svn lock --force raisin.jpg
'raisin.jpg' locked by user 'sally'.
+[sally] $
</screen>
- <para>In any case, whether the lock is broken or stolen, Harry
- may be in for a surprise. Harry's working copy still
- contains the original lock token, but that lock no longer
- exists. The lock token is said to
- be <firstterm>defunct</firstterm>. The lock represented by
- the lock-token has either been broken (no longer in the
- repository), or stolen (replaced with a different lock).
- Either way, Harry can see this by asking <command>svn
- status</command> to contact the repository:</para>
-
- <screen>
-$ whoami
-harry
+ <para>In any case, whether the lock is broken or stolen, Harry
+ may be in for a surprise. Harry's working copy still contains
+ the original lock token, but that lock no longer exists. The
+ lock token is said to be <firstterm>defunct</firstterm>. The
+ lock represented by the lock-token has either been broken (no
+ longer in the repository), or stolen (replaced with a
+ different lock). Either way, Harry can see this by asking
+ <command>svn status</command> to contact the
+ repository:</para>
-$ svn status
+ <screen>
+[harry] $ svn status
K raisin.jpg
-
-$ svn status --show-updates
+[harry] $ svn status --show-updates
B 32 raisin.jpg
-
-$ svn update
+[harry] $ svn update
B raisin.jpg
-
-$ svn status
-
-$
+[harry] $ svn status
+[harry] $
</screen>
- <para>If the repository lock was broken, then <command>svn
- status --show-updates</command> displays
- a <literal>B</literal> (Broken) symbol next to the file.
- If a new lock exists in place of the old one, then
- a <literal>T</literal> (sTolen) symbol is shown.
- Finally, <command>svn update</command> notices any defunct
- lock tokens and removes them from the working copy.</para>
+ <para>If the repository lock was broken, then <command>svn
+ status --show-updates</command> displays a
+ <literal>B</literal> (Broken) symbol next to the file. If a
+ new lock exists in place of the old one, then a
+ <literal>T</literal> (sTolen) symbol is shown. Finally,
+ <command>svn update</command> notices any defunct lock tokens
+ and removes them from the working copy.</para>
- <sidebar>
- <title>Locking Policies</title>
+ <sidebar>
+ <title>Locking Policies</title>
- <para>Different systems have different notions of how strict
- a lock should be. Some folks argue that locks must be
- strictly enforced at all costs, releasable only by the
- original creator or administrator. They argue that if
- anyone can break a lock, then chaos breaks loose and the
- whole point of locking is defeated. The other side argues
- that locks are first and foremost a communication tool.
- If users are constantly breaking each others' locks, then
- it represents a cultural failure within the team and the
- problem falls outside the scope of software
- enforcement.</para>
-
- <para>Subversion defaults to the <quote>softer</quote>
- approach, but still allows administrators to create
- stricter enforcement policies through the use of hook
- scripts. In particular, the <filename>pre-lock</filename>
- and <filename>pre-unlock</filename> hooks allow
- administrators to decide when lock creation and lock
- releases are allowed to happen. Depending on whether or
- not a lock already exists, these two hooks can decide
- whether or not to allow a certain user to break or steal a
- lock. The <filename>post-lock</filename>
- and <filename>post-unlock</filename> hooks are also
- available, and can be used to send email after locking
- actions.</para>
-
- <para>To learn more about repository hooks, see
- <xref linkend="svn.reposadmin.create.hooks"/>.</para>
- </sidebar>
+ <para>Different systems have different notions of how strict a
+ lock should be. Some folks argue that locks must be
+ strictly enforced at all costs, releasable only by the
+ original creator or administrator. They argue that if
+ anyone can break a lock, then chaos runs rampant and the
+ whole point of locking is defeated. The other side argues
+ that locks are first and foremost a communication tool. If
+ users are constantly breaking each others' locks, then it
+ represents a cultural failure within the team and the
+ problem falls outside the scope of software enforcement.</para>
+
+ <para>Subversion defaults to the <quote>softer</quote>
+ approach, but still allows administrators to create stricter
+ enforcement policies through the use of hook scripts. In
+ particular, the <filename>pre-lock</filename> and
+ <filename>pre-unlock</filename> hooks allow administrators
+ to decide when lock creation and lock releases are allowed
+ to happen. Depending on whether or not a lock already
+ exists, these two hooks can decide whether or not to allow a
+ certain user to break or steal a lock. The
+ <filename>post-lock</filename> and
+ <filename>post-unlock</filename> hooks are also available,
+ and can be used to send email after locking actions. To
+ learn more about repository hooks, see <xref
+ linkend="svn.reposadmin.create.hooks" />.</para>
+
+ </sidebar>
</sect2>
@@ -2220,61 +2275,67 @@
mechanism to remind users that a file ought to be locked
<emphasis>before</emphasis> the editing begins. 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 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>
+ that property is attached to a file (regardless of its value,
+ which is irrelevant), then Subversion will try to use
+ filesystem-level permissions to make the file read-only,
+ unless, of course, 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>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>
+ something is strange when she opens the file for editing.
+ Many applications alert users immediately when a read-only
+ file is opened for editing. And nearly all applications would
+ at least prevert her from saving changes to the file. This
+ reminds her to lock the file before editing, whereby she
+ discovers the pre-existing lock:</para>
<screen>
-$ /usr/local/bin/gimp raisin.jpg
+[sally] $ /usr/local/bin/gimp raisin.jpg
gimp: error: file is read-only!
-
-$ ls -l raisin.jpg
+[sally] $ ls -l raisin.jpg
-r--r--r-- 1 sally sally 215589 Jun 8 19:23 raisin.jpg
-
-$ svn lock raisin.jpg
+[sally] $ 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
+[sally] $ 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.
-
+[sally] $
</screen>
- <para>As a matter of <quote>best practice</quote>, both users
- and administrators are encouraged to attach
+ <tip>
+ <para>Users and administrators alike are encouraged to attach
the <literal>svn:needs-lock</literal> property to any file
- which cannot be contextually merged. It's the main
+ which cannot be contextually merged. This is the primary
technique for encouraging good locking habits and preventing
wasted effort.</para>
+ </tip>
- <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>
+ <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>Unfortunately, the system isn't flawless. 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. There's not much that
+ Subversion can do in this situation—at the end of the
+ day, there's simply no substitution for good interpersonal
+ communication.
+ <footnote>
+ <para>Except, perhaps, a classic Vulcan mind-meld.</para>
+ </footnote>
+ </para>
</sect2>
@@ -2305,11 +2366,11 @@
definitions in groups using the <literal>svn:externals</literal>
property. You can create or modify this property using
<command>svn propset</command> or <command>svn
- propedit</command> (see <xref linkend="svn.advanced.props.why"/>).
- It can be set on any versioned directory,
- and its value is a multi-line table of subdirectories (relative
- to the versioned directory on which the property is set) and
- fully qualified, absolute Subversion repository URLs.</para>
+ propedit</command> (see <xref linkend="svn.advanced.props.manip"
+ />). It can be set on any versioned directory, and its value is
+ a multi-line table of subdirectories (relative to the versioned
+ directory on which the property is set) and fully qualified,
+ absolute Subversion repository URLs.</para>
<screen>
$ svn propget svn:externals calc
More information about the svnbook-dev
mailing list