A Functional Specification for "Locking" This document describes the features of a new locking system for Subversion. It attempts to avoid specific design and implementation choices wherever possible. A separate document will outline a proposed implementation for this specification. I. Introduction A. Goals 1. Provide a mechanism to ensure that a user has exclusive rights to commit changes to a file from a particular working copy. 2. Provide a communication mechanism to decrease the chances of a user wasting time working on a file locked by someone else. B. Summary We recommend implementing a lightweight locking mechanism. Teach the server to track and enforce exclusive write locks. Provide means for repository administrators to manipulate locks and enforce locking policies. Provide a series of client commands for creating, removing, breaking, and stealing locks. Lastly, create a new property to communicate that a path must be locked before committing. Note that Subversion is still an inherently concurrent system. The ability to lock paths is optional, and can even be prevented by the repository administrator. II. New Client Behaviors A. Overview 1. Definition of "lock" A lock grants one user the exclusive right to change a certain file from a specific working copy. 2. Lock restrictions If a file is locked, the owner of the lock has the exclusive right to change the file's text and properties, to delete the file, and to move the file. The restriction on moving or deleting a locked file is a restriction on changing its full path name in any way, including by moving or renaming or deleting any of its parent directories. (A locked file can still be read and copied, and any copy of it will not automatically be locked.) B. Client requirements for locking 1. Enforcement system It must be possible to declare that certain files absolutely require locks before committing. 2. Communication system There must be a system in place that tells users when locking is necessary; ideally, it would prevent a user from beginning work in the first place. If a lock already exists, a user should be able to see who created it, when, and why. C. Lock manipulation via client 1. Lock Representations in the Working Copy In order to associate a lock with a particular working copy, the working copy must store some representation of the lock, and occasionally synchronize this with the repository's master list of locks. Because locks can be broken or stolen, it is possible for a working copy's lock representation to become "defunct". A defunct lock cannot be used or released--it is useless and is cleaned up when the client next synchronizes with the server. 2. Actions This section defines specific terminology to describe the kind of lock-related actions that a Subversion client can perform. a. Creating a lock To lock a file: - A user must be authenticated to the server - The file must not already be locked. Upon successfully locking a file, the working copy retains a representation of the lock. b. Using a lock To make use of a lock, two forms of authentication must be provided to the server: - The authenticated username that owns the lock - A non-defunct lock representation If either of these forms of authentication are missing or incorrect, the lock cannot be used. 1. Using a lock to Commit Upon successful commit, a locked file is released by default. The Subversion client provides an option to retain the lock after commit. 2. Releasing a lock After successful release, the representation of the lock is removed from both the working copy and the server. c. Breaking a lock "Breaking" a lock is a means of releasing a lock when: - The authenticated username is not the same as the lock owner, or - The working-copy lock representation is unavailable. (e.g. Harry locks file foo and is suddenly laid off. Sally decides to clean up his mess and breaks the lock on foo, without using Harry's username or lock representation.) d. Stealing a lock "Stealing" a lock is a means of creating a lock when: - The file is locked by you, but you don't have a representation of the lock in your current working copy, or - The file is locked by someone else. In order to steal a lock, a user must be authenticated to the server. (e.g. Harry locks file foo and goes on vacation. Sally needs to make changes to foo and obtains a lock on foo by stealing Harry's lock, without using Harry's username or lock representation.) e. Discovering/examining locks The Subversion client provides interfaces to answer the following questions: - Ask working copy to display all lock representations - Examine a particular lock representation - Ask server to list all locks underneath a given path, optionally displaying all attributes of the locks (Possibly able to restrict this query to a single user) - Ask server whether a given file is locked III. New Server Behaviors A. Overview 1. Definition of a lock As noted in section II.A.1, a lock grants one user the exclusive right to change a certain file from a specific working copy. 2. Attributes of a lock A lock is an immutable data object. It must contain: a unique identifier, the path being locked, the username that owns the lock, and a creation timestamp. A lock comment is optional. 3. Lock Restrictions See II.A.2 for details. The server will enforce these behaviors. B. Tracking locks The Subversion server holds the master list of all locks for a repository. It responds to client requests to create, release, break and steal locks. When a client asks about a lock, the server reports whether the lock is valid or is defunct (i.e. the server no longer has a lock corresponding to the lock representation in question). When a client creates or steals a lock, the server returns a lock representation. C. Enforcement During a commit, the server checks for locks the same way that it checks for out-of-dateness. As each changed path arrives, the server checks to see if the path is locked. If the path is locked, the server makes certain that the correct username and lock representation have been presented by the client. If not, the entire commit is rejected immediately. In addition, the server re-checks and enforces locks during commit finalization. D. Configurable Mechanisms The server provides mechanisms to enable diverse administrative locking policies, including: 1. Allow or disallow creating, breaking, and stealing of locks based on specific criteria (e.g. username, path, etc.) 2. Perform tasks after creating, breaking, and stealing a lock (e.g. sending email, collecting stats, etc.) E. Lock manipulation with svnadmin 1. Discovering locks svnadmin provides interfaces to answer the following questions: - List all locks in a repository underneath a given path (Possibly able to restrict this query to a single user) - Ask whether a given repository file is locked 2. Unconditional release of locks svnadmin provides an interface to unconditionally release a specific lock.