Locking

I'd like to give you a brief overview of locking functionality from within the Team Foundation source control system. Before we begin, however, I'd like to note that the lock command should be differentiated from the permission command. lock is used to temporarily prevent access to a file or folder while permission can be used to set persistent access permissions.

There are two types of locks. The weaker of the two is a checkin lock which prevents other users from checking in changes to the locked files. The stronger lock is a checkout lock which prevents users from pending changes, such as checkout, delete, and rename, to the locked files in their workspaces. A checkout lock cannot be granted if there are currently any pending changes by other users on the items to lock. In addition, only one user at a time may hold a lock on a given file or folder.

A checkout lock may be more useful when refactoring code or performing high priority maintenance. A checkin lock, on the other hand, allows other users to continue working with the locked files, though the user with the lock is guaranteed to apply their changes first for as long as the lock is in place. Thus, checkout locks fully serialize changes by allowing only the lock holder to work on the locked item while checkin locks only prevent others from checking in any changes they make.

A lock may be filed either as its own operation or as part of several other operations. The commands rename, checkout, delete, undelete, merge, branch, and add all have the option to lock as part of the operation. For add and branch, the lock is placed on the namespace where the new item will be created. Locks placed with rename apply both to the old and new namespaces.

Locks on folders are implicitly recursive. If a parent folder is locked, there is no need to lock its children unless a more restrictive lock is required. Conversely, unlocking a child causes the child to have the same locking level as its parent.

Since locks are used to control checkin and checkout activity on an item regardless of version, locks on an item apply to the item itself and not a specific version of the item.

An item becomes unlocked either when the user explicitly unlocks it or when the user's pending changes on that item are checked in. It is also possible for administrators with the UnlockOther permission to remove a lock placed by another user.

Here are a few examples demonstrating how to use the command line lock functionality. Note that you can use either the local or server path to specify files and folders. See Jason's post on maps and cloaks for more on mappings between the local drive and the respository.

To lock a file for checkout:

tf lock /lock:checkout Shuttle.cs

To lock a folder for checkin:

tf lock /lock:checkin src\3d_engine\

To unlock a file:

tf lock /lock:none $/UniverseExplorer/src/Galaxy.cs

To unlock all files locked by the current user in a given directory tree:

tf lock /lock:none /recursive src\renderer\