4.21. Locking


4.21. Locking

Subversion generally works best without locking, using the Copy-Modify-Merge methods described earlier in Section 2.2.3, “The Copy-Modify-Merge Solution”. However there are a few instances when you may need to implement some form of locking policy.

  • You are using unmergeable files, for example, graphics files. If two people change the same file, merging is not possible, so one of you will lose their changes.

  • Your company has always used a locking revision control system in the past and there has been a management decision that locking is best.

Firstly you need to ensure that your Subversion server is upgraded to at least version 1.2. Earlier versions do not support locking at all. If you are using file:// access, then of course only your client needs to be updated.

[Important] The Three Meanings of Lock

In this section, and almost everywhere in this book, the words lock and locking describe a mechanism for mutual exclusion between users to avoid clashing commits. Unfortunately, there are two other sorts of lock with which Subversion, and therefore this book, sometimes needs to be concerned.

The second is working copy locks, used internally by Subversion to prevent clashes between multiple Subversion clients operating on the same working copy. Usually you get these locks whenever a command like update/commit/... is interrupted due to an error. These locks can be removed by running the cleanup command on the working copy, as described in Section 4.16, “Cleanup”.

And third, files and folders can get locked if they're in use by another process, for example if you have a word document opened in Word, that file is locked and can not be accessed by TortoiseSVN.

You can generally forget about these other kinds of locks until something goes wrong that requires you to care about them. In this book, lock means the first sort unless the contrary is either clear from context or explicitly stated.

4.21.1. How Locking Works in Subversion

By default, nothing is locked and anyone who has commit access can commit changes to any file at any time. Others will update their working copies periodically and changes in the repository will be merged with local changes.

If you Get a Lock on a file, then only you can commit that file. Commits by all other users will be blocked until you release the lock. A locked file cannot be modified in any way in the repository, so it cannot be deleted or renamed either, except by the lock owner.

[Important] Important

A lock is not assigned to a specific user, but to a specific user and a working copy. Having a lock in one working copy also prevents the same user from committing the locked file from another working copy.

As an example, imagine that user Jon has a working copy on his office PC. There he starts working on an image, and therefore acquires a lock on that file. When he leaves his office he's not finished yet with that file, so he doesn't release that lock. Back at home Jon also has a working copy and decides to work a little more on the project. But he can't modify or commit that same image file, because the lock for that file resides in his working copy in the office.

However, other users will not necessarily know that you have taken out a lock. Unless they check the lock status regularly, the first they will know about it is when their commit fails, which in most cases is not very useful. To make it easier to manage locks, there is a new Subversion property svn:needs-lock. When this property is set (to any value) on a file, whenever the file is checked out or updated, the local copy is made read-only unless that working copy holds a lock for the file. This acts as a warning that you should not edit that file unless you have first acquired a lock. Files which are versioned and read-only are marked with a special overlay in TortoiseSVN to indicate that you need to acquire a lock before editing.

Locks are recorded by working copy location as well as by owner. If you have several working copies (at home, at work) then you can only hold a lock in one of those working copies.

If one of your co-workers acquires a lock and then goes on holiday without releasing it, what do you do? Subversion provides a means to force locks. Releasing a lock held by someone else is referred to as Breaking the lock, and forcibly acquiring a lock which someone else already holds is referred to as Stealing the lock. Naturally these are not things you should do lightly if you want to remain friends with your co-workers.

Locks are recorded in the repository, and a lock token is created in your local working copy. If there is a discrepancy, for example if someone else has broken the lock, the local lock token becomes invalid. The repository is always the definitive reference.

4.21.2. Getting a Lock

Select the file(s) in your working copy for which you want to acquire a lock, then select the command TortoiseSVNGet Lock....

Figure 4.58. The Locking Dialog

The Locking Dialog

A dialog appears, allowing you to enter a comment, so others can see why you have locked the file. The comment is optional and currently only used with Svnserve based repositories. If (and only if) you need to steal the lock from someone else, check the Steal lock box, then click on OK.

You can set the project property tsvn:logtemplatelock to provide a message template for users to fill in as the lock message. Refer to Section 4.17, “Project Settings” for instructions on how to set properties.

If you select a folder and then use TortoiseSVNGet Lock... the lock dialog will open with every file in every sub-folder selected for locking. If you really want to lock an entire hierarchy, that is the way to do it, but you could become very unpopular with your co-workers if you lock them out of the whole project. Use with care ...

4.21.3. Releasing a Lock

To make sure you don't forget to release a lock you don't need any more, locked files are shown in the commit dialog and selected by default. If you continue with the commit, locks you hold on the selected files are removed, even if the files haven't been modified. If you don't want to release a lock on certain files, you can uncheck them (if they're not modified). If you want to keep a lock on a file you've modified, you have to enable the Keep locks checkbox before you commit your changes.

To release a lock manually, select the file(s) in your working copy for which you want to release the lock, then select the command TortoiseSVNRelease Lock There is nothing further to enter so TortoiseSVN will contact the repository and release the locks. You can also use this command on a folder to release all locks recursively.

4.21.4. Checking Lock Status

Figure 4.59. The Check for Modifications Dialog

The Check for Modifications Dialog

To see what locks you and others hold, you can use TortoiseSVNCheck for Modifications.... Locally held lock tokens show up immediately. To check for locks held by others (and to see if any of your locks are broken or stolen) you need to click on Check Repository.

From the context menu here, you can also get and release locks, as well as breaking and stealing locks held by others.

[Caution] Avoid Breaking and Stealing Locks

If you break or steal someone else's lock without telling them, you could potentially cause loss of work. If you are working with unmergeable file types and you steal someone else's lock, once you release the lock they are free to check in their changes and overwrite yours. Subversion doesn't lose data, but you have lost the team-working protection that locking gave you.

4.21.5. Making Non-locked Files Read-Only

As mentioned above, the most effective way to use locking is to set the svn:needs-lock property on files. Refer to Section 4.17, “Project Settings” for instructions on how to set properties. Files with this property set will always be checked out and updated with the read-only flag set unless your working copy holds a lock.

As a reminder, TortoiseSVN uses a special overlay to indicate this.

If you operate a policy where every file has to be locked then you may find it easier to use Subversion's auto-props feature to set the property automatically every time you add new files. Read Section, “Automatic property setting” for further information.

4.21.6. The Locking Hook Scripts

When you create a new repository with Subversion 1.2 or higher, four hook templates are created in the repository hooks directory. These are called before and after getting a lock, and before and after releasing a lock.

It is a good idea to install a post-lock and post-unlock hook script on the server which sends out an email indicating the file which has been locked. With such a script in place, all your users can be notified if someone locks/unlocks a file. You can find an example hook script hooks/post-lock.tmpl in your repository folder.

You might also use hooks to disallow breaking or stealing of locks, or perhaps limit it to a named administrator. Or maybe you want to email the owner when one of their locks is broken or stolen.

Read Section 3.3, “Server side hook scripts” to find out more.