From the Question Bin: Subversion Locking

Here at CollabNet, we get a fairly constant stream of questions
about Subversion from a wide variety of folks and via several
different communication vehicles (webinar participation, training
sessions, and so on). We try to answer them
all as quickly as possible, but sometimes we wind up with a backlog
of unanswered questions. So, as has
on this blog before,
I’ll try to answer some of those queued up questions, focusing this
time on questions related to Subversion’s locking

First, allow me to try to summarize the locking feature at a high
level. The default version control model employed by Subversion is
the copy-modify-merge
model, where users asynchronously checkout personal working copies of
a versioned directory, modify files inside that directory, and then commit their modifications, only
worrying about conflicting changes made to the same file when they actually occur. Locking
(sometimes referred to as "reserved checkouts") allows
Subversion users to step outside that default model and into the lock-modify-unlock
model, in which multiple users preemptively serialize their commit access to
a given file so that conflicts never occur. This latter model is the
one most often used in systems like Visual SourceSafe. Subversion’s
locking feature accomplishes this by allowing users to claim the
exclusive right to modify a file (and then, later, to relinquish that

Is locking recommended?

The Subversion developers aren’t really in the habit of developing
new features that violate the community’s own recommendations or best
practices, and the locking feature (added in Subversion 1.2) was
definitely something that was intentionally developed. The
question is better phrased as follows: "When is locking
recommended?" To answer that, perhaps a review of the pros and
cons of the two version control models is in order.

Copy-modify-merge is characterized as having very low overhead in
terms of administration and workflow. Everyone can modify files
willy-nilly as they see fit, only dealing with conflicts as they
occur. Unfortunately, when conflicts do occur, the cost of resolving
them varies wildly from no-brainer to i-just-wasted-a-week-of-effort,
depending on the hackability of the file format used by the conflicted

When using lock-modify-unlock, everyone pays the workflow cost of
having to explicitly lock files they wish to edit and unlock them when
their edits are complete. If folks are careless, this can mean that
files are reserved for editing by a particular user for far longer
than necessary, which can be a hindrance to team productivity, and
might require administrative intervention. But on the positive side,
you never have to deal with effort lost due to unresolvable conflicts
because conflicts (which occur when multiple people commit changes to
the same file) cannot occur.

As with so many things in life, a good balance of the two models
generally yields the best results. Subversion’s built-in contextual
change merging algorithm automatically handles most of the situations
where multiple users simultaneously change the same file if that
file’s content is textual or otherwise human-readable. For those
files, using copy-modify-merge (that is, not locking
the files) can save users steps in the workflow, encourage
collaboration, and prevent administrative hassles. But for file types for which the cost
of resolving conflicts is high, such as for non-human-readable file
formats, the overhead of locking and unlocking those files is often less
painful than dealing with conflicts when they happen.

Does Subversion support reserved checkouts?

As previously mentioned, many folks refer to Subversion’s file
locking feature as "reserved checkouts", but it’s not entirely accurate
to do so. In version control systems with reserved checkouts, the
term "checkout" implies not just getting a copy of a
versioned file onto your computer, but also securing the right to
change that file. A reserved checkout is the same thing, except the
modification right you secure is yours exclusively — the file is
read-only for everyone else. This is at odds with Subversion’s use of
the term. In the default case, if you checkout a file from a
Subversion repository, you can modify it, period. Of course, once it
has been modified, you might not be able to commit it, either because
you aren’t authorized to do so, or because your copy of the file is
now out of date, or — of relevance to our topic — because
someone else has locked it.

"But wait a second! If someone else locked the file, why did
Subversion let me waste all that time editing it?"

You can see that a file has been locked by someone else if you run
‘svn status –update’ or run ‘svn info’ on a file’s repository
URL. But Subversion doesn’t persist that information in your working
copy. So there’s always a window between the time you last asked the
server about locks (and decided the file was okay for you to edit) and
the time you committed your changes. Locking the file yourself saves
you from dealing with unresolvable conflicts and wasting your editing
efforts, but doesn’t help your fellow collaborator who is now in the
same situation you were in before.

The best way to deal with this scenario is to make use of a special
Subversion file property — svn:needs-lock. By setting
this property on a file, you are declaring to Subversion that the file
is likely to cause you and your collaborators grief if folks fail to lock the file
before changing it. Files on which the svn:needs-lock
property is set will by default be read-only in your working copy (in
the OS filesystem sense), which should be enough to keep well-behaved
editing software from allowing you to change the file. When you load
the file into your software, and the software complains that the file
is read-only, you’ll be reminded that you need to run ‘svn lock’ to
lock the file. Upon doing so, Subversion will tweak the filesystem
permissions on the working copy file to make it no longer read-only, and you’ll be
able to change the file. Once you commit your changes and release
your lock on the file, Subversion returns it to a read-only state in
your working copy.

As a best practice, I’d recommend carefully evaluating the presence
or absence of the svn:needs-lock property and your desire to
lock a file. If a file doesn’t carry the property, do you really need
to lock it? If you really need to lock the file, would others benefit
by having their copies of the file be read-only due to the presence of
the svn:needs-lock property?

Note that the svn:needs-lock property doesn’t cause Subversion to require a lock on the file when committing. Its only effect is the client-side filesystem read-only bit twiddling stuff. I said earlier that the svn:needs-lock helps out
when you use well-behaved software to edit your files. But if
your software ignores the read-only filesystem bit — or even if you tweak the file’s permission bits by hand — you might never
realize that you failed to lock the file before changing it, and Subversion will happily allow you to commit those changes. (By the way, if you have software that misbehaves like this, consider sending its developers a nastygram!)

Can you lock modules/directories/branches, or only files?

Unfortunately, you can only lock files at this time in

This is unfortunate for more than just the obvious reason. Because
you can’t lock directories, many people perform the obvious workaround
— they lock every file in and under the directory. Ignoring the
question of whether or not this is actually necessary for that
particular set of files, this can have some performance implications
for Subversion. Also, Subversion doesn’t currently guarantee the
atomicity of a locking operation performed on multiple paths —
if the 126th file out of 200 fails to lock for some reason (perhaps
because someone else has it locked), you’re stuck with a partial
collection of locks. To those of you who do this regularly, consider
the fact that ‘svn lock’ doesn’t accept the --recursive
command-line option and that this was not an oversight on the
Subversion developers’ part. If you need to limit access to a whole subtree in Subversion, your best bet is to use normal path-based access control measures.

Can you tell Subversion that you want to use locks for all files?

Yes, you can, but please do read the answers to the previous
questions before deciding on this course. If you think you really
need to do this, there are a couple of ways to do so. First, you can
set the svn:needs-lock property on all your files. (You
might consider using the client-side auto-prop
to do this.) See my previous note about how this won’t force Subversion to require locks on those files, though. Alternatively, you could compose a
pre-commit hook script that checks all the files you changed in your
commit to see that they are locked. (You can trust Subversion to
check that the committing user was the one who actually holds
the locks.)

Can you lock specific file types (all *.doc files, e.g.)?

Sure. See the previous answer, and just limit the scope of your
auto-props or hook-script-based commit validation to the file
types of interest.

C. Michael Pilato

C. Michael Pilato is a core Subversion developer, co-author of Version Control With Subversion (O'Reilly Media), and the primary maintainer of ViewVC. He works remotely from his home state of North Carolina as a software engineer for CollabNet, and has been an active open source developer since early 2001. Mike is a proud husband and father who loves traveling, soccer, spending quality time with his family, and any combination of those things. He also enjoys composing and performing music, and harbors not-so-secret fantasies of rock stardom. Mike has a degree in computer science and mathematics from the University of North Carolina at Charlotte.

Tagged with: , , , , , , , ,
Posted in Subversion
2 comments on “From the Question Bin: Subversion Locking
  1. C. Michael Pilato: Subversion Locking

    C. Michael (Mike) Pilato, one of the main developers of Subversion, answers common questions about Subversion file locking feature.
    The default version control model employed by Subversion is the copy-modify-merge model, where users asynchronously…

  2. erhan elgün says:

    I have read your article but can’t find how to enable file locing. Could you explain how to enable file locking step by step?

Leave a Reply

Your email address will not be published. Required fields are marked *