| blob | f0c8d7440740e62b4e1242440e7bdbdf5c29bfeb |
1 A UI Specification for "Locking"
3 This document describes a user interface of a new locking system for
4 Subversion. It implements the set of features described in the
5 associated functional spec.
7 I. Introduction
9 A. Goals/Audience
11 There are two audiences we need to consider for a locking UI:
13 1. The enlightened software developer
15 - understands general VC concepts (required for job)
16 - understands concurrency model
17 - has already embraced Subversion (or at least CVS)
19 - ITCH: Some files aren't mergeable, like image files or
20 spreadsheets. Need to force serialized edits on such
21 things, as an occasional exception to concurrency.
23 2. The reluctant user of version control
25 - bright people, but no time or interest in learning VC concepts
26 - doesn't understand concurrency
27 - doesn't understand "out-of-dateness" or merging procedures
29 - typical examples:
30 - coder who has only used VSS or Clearcase with 100% locking
31 - website developer being forced to use VC
32 - manager being forced to use VC
34 - ITCH: VC system should be effortless, transparent, and
35 idiot proof. VC system should prevent people from
36 wasting editing time, destroying each others
37 changes, all while avoiding concurrency concepts such
38 as "merging" and "out of dateness".
41 B. The "Hijack" Scenario
43 This is specific use-case which is particularly important to
44 making version control usable by the second type of user
45 described above.
47 In this scenario, the user has a tool that circumvents whatever
48 system is in place to enforce serialized editing. In systems
49 like VSS or Clearcase 'copy' views, this usually means an
50 editor that ignores the read-only attribute on a file. When
51 the user goes to commit, they discover that they were supposed
52 to lock the file, and the repository version has changed. What
53 now?
55 The power-svn user would certainly have no problem knowing what
56 to do seeing an error that "the file must be locked to commit",
57 nor would such a user be confused by seeing a subsequent error
58 that the "file is out-of-date". The power user would run 'svn
59 update', resolve conflicts, then lock the file and commit.
61 But the reluctant or ignorant svn user shouldn't (and doesn't
62 need to) be forced to deal with merging and out-of-dateness
63 when working in an "all locking" environment. Here are a few
64 usability case-studies:
66 - Clearcase dynamic views
68 The workspace is always up-to-date, all of the time. And
69 it's impossible to circumvent the read-only bit. So the
70 hijack scenario can't happen at all.
72 - Clearcase copy-based views
74 In the hijack scenario, the user attempts to commit and
75 the client responds by attempting an interactive
76 contextual merge. If not possible, the whole commit
77 fails and a guru is phoned to fix the situation.
79 - Visual Source Safe
81 in the hijack scenario, the user remembers to lock the
82 file long after editing it; VSS asks whether to use the
83 server version or local version of the file. Somebody's
84 edits are lost.
86 It is the recommendation of this document that the command line
87 client produce normal conflicts when 'svn up' is run on a
88 hijacked file; but that for a GUI such as TortoiseSVN, a more
89 friendly (or interactive) procedure is followed -- perhaps one
90 that allows the user to choose between versions of files.
93 II. New Client Behaviors
95 A. Overview
97 This section describes a user interface to accomplish "locking",
98 as described in the functional spec. A new property is used to
99 enforce locking and prevent people from wasting time; lock
100 tokens are objects, stored in the working copy, that represent a
101 lock; and two new subcommands (lock/unlock) are described.
103 B. The "svn:needs-lock" property
105 Create a new "svn:needs-lock" property to indicate that a file
106 should be locked before committing. Just like "svn:executable",
107 the value of the property is irrelevant and the property can be
108 created (or deleted) by any user or administrator.
110 Note that this property doesn't enforce locking.
112 When the Subversion client encounters the "svn:needs-lock"
113 property on a path (on checkout or update), it sets the
114 working-copy path to a read-only state by default. This
115 serves as a reminder to the user that she should lock this
116 path before editing it. When a user locks the path, the
117 Subversion client makes the working-copy path read-write.
118 When the user releases the lock, or if the lock is found to
119 be defunct (see next section), the Subversion client makes
120 the path read-only again.
122 C. Lock manipulation via client
124 1. Lock Tokens
126 When a user successfully locks a path, the working copy
127 receives a "lock token" from the server. This token is an
128 object that connects your exclusive right to commit to a path
129 with your working copy.
131 You can think of a lock token as a form of authentication for
132 a certain working copy. Why is it important or useful for
133 lock tokens to be attached to only one working copy?
135 [An example: you might lock an unmergeable file using a
136 computer at your office, perhaps as part of a changeset in
137 progress. It should not be possible for a working copy on
138 your home computer to accidentally commit a change to that
139 same file, just because you've authenticated as the user
140 which owns the lock. If you really want to change the file
141 from home, you'd have to "steal" the lock from your other
142 working copy, which is discussed later in this document.]
144 Because locks can be broken or stolen, it is possible for a
145 lock token to become "defunct". A defunct lock cannot be
146 used or released--it is useless and is cleaned up when you
147 next run 'svn update'.
149 2. New client subcommands
151 Summary:
153 svn lock [--force]: lock (or steal)
154 svn unlock [--force]: release (or break)
157 a. Creating a lock
159 To lock a path, use the 'svn lock' command:
161 $ svn lock foo.c
162 username: harry
163 password: XXXXX
164 [...]
165 'foo.c' locked by user 'harry'.
167 In order for this command to work,
169 - You *must* provide a username to the server.
170 'anonymous' locks are not allowed.
171 - The path must not already be locked.
172 - The path must not be out-of-date.
174 The lock command accepts -m or -F to add a lock comment, so
175 others can see why the file was locked. The lock comment
176 is optional.
178 b. Using a lock
180 A lock can be used to make an exclusive commit to a path.
181 Also, if you have a lock, you can opt to "release"
182 (destroy) it when you're done.
184 To make use of a lock, two forms of authentication must be
185 provided to the server:
187 - The authenticated username that owns the lock
188 - A non-defunct lock token
190 If either of these forms of authentication are missing or
191 incorrect, the lock cannot be used.
193 1. Using a lock to Commit
195 $ svn commit foo.c
197 Upon successful commit, a locked path is released by
198 default. The Subversion client provides an option to
199 retain the lock after commit:
201 $ svn commit foo.c --no-unlock
203 If --no-unlock is not specified, even unmodified files
204 will be considered part of the commit and shown to the
205 user in the list of files to commit. Such files will
206 also be unlocked after the commit.
208 2. Releasing a lock
210 $ svn unlock foo.c
211 Lock on 'foo.c' has been released.
213 After successful release, the working copy's lock token
214 is gone.
216 c. Breaking a lock
218 "Breaking" a lock is a means of releasing a lock when:
220 - The authenticated username is not the same as the
221 lock owner, or
222 - The working-copy lock representation is unavailable.
224 Use the --force option to the unlock subcommand to
225 break a lock. For example:
227 $ svn unlock foo.c
228 username: sally
229 password: XXXX
230 svn: error: 'foo.c' is locked by user 'harry'.
232 $ svn unlock foo.c --force
233 username: sally
234 password: XXXX
235 Lock on 'foo.c' has been broken.
237 The --force option also accepts a URL, so that the lock
238 can be
239 released without a working copy.
241 d. Stealing a lock
243 "Stealing" a lock is a means of creating a lock when:
245 - The path is locked by you, but you don't have a
246 representation of the lock in your current working
247 copy, or
248 - The path is locked by someone else.
250 In order to steal a lock, a user must be authenticated to
251 the server.
253 Use the --force option to the lock command to steal a
254 lock. For example:
256 $ svn lock foo.c
257 username: sally
258 password: XXXX
259 svn: error: 'foo.c' is locked by user 'harry'.
261 $ svn lock foo.c --force
262 username: sally
263 password: XXXX
264 'foo.c' locked by user 'sally'.
266 Remember that the 'svn lock' command still requires that the
267 target be up-to-date to succeed.
270 e. Discovering/examining locks
272 1. seeing lock tokens in a working copy
274 'svn status' considers a lock token "interesting", and
275 displays it using some new symbol, in a new column:
277 $ svn status
278 M foo.c
279 M K bar.c
280 A baz.c
282 Note that K (locKed) is used instead of the more
283 intuitive L, since L is already in use for another purpose.
285 2. seeing locks in a repository.
287 'svn status -u' adds out-of-date information from the
288 server; in a similar manner, this command shows any
289 locks that exist on the server:
291 $ svn status -u
292 M foo.c
293 M K bar.c
294 A * baz.c
295 * file1
296 O file2
297 M B file3
298 M T file42
300 As with "svn status", the sixth column indicates lock
301 state. The letters have the following meanings:
302 ' ': No lock in either WC or repository.
303 'K': Locked in the WC and lock token valid in
304 repository.
305 'O': No lock in WC, lock in repository. (Locked in
306 Other WC.)
307 'B': Lock in WC, but no lock in repository. (Lock
308 Broken.)
309 'T': Locked in WC, but locked with another token in
310 repository. (Lock was sTolen.)
312 3. 'svn info', describes the attributes of a lock-token,
313 if attached to a working object. If invoked on a URL,
314 it displays information about any remote lock
315 attached.
317 $ svn info foo.c
318 Path: foo.c
319 Name: foo.c
320 URL: http://..../
321 [...]
322 Lock Token: 465610b1-33eb-0310-8a02-cae41507c13a
323 Lock Owner: lundblad
324 Lock Comment: Refactoring.
325 Lock Creation Date: 2004-12-14 14:49:36 +0100 (Tue, 14 Dec 2004)
328 $ svn info http://host/repos/file2
329 Path: /file2
330 Name: file2
331 URL: http://..../
332 [...]
333 Lock Token: 465610b1-33eb-0310-8a02-cae41507c13b
334 Lock Owner: fitz
335 Lock Comment: Don't touch my file!
336 Lock Creation Date: 2004-12-25 14:49:36 +0100 (Tue, 14 Dec 2004)
338 4. 'svn update' changes
340 At the start of an update, the client reports any
341 lock-tokens to the server. If a lock token has become
342 "defunct", the client is instructed to destroy the lock
343 token.
345 A new column will be added to the update output to indicate
346 removed lock tokens:
348 svn up
349 U path1
350 U path2
351 B path3
352 C B path4
354 In the above example, lock tokens for path3 and path4
355 were removed. Note that 'B' is used even if there is
356 a new lock in the repository.
358 III. New Server Behaviors
360 A. Overview
362 This section describes new server UIs for locking: two new hook
363 scripts, a new 'svnlook' subcommand, and a new 'svnadmin' subcommand.
365 B. Tracking locks
367 The Subversion server holds the master list of all locks for a
368 repository. It responds to client requests to create, release,
369 break and steal locks.
371 C. Enforcement
373 During a commit, the server checks for locks the same way that
374 it checks for out-of-dateness:
376 $ svn commit
377 Sending foo.c
378 Sending bar.c
379 svn: error: 'bar.c' is locked by user 'harry'.
382 D. Configurable Mechanisms
384 1. New "pre-" hook scripts
386 a. pre-lock
388 Used to authorize lock creation. Invoked whenever a user
389 creates a lock ('svn lock') or steals a lock ('svn lock
390 --force'). If an administrator wants the locking feature
391 completely disabled, just set this hook to always return failure.
393 - input: REPOS, PATH, USER
394 - successful exit means lock is allowed, else deny lock creation.
395 - if path is already locked, hook script can deduce
396 that USER is "stealing" the lock and decide what to do.
398 b. pre-unlock
400 Used to authorize lock releasing. Invoked whenever a user
401 releases a lock ('svn unlock) or breaks a lock ('svn
402 unlock' --force).
404 - input: REPOS, PATH, USER
405 - successful exit means release is allowed, else deny.
406 - if path is already locked, hook script can deduce
407 that USER is "breaking" the lock and decide what to do.
409 2. New "post-" hook scripts
411 a. post-lock
413 Used to report lock creation. Invoked whenever a user
414 creates a lock ('svn lock') or steals a lock ('svn lock
415 --force').
417 - input: REPOS, PATH, USER
418 - exit code ignored
419 - can be used to send email, collect statistics, etc.
421 b. post-unlock
423 Used to report lock release. Invoked whenever a user
424 releases a lock ('svn unlock') or breaks a lock ('svn unlock
425 --force').
427 - input: REPOS, PATH, USER
428 - exit code ignored
429 - can be used to send email, collect statistics, etc.
432 E. Lock manipulation with svnadmin
434 1. Discovering locks
436 A new 'svnlook listlocks' subcommand shows all current locks
437 in a repository:
439 $ svnlook listlocks /usr/local/svn/repos
440 # harry Aug 16 15:13 /trunk/bar.c
441 # sally Sep 07 09:30 /trunk/doc/foo.doc
444 2. Unconditional release of locks
446 A new 'svnadmin unlock' subcommand to unconditionally
447 release a lock. Note that this command circumvents hook
448 scripts, much like other svnadmin actions:
450 $ svnadmin unlock /usr/local/svn/repos /trunk/doc/foo.doc
451 Lock on '/trunk/doc/foo.doc' has been released.