| blob | 638a8396a93fcd8c3745e996359a5daa6e8a8628 |
1 ;;; vc.el --- drive a version-control system from within Emacs
3 ;; Copyright (C) 1992 Free Software Foundation, Inc.
5 ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
6 ;; Version: 5.0
8 ;; $Id: vc.el,v 1.22 1993/03/07 18:20:54 eggert Exp eric $
10 ;; This file is part of GNU Emacs.
12 ;; GNU Emacs is free software; you can redistribute it and/or modify
13 ;; it under the terms of the GNU General Public License as published by
14 ;; the Free Software Foundation; either version 2, or (at your option)
15 ;; any later version.
17 ;; GNU Emacs is distributed in the hope that it will be useful,
18 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 ;; GNU General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with GNU Emacs; see the file COPYING. If not, write to
24 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
26 ;;; Commentary:
28 ;; This was designed and implemented by Eric Raymond <esr@snark.thyrsus.com>.
29 ;; Paul Eggert <eggert@twinsun.com>, Sebastian Kremer <sk@thp.uni-koeln.de>,
30 ;; and Richard Stallman contributed valuable criticism, support, and testing.
31 ;;
32 ;; Supported version-control systems presently include SCCS and RCS;
33 ;; your RCS version should be 5.6.2 or later for proper operation of
34 ;; the lock-breaking code.
35 ;;
36 ;; The RCS code assumes strict locking. You can support the RCS -x option
37 ;; by adding pairs to the vc-master-templates list.
38 ;;
39 ;; Proper function of the SCCS diff commands requires the shellscript vcdiff
40 ;; to be installed somewhere on Emacs's path for executables.
41 ;;
42 ;; This code depends on call-process passing back the subprocess exit
43 ;; status. Thus, you need Emacs 18.58 or later to run it.
44 ;;
45 ;; The vc code maintains some internal state in order to reduce expensive
46 ;; version-control operations to a minimum. Some names are only computed
47 ;; once. If you perform version control operations with RCS/SCCS/CVS while
48 ;; vc's back is turned, or move/rename master files while vc is running,
49 ;; vc may get seriously confused. Don't do these things!
50 ;;
51 ;; Developer's notes on some concurrency issues are included at the end of
52 ;; the file.
54 ;;; Code:
58 ;; General customization
61 "*Back-end actually used by this interface; may be SCCS or RCS.
79 ;;;###autoload
83 ;; Header-insertion hair
91 "*Associate static header string templates with file types. A \%s in the
92 template is replaced with the first string associated with the file's
96 "*Special comment delimiters to be used in generating vc headers only.
97 Add an entry in this list if you need to override the normal comment-start
98 and comment-end variables. This will only be necessary if the mode language
101 ;; Variables the user doesn't need to know about.
115 ;; File property caching
118 ;; clear all properties of a given file
121 ;; Random helper functions
124 "Return the master name of a file, nil if it is not registered"
133 "Look for a command anywhere on the subprocess-command search path."
141 exec-path))
144 full)))
147 "Execute a version-control command, notifying user and checking for errors.
148 The command is successful if its exit status does not exceed OKSTATUS.
149 Output from COMMAND goes to buffer *vc*. The last argument of the command is
150 the master name of FILE; this is appended to an optional list of FLAGS."
157 status)
161 ;; This is so that command arguments typed in the *vc* buffer will
162 ;; have reasonable defaults.
167 flags)
173 )
187 status))
188 )
191 )
193 status)
194 )
196 ;;; Save a bit of the text around POSN in the current buffer, to help
197 ;;; us find the corresponding position again later. This works even
198 ;;; if all markers are destroyed or corrupted.
205 ;;; Return the position of CONTEXT in the current buffer, or nil if we
206 ;;; couldn't find it.
216 ;; Can't use search-backward since the match may continue
217 ;; after point.
219 ;; goto-char doesn't signal an error at
220 ;; beginning of buffer like backward-char would
222 ;; to beginning of OSTRING
226 ;; This code was shamelessly lifted from Sebastian Kremer's rcs.el mode.
227 ;; Revert buffer, try to keep point and mark where user expects them in spite
228 ;; of changes because of expanded version-control key words.
229 ;; This is quite important since otherwise typeahead won't work as expected.
233 ;; Use mark-marker to avoid confusion in transient-mark-mode.
236 ;; Make the right thing happen in transient-mark-mode.
247 ;; Make sure the current buffer and its working file are in sync
250 vc-suppress-confirm
256 ;; Has the given workfile changed since last checkout?
264 t)
267 nil
268 ))
269 )))
271 ;; Here's the major entry point.
273 ;;;###autoload
275 "Do the next logical checkin or checkout operation on the current file.
276 If the file is not already registered, this registers it for version
277 control and then retrieves a writeable, locked copy for editing.
278 If the file is registered and not locked by anyone, this checks out
279 a writeable and locked file ready for editing.
280 If the file is checked out and locked by the calling user, this
281 first checks to see if the file has changed since checkout. If not,
282 it performs a revert.
283 If the file has been changed, this pops up a buffer for creation of
284 a log message; when the message has been entered, it checks in the
285 resulting changes along with the log message as change commentary. If
286 the variable vc-keep-workfiles is non-nil (which is its default), a
287 read-only copy of the changed file is left in place afterwards.
288 If the file is registered and locked by someone else, you are given
289 the option to steal the lock."
297 owner)
301 ;; if there is no master file corresponding, create one
309 ;; if there is no lock on the file, assert one and get it
313 ;; a checked-out version exists, but the user may not own the lock
316 file
318 owner))
320 ;; OK, user owns the lock on the file
323 ;; give luser a chance to save before checking in.
326 ;; Revert if file is unchanged and buffer is too.
327 ;; If buffer is modified, that means the user just said no
328 ;; to saving it; in that case, don't revert,
329 ;; because the user might intend to save
330 ;; after finishing the log entry.
335 ;; DO NOT revert the file without asking the user!
338 ;; user may want to set nonstandard parameters
342 ;; OK, let's do the checkin
346 ;;; These functions help the vc-next-action entry point
349 "Retrieve a writeable copy of the latest version of the current buffer's file."
351 )
353 ;;;###autoload
355 "Register the current file into your version-control system."
359 ;; Watch out for new buffers of size 0: the corresponding file
360 ;; does not exist yet, even though buffer-modified-p is nil.
367 buffer-file-name
369 )
372 ;; If the given file is in the current buffer,
373 ;; either revert on it so we see expanded keyworks,
374 ;; or unvisit it (depending on vc-keep-workfiles)
375 ;; NOQUERY if non-nil inhibits confirmation for reverting.
376 ;; NOQUERY should be t *only* if it is known the only difference
377 ;; between the buffer and the file is due to RCS rather than user editing!
389 "Check a file into your version-control system.
390 FILE is the unmodified name of the file. REV should be the base version
391 level to check it in under."
404 ;; Inhibit query here, since otherwise we always get asked.
408 "Steal the lock on the current workfile."
429 ;; This is called when the notification has been sent.
435 "Retrieve a copy of the latest version of the given file."
439 )
442 "Check in the file specified by FILE.
443 The optional argument REV may be a string specifying the new version level
444 \(if nil increment the current level). The file is either retained with write
445 permissions zeroed, or deleted (according to the value of vc-keep-workfiles).
446 COMMENT is a comment string; if omitted, a buffer is
447 popped up to accept a comment."
453 vc-log-file file
454 vc-log-version rev
463 "Complete the operation implied by the current log entry."
467 ;; delimit current page
476 ;; Check for errors
478 ;; OK, do it to it
481 vc-log-file
482 vc-log-version
485 ;; Return to "parent" buffer of this checkin and remove checkin window
489 ;; Now make sure we see the expanded headers
492 )
494 ;; Code for access to the comment ring
497 "Fill the log buffer with the next message in the msg ring."
507 "Fill the log buffer with the previous message in the msg ring."
517 "Fill the log buffer with the last message in the msg ring matching REGEXP."
527 "Fill the log buffer with the next message in the msg ring matching REGEXP."
536 ;; Additional entry points for examining version histories
538 ;;;###autoload
540 "Display diffs between file versions."
545 unchanged)
553 )
555 )
556 )
557 )
560 "For FILE, report diffs between two stored versions REL1 and REL2 of it.
561 If FILE is a directory, generate diffs between versions for all registered
562 files in or below it."
572 " and "
584 )))
589 )
597 )
598 )
599 )
600 )
602 ;; Header-insertion code
604 ;;;###autoload
606 "Insert headers in a file for use with your version-control system.
607 Headers desired are inserted at the start of the buffer, and are pulled from
608 the variable vc-header-strings"
623 hdstrings)
628 vc-static-header-alist))
629 )
630 )))))
632 ;; Status-checking functions
634 ;;;###autoload
636 "Show version-control status of all files under the current directory."
658 ))
660 ;; Named-configuration support for SCCS
669 ))
678 ))
682 name
688 ))
690 ;; Named-configuration entry points
693 ;; Is the current directory ready to be snapshot?
699 t))
701 ;;;###autoload
703 "Make a snapshot called NAME.
704 The snapshot is made from all registered files at or below the current
705 directory. For each file, the version level of its latest
706 version becomes part of the named configuration."
714 ))
716 ;;;###autoload
718 "Retrieve the snapshot called NAME.
719 This function fails if any files are locked at or below the current directory
720 Otherwise, all registered files are checked out (unlocked) at their version
721 levels in the snapshot."
729 ))
731 ;; Miscellaneous other entry points
733 ;;;###autoload
735 "List the change log of the current buffer in a window."
742 )
744 )
745 )
747 ;;;###autoload
749 "Revert the current buffer's file back to the latest checked-in version.
750 This asks for confirmation if the buffer contents are not identical
751 to that version."
765 )
766 )
768 ;;;###autoload
770 "Undo your latest checkin."
780 )
783 "Rename a file, taking its master files with it."
795 ;; This had FILE, I changed it to OLD. -- rms.
801 ; ?? Renaming a file might change its contents due to keyword expansion.
802 ; We should really check out a new copy if the old copy was precisely equal
803 ; to some checked in version. However, testing for this is tricky....
809 ;; This had FILE, I changed it to OLD. -- rms.
812 nil)
813 )
815 ;;;###autoload
817 "Find change log file and add entries from recent RCS logs.
818 The mark is left at the end of the text prepended to the change log.
819 With prefix arg of C-u, only find log entries for the current buffer's file.
820 With any numeric prefix arg, find log entries for all files currently visited.
821 From a program, any arguments are passed to the `rcs2log' script."
828 file)
834 files))))
846 ;; Functions for querying the master and lock files.
852 ;; Use PATTERNS to parse information out of the current buffer
853 ;; by matching each regular expression in the list and returning \\1.
854 ;; If a regexp has two tag brackets, assume the second is a date
855 ;; field and we want the most recent entry matching the template.
856 ;; If FILE and PROPERTIES are given, the latter must be a list of
857 ;; properties of the same length as PATTERNS; each property is assigned
858 ;; the corresponding value.
870 latest-val))
876 value))
878 patterns)
879 )
882 ;; Search for information in a master file.
895 )
899 properties))
900 )
901 )
904 ;; Search for information in log program output
915 )
916 )
920 properties))
921 )
922 )
925 "Return the name of the person currently holding a lock on FILE.
926 Return nil if there is no such person."
932 ;; This implementation assumes that any file which is under version
933 ;; control and has -rw-r--r-- is locked by its owner. This is true
934 ;; for both RCS and SCCS, which keep unlocked files at -r--r--r--.
935 ;; We have to be careful not to exclude files with execute bits on;
936 ;; scripts can be under version control too. The advantage of this
937 ;; hack is that calls to the very expensive vc-fetch-properties
938 ;; function only have to be made if (a) the file is locked by someone
939 ;; other than the current user, or (b) some untoward manipulation
940 ;; behind vc's back has twiddled the `group' or `other' write bits.
943 nil)
951 ;; The slow but reliable version
956 ;; Return version level of the latest version of FILE
961 ;; Return version level of the latest version of FILE checked in by you
965 ;; Collect back-end-dependent stuff here
966 ;;
967 ;; Everything eventually funnels through these functions. To implement
968 ;; support for a new version-control system, add another branch to the
969 ;; vc-backend-dispatch macro (in vc-hooks.el) and fill it in in each call.
972 "Execute FORM1 or FORM2 depending on whether we're using SCCS or RCS."
977 )))
980 ;; Generate lock file name corresponding to FILE
983 master
987 "p."
992 ;; Re-fetch all properties associated with the given file.
993 ;; Currently these properties are:
994 ;; vc-locking-user
995 ;; vc-locked-version
996 ;; vc-latest-version
997 ;; vc-your-latest-version
999 file
1000 ;; SCCS
1006 file
1013 )
1014 file
1016 )
1017 ;; RCS
1028 vc-latest-version vc-your-latest-version))
1029 ))
1032 ;; Where the master and lock files for the current directory are kept
1036 vc-default-back-end
1040 ;; Register a file into the version-control system
1041 ;; Automatically retrieves a read-only version of the file with
1042 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1043 ;; it deletes the workfile.
1057 "-fb"
1071 file)
1072 )))
1074 )
1077 ;; Retrieve a copy of a saved version into a workfile
1084 )
1088 )
1091 )
1101 nil)
1102 )
1105 ;; Register changes to FILE as level REV with explanatory COMMENT.
1106 ;; Automatically retrieves a read-only version of the file with
1108 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1109 ;; it deletes the workfile.
1113 ;; Change buffers to get local value of vc-checkin-switches.
1120 vc-checkin-switches)
1124 )
1129 vc-checkin-switches)
1130 ))
1133 )
1136 ;; Revert file to latest checked-in version.
1139 file
1148 )
1151 ;; Steal the lock on the current workfile. Needs RCS 5.6.2 or later for -M.
1156 )
1161 )
1164 )
1167 ;; Undo the latest checkin. Note: this code will have to get a lot
1168 ;; smarter when we support multiple branches.
1173 )
1175 )
1178 ;; Print change log associated with FILE to buffer *vc*.
1181 file)
1182 )
1185 ;; Assign to a FILE's latest version a given NAME.
1189 )
1191 )
1194 ;; Get a difference report between two versions
1198 file
1201 vc-diff-options
1202 ))
1205 "Check if the current file has any headers in it."
1211 (re-search-forward "\\$[A-Za-z\300-\326\330-\366\370-\377]+\\(: [\t -#%-\176\240-\377]*\\)?\\$" nil t) ;; RCS
1212 )
1213 ))
1215 ;; Back-end-dependent stuff ends here.
1217 ;; Set up key bindings for use while editing log messages
1220 "Minor mode for driving version-control tools.
1221 These bindings are added to the global keymap when you enter this mode:
1233 While you are entering a change log message for a version, the following
1234 additional bindings will be in effect.
1238 Whenever you do a checkin, your log comment is added to a ring of
1239 saved comments. These can be recalled as follows:
1246 Entry to the change-log submode calls the value of text-mode-hook, then
1247 the value of vc-log-mode-hook.
1249 Global user options:
1250 vc-initial-comment If non-nil, require user to enter a change
1251 comment upon first checkin of the file.
1253 vc-keep-workfiles Non-nil value prevents workfiles from being
1254 deleted when changes are checked in
1256 vc-suppress-confirm Suppresses some confirmation prompts,
1257 notably for reversions.
1259 vc-diff-options A list consisting of the flags
1260 to be used for generating context diffs.
1262 vc-header-strings Which keywords to insert when adding headers
1266 vc-static-header-alist By default, version headers inserted in C files
1267 get stuffed in a static string area so that
1268 ident(RCS) or what(SCCS) can see them in the
1269 compiled object code. You can override this
1270 by setting this variable to nil, or change
1271 the header template by changing it.
1273 vc-command-messages if non-nil, display run messages from the
1274 actual version-control utilities (this is
1275 intended primarily for people hacking vc
1276 itself).
1277 "
1289 )
1291 ;; Initialization code, to be done just once at load-time
1293 nil
1300 )
1302 ;;; These things should probably be generally available
1305 "Shrink a window vertically until it's just large enough to contain its text"
1312 "Walk recursively through default directory,
1313 invoking FUNC f ARGS on all non-directory files f underneath it."
1335 ;;; DEVELOPER'S NOTES ON CONCURRENCY PROBLEMS IN THIS CODE
1336 ;;;
1337 ;;; These may be useful to anyone who has to debug or extend the package.
1338 ;;;
1339 ;;; A fundamental problem in VC is that there are time windows between
1340 ;;; vc-next-action's computations of the file's version-control state and
1341 ;;; the actions that change it. This is a window open to lossage in a
1342 ;;; multi-user environment; someone else could nip in and change the state
1343 ;;; of the master during it.
1344 ;;;
1345 ;;; The performance problem is that rlog/prs calls are very expensive; we want
1346 ;;; to avoid them as much as possible.
1347 ;;;
1348 ;;; ANALYSIS:
1349 ;;;
1350 ;;; The performance problem, it turns out, simplifies in practice to the
1351 ;;; problem of making vc-locking-user fast. The two other functions that call
1352 ;;; prs/rlog will not be so commonly used that the slowdown is a problem; one
1353 ;;; makes snapshots, the other deletes the calling user's last change in the
1354 ;;; master.
1355 ;;;
1356 ;;; The race condition implies that we have to either (a) lock the master
1357 ;;; during the entire execution of vc-next-action, or (b) detect and
1358 ;;; recover from errors resulting from dispatch on an out-of-date state.
1359 ;;;
1360 ;;; Alternative (a) appears to be unfeasible. The problem is that we can't
1361 ;;; guarantee that the lock will ever be removed. Suppose a user starts a
1362 ;;; checkin, the change message buffer pops up, and the user, having wandered
1363 ;;; off to do something else, simply forgets about it?
1364 ;;;
1365 ;;; Alternative (b), on the other hand, works well with a cheap way to speed up
1366 ;;; vc-locking-user. Usually, if a file is registered, we can read its locked/
1367 ;;; unlocked state and its current owner from its permissions.
1368 ;;;
1369 ;;; This shortcut will fail if someone has manually changed the workfile's
1370 ;;; permissions; also if developers are munging the workfile in several
1371 ;;; directories, with symlinks to a master (in this latter case, the
1372 ;;; permissions shortcut will fail to detect a lock asserted from another
1373 ;;; directory).
1374 ;;;
1375 ;;; Note that these cases correspond exactly to the errors which could happen
1376 ;;; because of a competing checkin/checkout race in between two instances of
1377 ;;; vc-next-action.
1378 ;;;
1379 ;;; For VC's purposes, a workfile/master pair may have the following states:
1380 ;;;
1381 ;;; A. Unregistered. There is a workfile, there is no master.
1382 ;;;
1383 ;;; B. Registered and not locked by anyone.
1384 ;;;
1385 ;;; C. Locked by calling user and unchanged.
1386 ;;;
1387 ;;; D. Locked by the calling user and changed.
1388 ;;;
1389 ;;; E. Locked by someone other than the calling user.
1390 ;;;
1391 ;;; This makes for 25 states and 20 error conditions. Here's the matrix:
1392 ;;;
1393 ;;; VC's idea of state
1394 ;;; |
1395 ;;; V Actual state RCS action SCCS action Effect
1396 ;;; A B C D E
1397 ;;; A . 1 2 3 4 ci -u -t- admin -fb -i<file> initial admin
1398 ;;; B 5 . 6 7 8 co -l get -e checkout
1399 ;;; C 9 10 . 11 12 co -u unget; get revert
1400 ;;; D 13 14 15 . 16 ci -u -m<comment> delta -y<comment>; get checkin
1401 ;;; E 17 18 19 20 . rcs -u -M ; rcs -l unget -n ; get -g steal lock
1402 ;;;
1403 ;;; All commands take the master file name as a last argument (not shown).
1404 ;;;
1405 ;;; In the discussion below, a "self-race" is a pathological situation in
1406 ;;; which VC operations are being attempted simultaneously by two or more
1407 ;;; Emacsen running under the same username.
1408 ;;;
1409 ;;; The vc-next-action code has the following windows:
1410 ;;;
1411 ;;; Window P:
1412 ;;; Between the check for existence of a master file and the call to
1413 ;;; admin/checkin in vc-buffer-admin (apparent state A). This window may
1414 ;;; never close if the initial-comment feature is on.
1415 ;;;
1416 ;;; Window Q:
1417 ;;; Between the call to vc-workfile-unchanged-p in and the immediately
1418 ;;; following revert (apparent state C).
1419 ;;;
1420 ;;; Window R:
1421 ;;; Between the call to vc-workfile-unchanged-p in and the following
1422 ;;; checkin (apparent state D). This window may never close.
1423 ;;;
1424 ;;; Window S:
1425 ;;; Between the unlock and the immediately following checkout during a
1426 ;;; revert operation (apparent state C). Included in window Q.
1427 ;;;
1428 ;;; Window T:
1429 ;;; Between vc-locking-user and the following checkout (apparent state B).
1430 ;;;
1431 ;;; Window U:
1432 ;;; Between vc-locking-user and the following revert (apparent state C).
1433 ;;; Includes windows Q and S.
1434 ;;;
1435 ;;; Window V:
1436 ;;; Between vc-locking-user and the following checkin (apparent state
1437 ;;; D). This window may never be closed if the user fails to complete the
1438 ;;; checkin message. Includes window R.
1439 ;;;
1440 ;;; Window W:
1441 ;;; Between vc-locking-user and the following steal-lock (apparent
1442 ;;; state E). This window may never cloce if the user fails to complete
1443 ;;; the steal-lock message. Includes window X.
1444 ;;;
1445 ;;; Window X:
1446 ;;; Between the unlock and the immediately following re-lock during a
1447 ;;; steal-lock operation (apparent state E). This window may never cloce
1448 ;;; if the user fails to complete the steal-lock message.
1449 ;;;
1450 ;;; Errors:
1451 ;;;
1452 ;;; Apparent state A ---
1453 ;;;
1454 ;;; 1. File looked unregistered but is actually registered and not locked.
1455 ;;;
1456 ;;; Potential cause: someone else's admin during window P, with
1457 ;;; caller's admin happening before their checkout.
1458 ;;;
1459 ;;; RCS: ci will fail with a "no lock set by <user>" message.
1460 ;;; SCCS: admin will fail with error (ad19).
1461 ;;;
1462 ;;; We can let these errors be passed up to the user.
1463 ;;;
1464 ;;; 2. File looked unregistered but is actually locked by caller, unchanged.
1465 ;;;
1466 ;;; Potential cause: self-race during window P.
1467 ;;;
1468 ;;; RCS: will revert the file to the last saved version and unlock it.
1469 ;;; SCCS: will fail with error (ad19).
1470 ;;;
1471 ;;; Either of these consequences is acceptable.
1472 ;;;
1473 ;;; 3. File looked unregistered but is actually locked by caller, changed.
1474 ;;;
1475 ;;; Potential cause: self-race during window P.
1476 ;;;
1477 ;;; RCS: will register the caller's workfile as a delta with a
1478 ;;; null change comment (the -t- switch will be ignored).
1479 ;;; SCCS: will fail with error (ad19).
1480 ;;;
1481 ;;; 4. File looked unregistered but is locked by someone else.
1482 ;;;
1483 ;;; Potential cause: someone else's admin during window P, with
1484 ;;; caller's admin happening *after* their checkout.
1485 ;;;
1486 ;;; RCS: will fail with a "no lock set by <user>" message.
1487 ;;; SCCS: will fail with error (ad19).
1488 ;;;
1489 ;;; We can let these errors be passed up to the user.
1490 ;;;
1491 ;;; Apparent state B ---
1492 ;;;
1493 ;;; 5. File looked registered and not locked, but is actually unregistered.
1494 ;;;
1495 ;;; Potential cause: master file got nuked during window P.
1496 ;;;
1497 ;;; RCS: will fail with "RCS/<file>: No such file or directory"
1498 ;;; SCCS: will fail with error ut4.
1499 ;;;
1500 ;;; We can let these errors be passed up to the user.
1501 ;;;
1502 ;;; 6. File looked registered and not locked, but is actually locked by the
1503 ;;; calling user and unchanged.
1504 ;;;
1505 ;;; Potential cause: self-race during window T.
1506 ;;;
1507 ;;; RCS: in the same directory as the previous workfile, co -l will fail
1508 ;;; with "co error: writable foo exists; checkout aborted". In any other
1509 ;;; directory, checkout will succeed.
1510 ;;; SCCS: will fail with ge17.
1511 ;;;
1512 ;;; Either of these consequences is acceptable.
1513 ;;;
1514 ;;; 7. File looked registered and not locked, but is actually locked by the
1515 ;;; calling user and changed.
1516 ;;;
1517 ;;; As case 6.
1518 ;;;
1519 ;;; 8. File looked registered and not locked, but is actually locked by another
1520 ;;; user.
1521 ;;;
1522 ;;; Potential cause: someone else checks it out during window T.
1523 ;;;
1524 ;;; RCS: co error: revision 1.3 already locked by <user>
1525 ;;; SCCS: fails with ge4 (in directory) or ut7 (outside it).
1526 ;;;
1527 ;;; We can let these errors be passed up to the user.
1528 ;;;
1529 ;;; Apparent state C ---
1530 ;;;
1531 ;;; 9. File looks locked by calling user and unchanged, but is unregistered.
1532 ;;;
1533 ;;; As case 5.
1534 ;;;
1535 ;;; 10. File looks locked by calling user and unchanged, but is actually not
1536 ;;; locked.
1537 ;;;
1538 ;;; Potential cause: a self-race in window U, or by the revert's
1539 ;;; landing during window X of some other user's steal-lock or window S
1540 ;;; of another user's revert.
1541 ;;;
1542 ;;; RCS: succeeds, refreshing the file from the identical version in
1543 ;;; the master.
1544 ;;; SCCS: fails with error ut4 (p file nonexistent).
1545 ;;;
1546 ;;; Either of these consequences is acceptable.
1547 ;;;
1548 ;;; 11. File is locked by calling user. It looks unchanged, but is actually
1549 ;;; changed.
1550 ;;;
1551 ;;; Potential cause: the file would have to be touched by a self-race
1552 ;;; during window Q.
1553 ;;;
1554 ;;; The revert will succeed, removing whatever changes came with
1555 ;;; the touch. It is theoretically possible that work could be lost.
1556 ;;;
1557 ;;; 12. File looks like it's locked by the calling user and unchanged, but
1558 ;;; it's actually locked by someone else.
1559 ;;;
1560 ;;; Potential cause: a steal-lock in window V.
1561 ;;;
1562 ;;; RCS: co error: revision <rev> locked by <user>; use co -r or rcs -u
1563 ;;; SCCS: fails with error un2
1564 ;;;
1565 ;;; We can pass these errors up to the user.
1566 ;;;
1567 ;;; Apparent state D ---
1568 ;;;
1569 ;;; 13. File looks like it's locked by the calling user and changed, but it's
1570 ;;; actually unregistered.
1571 ;;;
1572 ;;; Potential cause: master file got nuked during window P.
1573 ;;;
1574 ;;; RCS: Checks in the user's version as an initial delta.
1575 ;;; SCCS: will fail with error ut4.
1576 ;;;
1577 ;;; This case is kind of nasty. It means VC may fail to detect the
1578 ;;; loss of previous version information.
1579 ;;;
1580 ;;; 14. File looks like it's locked by the calling user and changed, but it's
1581 ;;; actually unlocked.
1582 ;;;
1583 ;;; Potential cause: self-race in window V, or the checkin happening
1584 ;;; during the window X of someone else's steal-lock or window S of
1585 ;;; someone else's revert.
1586 ;;;
1587 ;;; RCS: ci will fail with "no lock set by <user>".
1588 ;;; SCCS: delta will fail with error ut4.
1589 ;;;
1590 ;;; 15. File looks like it's locked by the calling user and changed, but it's
1591 ;;; actually locked by the calling user and unchanged.
1592 ;;;
1593 ;;; Potential cause: another self-race --- a whole checkin/checkout
1594 ;;; sequence by the calling user would have to land in window R.
1595 ;;;
1596 ;;; SCCS: checks in a redundant delta and leaves the file unlocked as usual.
1597 ;;; RCS: reverts to the file state as of the second user's checkin, leaving
1598 ;;; the file unlocked.
1599 ;;;
1600 ;;; It is theoretically possible that work could be lost under RCS.
1601 ;;;
1602 ;;; 16. File looks like it's locked by the calling user and changed, but it's
1603 ;;; actually locked by a different user.
1604 ;;;
1605 ;;; RCS: ci error: no lock set by <user>
1606 ;;; SCCS: unget will fail with error un2
1607 ;;;
1608 ;;; We can pass these errors up to the user.
1609 ;;;
1610 ;;; Apparent state E ---
1611 ;;;
1612 ;;; 17. File looks like it's locked by some other user, but it's actually
1613 ;;; unregistered.
1614 ;;;
1615 ;;; As case 13.
1616 ;;;
1617 ;;; 18. File looks like it's locked by some other user, but it's actually
1618 ;;; unlocked.
1619 ;;;
1620 ;;; Potential cause: someone released a lock during window W.
1621 ;;;
1622 ;;; RCS: The calling user will get the lock on the file.
1623 ;;; SCCS: unget -n will fail with cm4.
1624 ;;;
1625 ;;; Either of these consequences will be OK.
1626 ;;;
1627 ;;; 19. File looks like it's locked by some other user, but it's actually
1628 ;;; locked by the calling user and unchanged.
1629 ;;;
1630 ;;; Potential cause: the other user relinquishing a lock followed by
1631 ;;; a self-race, both in window W.
1632 ;;;
1633 ;;; Under both RCS and SCCS, both unlock and lock will succeed, making
1634 ;;; the sequence a no-op.
1635 ;;;
1636 ;;; 20. File looks like it's locked by some other user, but it's actually
1637 ;;; locked by the calling user and changed.
1638 ;;;
1639 ;;; As case 19.
1640 ;;;
1641 ;;; PROBLEM CASES:
1642 ;;;
1643 ;;; In order of decreasing severity:
1644 ;;;
1645 ;;; Cases 11 and 15 under RCS are the only one that potentially lose work.
1646 ;;; They would require a self-race for this to happen.
1647 ;;;
1648 ;;; Case 13 in RCS loses information about previous deltas, retaining
1649 ;;; only the information in the current workfile. This can only happen
1650 ;;; if the master file gets nuked in window P.
1651 ;;;
1652 ;;; Case 3 in RCS and case 15 under SCCS insert a redundant delta with
1653 ;;; no change comment in the master. This would require a self-race in
1654 ;;; window P or R respectively.
1655 ;;;
1656 ;;; Cases 2, 10, 19 and 20 do extra work, but make no changes.
1657 ;;;
1658 ;;; Unfortunately, it appears to me that no recovery is possible in these
1659 ;;; cases. They don't yield error messages, so there's no way to tell that
1660 ;;; a race condition has occurred.
1661 ;;;
1662 ;;; All other cases don't change either the workfile or the master, and
1663 ;;; trigger command errors which the user will see.
1664 ;;;
1665 ;;; Thus, there is no explicit recovery code.
1667 ;;; vc.el ends here