| A UI Specification for "Locking" |
| |
| This document describes a user interface of a new locking system for |
| Subversion. It implements the set of features described in the |
| associated functional spec. |
| |
| I. Introduction |
| |
| A. Goals/Audience |
| |
| There are two audiences we need to consider for a locking UI: |
| |
| 1. The enlightened software developer |
| |
| - understands general VC concepts (required for job) |
| - understands concurrency model |
| - has already embraced Subversion (or at least CVS) |
| |
| - ITCH: Some files aren't mergeable, like image files or |
| spreadsheets. Need to force serialized edits on such |
| things, as an occasional exception to concurrency. |
| |
| 2. The reluctant user of version control |
| |
| - bright people, but no time or interest in learning VC concepts |
| - doesn't understand concurrency |
| - doesn't understand "out-of-dateness" or merging procedures |
| |
| - typical examples: |
| - coder who has only used VSS or Clearcase with 100% locking |
| - website developer being forced to use VC |
| - manager being forced to use VC |
| |
| - ITCH: VC system should be effortless, transparent, and |
| idiot proof. VC system should prevent people from |
| wasting editing time, destroying each others |
| changes, all while avoiding concurrency concepts such |
| as "merging" and "out of dateness". |
| |
| |
| B. The "Hijack" Scenario |
| |
| This is specific use-case which is particularly important to |
| making version control usable by the second type of user |
| described above. |
| |
| In this scenario, the user has a tool that circumvents whatever |
| system is in place to enforce serialized editing. In systems |
| like VSS or Clearcase 'copy' views, this usually means an |
| editor that ignores the read-only attribute on a file. When |
| the user goes to commit, they discover that they were supposed |
| to lock the file, and the repository version has changed. What |
| now? |
| |
| The power-svn user would certainly have no problem knowing what |
| to do seeing an error that "the file must be locked to commit", |
| nor would such a user be confused by seeing a subsequent error |
| that the "file is out-of-date". The power user would run 'svn |
| update', resolve conflicts, then lock the file and commit. |
| |
| But the reluctant or ignorant svn user shouldn't (and doesn't |
| need to) be forced to deal with merging and out-of-dateness |
| when working in an "all locking" environment. Here are a few |
| usability case-studies: |
| |
| - Clearcase dynamic views |
| |
| The workspace is always up-to-date, all of the time. And |
| it's impossible to circumvent the read-only bit. So the |
| hijack scenario can't happen at all. |
| |
| - Clearcase copy-based views |
| |
| In the hijack scenario, the user attempts to commit and |
| the client responds by attempting an interactive |
| contextual merge. If not possible, the whole commit |
| fails and a guru is phoned to fix the situation. |
| |
| - Visual Source Safe |
| |
| in the hijack scenario, the user remembers to lock the |
| file long after editing it; VSS asks whether to use the |
| server version or local version of the file. Somebody's |
| edits are lost. |
| |
| It is the recommendation of this document that the command line |
| client produce normal conflicts when 'svn up' is run on a |
| hijacked file; but that for a GUI such as TortoiseSVN, a more |
| friendly (or interactive) procedure is followed -- perhaps one |
| that allows the user to choose between versions of files. |
| |
| |
| II. New Client Behaviors |
| |
| A. Overview |
| |
| This section describes a user interface to accomplish "locking", |
| as described in the functional spec. A new property is used to |
| enforce locking and prevent people from wasting time; lock |
| tokens are objects, stored in the working copy, that represent a |
| lock; and two new subcommands (lock/unlock) are described. |
| |
| B. The "svn:needs-lock" property |
| |
| Create a new "svn:needs-lock" property to indicate that a file |
| should be locked before committing. Just like "svn:executable", |
| the value of the property is irrelevant and the property can be |
| created (or deleted) by any user or administrator. |
| |
| Note that this property doesn't enforce locking. |
| |
| When the Subversion client encounters the "svn:needs-lock" |
| property on a path (on checkout or update), it sets the |
| working-copy path to a read-only state by default. This |
| serves as a reminder to the user that she should lock this |
| path before editing it. When a user locks the path, the |
| Subversion client makes the working-copy path read-write. |
| When the user releases the lock, or if the lock is found to |
| be defunct (see next section), the Subversion client makes |
| the path read-only again. |
| |
| C. Lock manipulation via client |
| |
| 1. Lock Tokens |
| |
| When a user successfully locks a path, the working copy |
| receives a "lock token" from the server. This token is an |
| object that connects your exclusive right to commit to a path |
| with your working copy. |
| |
| You can think of a lock token as a form of authentication for |
| a certain working copy. Why is it important or useful for |
| lock tokens to be attached to only one working copy? |
| |
| [An example: you might lock an unmergeable file using a |
| computer at your office, perhaps as part of a changeset in |
| progress. It should not be possible for a working copy on |
| your home computer to accidentally commit a change to that |
| same file, just because you've authenticated as the user |
| which owns the lock. If you really want to change the file |
| from home, you'd have to "steal" the lock from your other |
| working copy, which is discussed later in this document.] |
| |
| Because locks can be broken or stolen, it is possible for a |
| lock token to become "defunct". A defunct lock cannot be |
| used or released--it is useless and is cleaned up when you |
| next run 'svn update'. |
| |
| 2. New client subcommands |
| |
| Summary: |
| |
| svn lock [--force]: lock (or steal) |
| svn unlock [--force]: release (or break) |
| |
| |
| a. Creating a lock |
| |
| To lock a path, use the 'svn lock' command: |
| |
| $ svn lock foo.c |
| username: harry |
| password: XXXXX |
| [...] |
| 'foo.c' locked by user 'harry'. |
| |
| In order for this command to work, |
| |
| - You *must* provide a username to the server. |
| 'anonymous' locks are not allowed. |
| - The path must not already be locked. |
| - The path must not be out-of-date. |
| |
| The lock command accepts -m or -F to add a lock comment, so |
| others can see why the file was locked. The lock comment |
| is optional. |
| |
| b. Using a lock |
| |
| A lock can be used to make an exclusive commit to a path. |
| Also, if you have a lock, you can opt to "release" |
| (destroy) it when you're done. |
| |
| 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 token |
| |
| If either of these forms of authentication are missing or |
| incorrect, the lock cannot be used. |
| |
| 1. Using a lock to Commit |
| |
| $ svn commit foo.c |
| |
| Upon successful commit, a locked path is released by |
| default. The Subversion client provides an option to |
| retain the lock after commit: |
| |
| $ svn commit foo.c --no-unlock |
| |
| If --no-unlock is not specified, even unmodified files |
| will be considered part of the commit and shown to the |
| user in the list of files to commit. Such files will |
| also be unlocked after the commit. |
| |
| 2. Releasing a lock |
| |
| $ svn unlock foo.c |
| Lock on 'foo.c' has been released. |
| |
| After successful release, the working copy's lock token |
| is gone. |
| |
| 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. |
| |
| Use the --force option to the unlock subcommand to |
| break a lock. For example: |
| |
| $ svn unlock foo.c |
| username: sally |
| password: XXXX |
| svn: error: 'foo.c' is locked by user 'harry'. |
| |
| $ svn unlock foo.c --force |
| username: sally |
| password: XXXX |
| Lock on 'foo.c' has been broken. |
| |
| The --force option also accepts a URL, so that the lock |
| can be |
| released without a working copy. |
| |
| d. Stealing a lock |
| |
| "Stealing" a lock is a means of creating a lock when: |
| |
| - The path is locked by you, but you don't have a |
| representation of the lock in your current working |
| copy, or |
| - The path is locked by someone else. |
| |
| In order to steal a lock, a user must be authenticated to |
| the server. |
| |
| Use the --force option to the lock command to steal a |
| lock. For example: |
| |
| $ svn lock foo.c |
| username: sally |
| password: XXXX |
| svn: error: 'foo.c' is locked by user 'harry'. |
| |
| $ svn lock foo.c --force |
| username: sally |
| password: XXXX |
| 'foo.c' locked by user 'sally'. |
| |
| Remember that the 'svn lock' command still requires that the |
| target be up-to-date to succeed. |
| |
| |
| e. Discovering/examining locks |
| |
| 1. seeing lock tokens in a working copy |
| |
| 'svn status' considers a lock token "interesting", and |
| displays it using some new symbol, in a new column: |
| |
| $ svn status |
| M foo.c |
| M K bar.c |
| A baz.c |
| |
| Note that K (locKed) is used instead of the more |
| intuitive L, since L is already in use for another purpose. |
| |
| 2. seeing locks in a repository. |
| |
| 'svn status -u' adds out-of-date information from the |
| server; in a similar manner, this command shows any |
| locks that exist on the server: |
| |
| $ svn status -u |
| M foo.c |
| M K bar.c |
| A * baz.c |
| * file1 |
| O file2 |
| M B file3 |
| M T file42 |
| |
| As with "svn status", the sixth column indicates lock |
| state. The letters have the following meanings: |
| ' ': No lock in either WC or repository. |
| 'K': Locked in the WC and lock token valid in |
| repository. |
| 'O': No lock in WC, lock in repository. (Locked in |
| Other WC.) |
| 'B': Lock in WC, but no lock in repository. (Lock |
| Broken.) |
| 'T': Locked in WC, but locked with another token in |
| repository. (Lock was sTolen.) |
| |
| 3. 'svn info', describes the attributes of a lock-token, |
| if attached to a working object. If invoked on a URL, |
| it displays information about any remote lock |
| attached. |
| |
| $ svn info foo.c |
| Path: foo.c |
| Name: foo.c |
| URL: http://..../ |
| [...] |
| Lock Token: 465610b1-33eb-0310-8a02-cae41507c13a |
| Lock Owner: lundblad |
| Lock Comment: Refactoring. |
| Lock Creation Date: 2004-12-14 14:49:36 +0100 (Tue, 14 Dec 2004) |
| |
| |
| $ svn info http://host/repos/file2 |
| Path: /file2 |
| Name: file2 |
| URL: http://..../ |
| [...] |
| Lock Token: 465610b1-33eb-0310-8a02-cae41507c13b |
| Lock Owner: fitz |
| Lock Comment: Don't touch my file! |
| Lock Creation Date: 2004-12-25 14:49:36 +0100 (Tue, 14 Dec 2004) |
| |
| 4. 'svn update' changes |
| |
| At the start of an update, the client reports any |
| lock-tokens to the server. If a lock token has become |
| "defunct", the client is instructed to destroy the lock |
| token. |
| |
| A new column will be added to the update output to indicate |
| removed lock tokens: |
| |
| svn up |
| U path1 |
| U path2 |
| B path3 |
| C B path4 |
| |
| In the above example, lock tokens for path3 and path4 |
| were removed. Note that 'B' is used even if there is |
| a new lock in the repository. |
| |
| III. New Server Behaviors |
| |
| A. Overview |
| |
| This section describes new server UIs for locking: two new hook |
| scripts, a new 'svnlook' subcommand, and a new 'svnadmin' subcommand. |
| |
| 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. |
| |
| C. Enforcement |
| |
| During a commit, the server checks for locks the same way that |
| it checks for out-of-dateness: |
| |
| $ svn commit |
| Sending foo.c |
| Sending bar.c |
| svn: error: 'bar.c' is locked by user 'harry'. |
| |
| |
| D. Configurable Mechanisms |
| |
| 1. New "pre-" hook scripts |
| |
| a. pre-lock |
| |
| Used to authorize lock creation. Invoked whenever a user |
| creates a lock ('svn lock') or steals a lock ('svn lock |
| --force'). If an administrator wants the locking feature |
| completely disabled, just set this hook to always return failure. |
| |
| - input: REPOS, PATH, USER |
| - successful exit means lock is allowed, else deny lock creation. |
| - if path is already locked, hook script can deduce |
| that USER is "stealing" the lock and decide what to do. |
| |
| b. pre-unlock |
| |
| Used to authorize lock releasing. Invoked whenever a user |
| releases a lock ('svn unlock) or breaks a lock ('svn |
| unlock' --force). |
| |
| - input: REPOS, PATH, USER |
| - successful exit means release is allowed, else deny. |
| - if path is already locked, hook script can deduce |
| that USER is "breaking" the lock and decide what to do. |
| |
| 2. New "post-" hook scripts |
| |
| a. post-lock |
| |
| Used to report lock creation. Invoked whenever a user |
| creates a lock ('svn lock') or steals a lock ('svn lock |
| --force'). |
| |
| - input: REPOS, PATH, USER |
| - exit code ignored |
| - can be used to send email, collect statistics, etc. |
| |
| b. post-unlock |
| |
| Used to report lock release. Invoked whenever a user |
| releases a lock ('svn unlock') or breaks a lock ('svn unlock |
| --force'). |
| |
| - input: REPOS, PATH, USER |
| - exit code ignored |
| - can be used to send email, collect statistics, etc. |
| |
| |
| E. Lock manipulation with svnadmin |
| |
| 1. Discovering locks |
| |
| A new 'svnlook listlocks' subcommand shows all current locks |
| in a repository: |
| |
| $ svnlook listlocks /usr/local/svn/repos |
| # harry Aug 16 15:13 /trunk/bar.c |
| # sally Sep 07 09:30 /trunk/doc/foo.doc |
| |
| |
| 2. Unconditional release of locks |
| |
| A new 'svnadmin unlock' subcommand to unconditionally |
| release a lock. Note that this command circumvents hook |
| scripts, much like other svnadmin actions: |
| |
| $ svnadmin unlock /usr/local/svn/repos /trunk/doc/foo.doc |
| Lock on '/trunk/doc/foo.doc' has been released. |
| |
| |
| |
| |
