| blob | bef1b7de5058bf1a41ff69e78a80d6ed9d68a1ba |
1 ;;; vc.el --- drive a version-control system from within Emacs
3 ;; Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc.
5 ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
6 ;; Maintainer: ttn@netcom.com
7 ;; Version: 5.5 + CVS hacks by ceder@lysator.liu.se made in Jan-Feb 1994.
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
14 ;; any later version.
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to
23 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
25 ;;; Commentary:
27 ;; This mode is fully documented in the Emacs user's manual.
28 ;;
29 ;; This was designed and implemented by Eric Raymond <esr@snark.thyrsus.com>.
30 ;; Paul Eggert <eggert@twinsun.com>, Sebastian Kremer <sk@thp.uni-koeln.de>,
31 ;; and Richard Stallman contributed valuable criticism, support, and testing.
32 ;;
33 ;; Supported version-control systems presently include SCCS and RCS;
34 ;; the RCS lock-stealing code doesn't work right unless you use RCS 5.6.2
35 ;; or newer. Currently (January 1994) that is only a beta test release.
36 ;;
37 ;; The RCS code assumes strict locking. You can support the RCS -x option
38 ;; by adding pairs to the vc-master-templates list.
39 ;;
40 ;; Proper function of the SCCS diff commands requires the shellscript vcdiff
41 ;; to be installed somewhere on Emacs's path for executables.
42 ;;
43 ;; If your site uses the ChangeLog convention supported by Emacs, the
44 ;; function vc-comment-to-change-log should prove a useful checkin hook.
45 ;;
46 ;; This code depends on call-process passing back the subprocess exit
47 ;; status. Thus, you need Emacs 18.58 or later to run it. For the
48 ;; vc-directory command to work properly as documented, you need 19.
49 ;; You also need Emacs 19's ring.el.
50 ;;
51 ;; The vc code maintains some internal state in order to reduce expensive
52 ;; version-control operations to a minimum. Some names are only computed
53 ;; once. If you perform version control operations with RCS/SCCS/CVS while
54 ;; vc's back is turned, or move/rename master files while vc is running,
55 ;; vc may get seriously confused. Don't do these things!
56 ;;
57 ;; Developer's notes on some concurrency issues are included at the end of
58 ;; the file.
60 ;;; Code:
69 minor-mode-alist)))
71 ;; General customization
74 "*Back-end actually used by this interface; may be SCCS or RCS.
79 "*If non-nil, don't delete working files after registering changes.
80 If the back-end is CVS, workfiles are always kept, regardless of the
100 ;;; This is duplicated in diff.el.
104 ;;;###autoload
109 "*List of functions called when a buffer is made writable. See `run-hooks.'
110 This hook is only used when the version control system is CVS. It
111 might be useful for sites who uses locking with CVS, or who uses link
114 ;; Header-insertion hair
122 "*Associate static header string templates with file types. A \%s in the
123 template is replaced with the first string associated with the file's
128 "*Special comment delimiters to be used in generating vc headers only.
129 Add an entry in this list if you need to override the normal comment-start
130 and comment-end variables. This will only be necessary if the mode language
133 ;; Default is to be extra careful for super-user.
135 "*Non-nil means be extra-careful in checkout.
136 Verify that the file really is not locked
139 ;; Variables the user doesn't need to know about.
144 ;; In a log entry buffer, this is a local variable
145 ;; that points to the buffer for which it was made
146 ;; (either a file, or a VC dired buffer).
162 ;; File property caching
165 ;; clear all properties of a given file
169 "Clear all cached file properties and the comment ring."
172 ;; Note: there is potential for minor lossage here if there is an open
173 ;; log buffer with a nonzero local value of vc-comment-ring-index.
176 ;; Random helper functions
186 "Look for a command anywhere on the subprocess-command search path."
199 exec-path)
200 nil)))
203 "Execute a version-control command, notifying user and checking for errors.
204 The command is successful if its exit status does not exceed OKSTATUS.
205 Output from COMMAND goes to buffer *vc*. The last argument of the command is
206 the master name of FILE if LAST is 'MASTER, or the basename of FILE if LAST is
207 'BASE; this is appended to an optional list of FLAGS."
214 status)
222 ;; This is so that command arguments typed in the *vc* buffer will
223 ;; have reasonable defaults.
228 flags)
235 ;; Add vc-path to PATH for the execution of this command.
239 process-environment)))
251 status))
252 )
255 )
257 status)
258 )
260 ;;; Save a bit of the text around POSN in the current buffer, to help
261 ;;; us find the corresponding position again later. This works even
262 ;;; if all markers are destroyed or corrupted.
269 ;;; Return the position of CONTEXT in the current buffer, or nil if we
270 ;;; couldn't find it.
280 ;; Can't use search-backward since the match may continue
281 ;; after point.
283 ;; goto-char doesn't signal an error at
284 ;; beginning of buffer like backward-char would
286 ;; to beginning of OSTRING
290 ;; Most of this was shamelessly lifted from Sebastian Kremer's rcs.el mode.
291 ;; Revert buffer, try to keep point and mark where user expects them in spite
292 ;; of changes because of expanded version-control key words.
293 ;; This is quite important since otherwise typeahead won't work as expected.
297 ;; Use mark-marker to avoid confusion in transient-mark-mode.
300 ;; Make the right thing happen in transient-mark-mode.
302 ;; We may want to reparse the compilation buffer after revert
305 ;; Construct a list; each elt is nil or a buffer
306 ;; iff that buffer is a compilation output buffer
307 ;; that contains markers into the current buffer.
313 compilation-old-error-list
314 compilation-error-list))
327 ;; the actual revisit
330 ;; Reparse affected compilation buffers.
336 ;; Record the position in the compilation buffer of
337 ;; the last error next-error went to.
340 ;; Reparse the error messages as far as they were parsed before.
342 ;; Move the pointer up to find the error we were at before
343 ;; reparsing. Now next-error should properly go to the next one.
349 ;; Restore point and mark
358 ;; Make sure the current buffer and its working file are in sync
359 ;; NOT-URGENT means it is ok to continue if the user says not to save.
365 nil
370 ;; Has the given workfile changed since last checkout?
377 ;; 0 stands for an unknown time; it can't match any mod time.
379 unchanged)))))
382 ;;; If comment is specified, it will be used as an admin or checkin comment.
385 owner version)
388 ;; if there is no master file corresponding, create one
392 ;; if there is no lock on the file, assert one and get it
401 file))
412 )
415 ;; a checked-out version exists, but the user may not own the lock
421 file
423 owner))
425 ;; changes to the master file needs to be merged back into the
426 ;; working file
428 ;; "0" means "added, but not yet committed"
440 "Buffer %s modified; merge file on disc anyhow? "
444 ;; Overlaps detected - what now? Should use some
445 ;; fancy RCS conflict resolving package, or maybe
446 ;; emerge, but for now, simply warn the user with a
447 ;; message.
455 ;; Sites who make link farms to a read-only gold tree (or
456 ;; something similar) can use the hook below to break the
457 ;; sym-link.
460 ;; OK, user owns the lock on the file (or we are running CVS)
464 ;; give luser a chance to save before checking in.
467 ;; Revert if file is unchanged and buffer is too.
468 ;; If buffer is modified, that means the user just said no
469 ;; to saving it; in that case, don't revert,
470 ;; because the user might intend to save
471 ;; after finishing the log entry.
479 ;; DO NOT revert the file without asking the user!
482 ;; user may want to set nonstandard parameters
486 ;; OK, let's do the checkin
488 )))))
491 ;; We've accepted a log comment, now do a vc-next-action using it on all
492 ;; marked files.
500 nil t)
501 )
503 ;; Here's the major entry point.
505 ;;;###autoload
507 "Do the next logical checkin or checkout operation on the current file.
509 For RCS and SCCS files:
510 If the file is not already registered, this registers it for version
511 control and then retrieves a writable, locked copy for editing.
512 If the file is registered and not locked by anyone, this checks out
513 a writable and locked file ready for editing.
514 If the file is checked out and locked by the calling user, this
515 first checks to see if the file has changed since checkout. If not,
516 it performs a revert.
517 If the file has been changed, this pops up a buffer for entry
518 of a log message; when the message has been entered, it checks in the
519 resulting changes along with the log message as change commentary. If
520 the variable `vc-keep-workfiles' is non-nil (which is its default), a
521 read-only copy of the changed file is left in place afterwards.
522 If the file is registered and locked by someone else, you are given
523 the option to steal the lock.
525 For CVS files:
526 If the file is not already registered, this registers it for version
528 If the file is added but not committed, it is committed.
529 If the file has not been changed, neither in your working area or
530 in the repository, a message is printed and nothing is done.
531 If your working file is changed, but the repository file is
532 unchanged, this pops up a buffer for entry of a log message; when the
533 message has been entered, it checks in the resulting changes along
534 with the logmessage as change commentary. A writable file is retained.
535 If the repository file is changed, you are asked if you want to
536 merge in the changes into your working copy.
538 The following is true regardless of which version control system you
539 are using:
541 If you call this from within a VC dired buffer with no files marked,
542 it will operate on the file in the current line.
543 If you call this from within a VC dired buffer, and one or more
544 files are marked, it will accept a log message and then operate on
545 each one. The log message will be used as a comment for any register
546 or checkin operations, but ignored when doing checkouts. Attempted
547 lock steals will raise an error.
549 For checkin, a prefix argument lets you specify the version number to use."
557 "Enter a change comment for the marked files."
566 ;;; These functions help the vc-next-action entry point
569 "Retrieve a writable copy of the latest version of the current buffer's file."
571 )
573 ;;;###autoload
575 "Register the current file into your version-control system."
583 ;; Watch out for new buffers of size 0: the corresponding file
584 ;; does not exist yet, even though buffer-modified-p is nil.
591 buffer-file-name
595 )
598 ;; If the given file is in the current buffer,
599 ;; either revert on it so we see expanded keyworks,
600 ;; or unvisit it (depending on vc-keep-workfiles)
601 ;; NOQUERY if non-nil inhibits confirmation for reverting.
602 ;; NOQUERY should be t *only* if it is known the only difference
603 ;; between the buffer and the file is due to RCS rather than user editing!
614 ;; Accept a comment for an operation on FILE revision REV. If COMMENT
615 ;; is nil, pop up a VC-log buffer, emit MSG, and set the
616 ;; action on close to ACTION; otherwise, do action immediately.
617 ;; Remember the file's buffer in vc-parent-buffer (current one if no file).
618 ;; AFTER-HOOK specifies the local value for vc-log-operation-hook.
644 "Check a file into your version-control system.
645 FILE is the unmodified name of the file. REV should be the base version
646 level to check it in under. COMMENT, if specified, is the checkin comment."
650 nil))
653 "Retrieve a copy of the latest version of the given file."
654 ;; If ftp is on this system and the name matches the ange-ftp format
655 ;; for a remote file, the user is trying something that won't work.
661 )
664 "Steal the lock on the current workfile."
672 file-description owner)))
688 ;; This is called when the notification has been sent.
697 "Check in the file specified by FILE.
698 The optional argument REV may be a string specifying the new version level
699 \(if nil increment the current level). The file is either retained with write
700 permissions zeroed, or deleted (according to the value of `vc-keep-workfiles').
701 If the back-end is CVS, a writable workfile is always kept.
702 COMMENT is a comment string; if omitted, a buffer is
703 popped up to accept a comment."
708 ;;; Here is a checkin hook that may prove useful to sites using the
709 ;;; ChangeLog facility supported by Emacs.
711 "Enter last VC comment into change log file for current buffer's file.
712 Optional arg (interactive prefix) non-nil means prompt for user name and site.
713 Second arg is file name of change log. \
714 If nil, uses `change-log-default-name'."
718 ;; Make sure the defvar for add-log-current-defun-function has been executed
719 ;; before binding it.
723 ;; Don't let add-change-log-entry insert a defun name.
725 end)
726 ;; Call add-log to do half the work.
728 ;; Insert the VC comment, leaving point before it.
731 ;; It starts with an open-paren, as in "(foo): Frobbed."
732 ;; So remove the ": " add-log inserted.
734 ;; Canonicalize the white space between the file name and comment.
736 ;; Indent rest of the text the same way add-log indented the first line.
743 ;; Fill the inserted text, preserving open-parens at bol.
748 ;; Canonicalize the white space at the end of the entry so it is
749 ;; separated from the next entry by a single blank line.
757 "Complete the operation implied by the current log entry."
759 ;; Check and record the comment, if any.
765 ;; Comment too long?
767 ;; Record the comment in the comment ring
771 ))
772 ;; Sync parent buffer in case the user modified it while editing the comment.
773 ;; But not if it is a vc-dired buffer.
778 ;; OK, do it to it
782 vc-log-file
783 vc-log-version
786 ;; save the vc-log-after-operation-hook of log buffer
788 ;; Return to "parent" buffer of this checkin and remove checkin window
793 ;; Now make sure we see the expanded headers
798 ;; Code for access to the comment ring
801 "Cycle backwards through comment history."
809 ;; Initialize the index on the first use of this command
810 ;; so that the first M-p gets index 0, and the first M-n gets
811 ;; index -1.
822 "Cycle forwards through comment history."
827 "Searches backwards through comment history for substring match."
844 "Searches forwards through comment history for substring match."
860 ;; Additional entry points for examining version histories
862 ;;;###autoload
864 "Display diffs between file versions.
865 Normally this compares the current file and buffer with the most recent
866 checked in version of that file. This uses no arguments.
867 With a prefix argument, it reads the file name to use
868 and two version designators specifying which versions to compare."
880 unchanged)
888 ;; Ideally, we'd like at this point to parse the diff so that
889 ;; the buffer effectively goes into compilation mode and we
890 ;; can visit the old and new change locations via next-error.
891 ;; Unfortunately, this is just too painful to do. The basic
892 ;; problem is that the `old' file doesn't exist to be
893 ;; visited. This plays hell with numerous assumptions in
894 ;; the diff.el and compile.el machinery.
906 "For FILE, report diffs between two stored versions REL1 and REL2 of it.
907 If FILE is a directory, generate diffs between versions for all registered
908 files in or below it."
921 " and "
934 )))
939 )
944 ;;;###autoload
946 "Visit version REV of the current buffer in another window.
947 If the current buffer is named `F', the version is named `F.~REV~'.
948 If `F.~REV~' already exists, it is used instead of being re-created."
957 rev))
964 ;; Header-insertion code
966 ;;;###autoload
968 "Insert headers in a file for use with your version-control system.
969 Headers desired are inserted at the start of the buffer, and are pulled from
970 the variable `vc-header-alist'."
989 hdstrings)
994 vc-static-header-alist))
995 )
996 )))))
998 ;; The VC directory submode. Coopt Dired for this.
999 ;; All VC commands get mapped into logical equivalents.
1008 minor-mode-map-alist)))
1011 "The augmented Dired minor mode used in VC directory buffers.
1012 All Dired commands operate normally. Users currently locking listed files
1013 are listed in place of the file's owner and group.
1014 Keystrokes bound to VC commands will execute as though they had been called
1015 on a buffer attached to the file named in the current Dired buffer line."
1020 ;; Hack a directory-listing line, plugging in locking-user info in
1021 ;; place of the user and group info. Should have the beneficial
1022 ;; side-effect of shortening the listing line. Each call starts with
1023 ;; point immediately following the dired mark area on the line to be
1024 ;; hacked.
1025 ;;
1026 ;; Simplest possible one:
1027 ;; (insert (concat x "\t")))
1028 ;;
1029 ;; This code, like dired, assumes UNIX -l format.
1032 ;; This hack is used by the CVS code. See vc-locking-user.
1049 )))
1051 ;;;###autoload
1053 "Show version-control status of all files in the directory DIR.
1054 If the second argument VERBOSE is non-nil, show all files;
1055 otherwise show only files that current locked in the version control system.
1056 Interactively, supply a prefix arg to make VERBOSE non-nil.
1058 If the optional third argument NESTED is non-nil,
1059 scan the entire tree of subdirectories of the current directory."
1064 dired-buf
1065 dired-buf-mod-count
1078 ;; This uses a semi-documented feature of dired; giving a switch
1079 ;; argument forces the buffer to refresh each time.
1082 dired-listing-switches)
1101 )
1104 ))
1106 ; Emacs 18 also lacks these.
1110 ;; Named-configuration support for SCCS
1119 ))
1125 ;; (replace-regexp (concat ":" (regexp-quote file) "$") (concat ":" newname))
1130 ))
1133 ;; Return the numeric version corresponding to a named snapshot of file
1134 ;; If name is nil or a version number string it's just passed through
1138 name)
1143 )))
1145 ;; Named-configuration entry points
1148 ;; Return an example of why the current directory is not ready to be snapshot
1149 ;; or nil if no such example exists.
1155 nil))
1157 ;;;###autoload
1159 "Make a snapshot called NAME.
1160 The snapshot is made from all registered files at or below the current
1161 directory. For each file, the version level of its latest
1162 version becomes part of the named configuration."
1171 )))
1173 ;;;###autoload
1175 "Retrieve the snapshot called NAME.
1176 This function fails if any files are locked at or below the current directory
1177 Otherwise, all registered files are checked out (unlocked) at their version
1178 levels in the snapshot."
1188 )))
1190 ;; Miscellaneous other entry points
1192 ;;;###autoload
1194 "List the change log of the current buffer in a window."
1211 )
1213 )
1214 )
1216 ;;;###autoload
1218 "Revert the current buffer's file back to the latest checked-in version.
1219 This asks for confirmation if the buffer contents are not identical
1220 to that version.
1221 If the back-end is CVS, this will give you the most recent revision of
1222 the file on the branch you are editing."
1240 )
1241 )
1243 ;;;###autoload
1245 "Get rid of most recently checked in version of this file.
1246 A prefix argument means do not revert the buffer afterwards."
1255 "Remove your version %s from master? "
1258 nil
1264 ))
1266 ;;;###autoload
1268 "Rename file OLD to NEW, and rename its master file likewise."
1270 ;; There are several ways of renaming files under CVS 1.3, but they all
1271 ;; have serious disadvantages. See the FAQ (available from think.com in
1272 ;; pub/cvs/). I'd rather send the user an error, than do something he might
1273 ;; consider to be wrong. When the famous, long-awaited rename database is
1274 ;; implemented things might change for the better. This is unlikely to occur
1275 ;; until CVS 2.0 is released. --ceder 1994-01-23 21:27:51
1291 ;; This had FILE, I changed it to OLD. -- rms.
1295 oldmaster
1309 vc-master-templates)
1313 ; ?? Renaming a file might change its contents due to keyword expansion.
1314 ; We should really check out a new copy if the old copy was precisely equal
1315 ; to some checked in version. However, testing for this is tricky....
1321 ;; This had FILE, I changed it to OLD. -- rms.
1324 nil ;RCS
1325 nil ;CVS
1326 )
1327 )
1329 ;;;###autoload
1331 "Find change log file and add entries from recent RCS logs.
1332 The mark is left at the end of the text prepended to the change log.
1333 With prefix arg of C-u, only find log entries for the current buffer's file.
1334 With any numeric prefix arg, find log entries for all files currently visited.
1335 Otherwise, find log entries for all registered files in the default directory.
1336 From a program, any arguments are passed to the `rcs2log' script."
1343 file)
1349 files))
1357 f)))
1370 "-n"
1373 user-mail-address
1378 f
1380 args))))
1383 ;; Functions for querying the master and lock files.
1389 ;; Use PATTERNS to parse information out of the current buffer
1390 ;; by matching each regular expression in the list and returning \\1.
1391 ;; If a regexp has two tag brackets, assume the second is a date
1392 ;; field and we want the most recent entry matching the template.
1393 ;; If FILE and PROPERTIES are given, the latter must be a list of
1394 ;; properties of the same length as PATTERNS; each property is assigned
1395 ;; the corresponding value.
1407 latest-val))
1414 value)
1416 patterns)
1417 )
1420 ;; Search for information in a master file.
1433 )
1437 properties))
1438 )
1439 )
1442 ;; Search for information in log program output
1451 )
1452 )
1456 properties))
1457 )
1458 )
1461 "Return the name of the person currently holding a lock on FILE.
1462 Return nil if there is no such person.
1463 Under CVS, a file is considered locked if it has been modified since it
1464 was checked out. Under CVS, this will sometimes return the uid of
1465 the owner of the file (as a number) instead of a string."
1470 nil
1471 ;; The expression below should return the username of the owner
1472 ;; of the file. It doesn't. It returns the username if it is
1473 ;; you, or otherwise the UID of the owner of the file. The
1474 ;; return value from this function is only used by
1475 ;; vc-dired-reformat-line, and it does the proper thing if a UID
1476 ;; is returned.
1477 ;;
1478 ;; The *proper* way to fix this would be to implement a built-in
1479 ;; function in Emacs, say, (username UID), that returns the
1480 ;; username of a given UID.
1481 ;;
1482 ;; The result of this hack is that vc-directory will print the
1483 ;; name of the owner of the file for any files that are
1484 ;; modified.
1488 uid))))
1494 file))))
1496 ;; This implementation assumes that any file which is under version
1497 ;; control and has -rw-r--r-- is locked by its owner. This is true
1498 ;; for both RCS and SCCS, which keep unlocked files at -r--r--r--.
1499 ;; We have to be careful not to exclude files with execute bits on;
1500 ;; scripts can be under version control too. Also, we must ignore
1501 ;; the group-read and other-read bits, since paranoid users turn them off.
1502 ;; This hack wins because calls to the very expensive vc-fetch-properties
1503 ;; function only have to be made if (a) the file is locked by someone
1504 ;; other than the current user, or (b) some untoward manipulation
1505 ;; behind vc's back has changed the owner or the `group' or `other'
1506 ;; write bits.
1509 nil)
1517 ;; The slow but reliable version
1522 ;; Return version level of the latest version of FILE
1527 ;; Return version level of the latest version of FILE checked in by you
1531 ;; Collect back-end-dependent stuff here
1532 ;;
1533 ;; Everything eventually funnels through these functions. To implement
1534 ;; support for a new version-control system, add another branch to the
1535 ;; vc-backend-dispatch macro and fill it in in each call. The variable
1536 ;; vc-master-templates in vc-hooks.el will also have to change.
1539 "Execute FORM1, FORM2 or FORM3 depending whether we're using SCCS, RCS or CVS.
1540 If FORM3 is RCS, use FORM2 even if we are using CVS. (CVS shares some code
1541 with RCS)."
1548 )))
1551 ;; Generate lock file name corresponding to FILE
1554 master
1558 "p."
1563 ;; Re-fetch all properties associated with the given file.
1564 ;; Currently these properties are:
1565 ;; vc-locking-user
1566 ;; vc-locked-version
1567 ;; vc-latest-version
1568 ;; vc-your-latest-version
1570 file
1571 ;; SCCS
1577 file
1584 )
1585 file
1587 )
1588 ;; RCS
1599 vc-latest-version vc-your-latest-version))
1600 ;; CVS
1601 ;; Don't fetch vc-locking-user and vc-locked-version here, since they
1602 ;; should always be nil anyhow. Don't fetch vc-your-latest-version, since
1603 ;; that is done in vc-find-cvs-master.
1606 ;; CVS 1.3 says "RCS Version:", other releases "RCS Revision:",
1607 ;; and CVS 1.4a1 says "Repository revision:". The regexp below
1608 ;; matches much more, but because of the way vc-log-info is
1609 ;; implemented it is impossible to use additional groups.
1612 ))
1615 ;; Where the master and lock files for the current directory are kept
1619 vc-default-back-end
1623 ;; Register a file into the version-control system
1624 ;; Automatically retrieves a read-only version of the file with
1625 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1626 ;; it deletes the workfile.
1641 "-fb"
1655 file))
1658 "add"
1661 )))
1663 )
1666 ;; Retrieve a copy of a saved version into a workfile
1670 ;; Change buffers to get local value of vc-checkin-switches.
1674 ;; Some SCCS implementations allow checking out directly to a
1675 ;; file using the -G option, but then some don't so use the
1676 ;; least common denominator approach and use the -p option
1677 ;; ala RCS.
1685 ;; Some shells make the "" dummy argument into $0
1686 ;; while others use the shell's name as $0 and
1687 ;; use the "" as $1. The if-statement
1688 ;; converts the latter case to the former.
1695 filename
1699 vc-checkout-switches)
1705 vc-checkout-switches)
1707 ;; RCS doesn't let us check out into arbitrary file names directly.
1708 ;; Use `co -p' and make stdout point to the correct file.
1716 ;; See the SCCS case, above, regarding the
1717 ;; if-statement.
1724 filename
1727 vc-checkout-switches)
1733 vc-checkout-switches)
1735 ;; CVS is much like RCS
1743 workfile
1745 "-p"
1746 vc-checkout-switches)
1751 file
1752 vc-checkout-switches))
1753 ))
1758 )
1767 nil ;; RCS
1769 )
1772 ;; Register changes to FILE as level REV with explanatory COMMENT.
1773 ;; Automatically retrieves a read-only version of the file with
1774 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1775 ;; it deletes the workfile.
1778 ;; Change buffers to get local value of vc-checkin-switches.
1785 vc-checkin-switches)
1788 )
1792 vc-checkin-switches)
1796 vc-checkin-switches)
1799 ))
1802 )
1805 ;; Revert file to latest checked-in version.
1808 file
1817 )
1820 )
1823 ;; Steal the lock on the current workfile. Needs RCS 5.6.2 or later for -M.
1829 )
1833 )
1836 )
1839 ;; Undo the latest checkin. Note: this code will have to get a lot
1840 ;; smarter when we support multiple branches.
1846 )
1848 )
1851 ;; Print change log associated with FILE to buffer *vc*.
1853 file
1859 ;; Assign to a FILE's latest version a given NAME.
1864 )
1865 )
1868 ;; Get a difference report between two versions of FILE.
1869 ;; Get only a brief comparison report if CMP, a difference report otherwise.
1876 ;; SCCS and RCS shares a lot of code.
1879 "vcdiff"
1882 "-q"
1887 diff-switches
1890 ;; Some RCS versions don't understand "--brief"; work around this.
1894 status)))
1895 ;; CVS is different.
1896 ;; cmp is not yet implemented -- we always do a full diff.
1899 ;; This file is added but not yet committed; there is no master file.
1900 ;; diff it against /dev/null.
1906 diff-switches
1913 diff-switches
1919 ;; Merge in any new changes made to FILE.
1921 file
1925 ))
1928 "Check if the current file has any headers in it."
1934 (re-search-forward "\\$[A-Za-z\300-\326\330-\366\370-\377]+\\(: [\t -#%-\176\240-\377]*\\)?\\$" nil t) ;; RCS
1936 )
1937 ))
1939 ;; Back-end-dependent stuff ends here.
1941 ;; Set up key bindings for use while editing log messages
1944 "Minor mode for driving version-control tools.
1945 These bindings are added to the global keymap when you enter this mode:
1958 While you are entering a change log message for a version, the following
1959 additional bindings will be in effect.
1963 Whenever you do a checkin, your log comment is added to a ring of
1964 saved comments. These can be recalled as follows:
1971 Entry to the change-log submode calls the value of text-mode-hook, then
1972 the value of vc-log-mode-hook.
1974 Global user options:
1975 vc-initial-comment If non-nil, require user to enter a change
1976 comment upon first checkin of the file.
1978 vc-keep-workfiles Non-nil value prevents workfiles from being
1979 deleted when changes are checked in
1981 vc-suppress-confirm Suppresses some confirmation prompts,
1982 notably for reversions.
1984 vc-header-alist Which keywords to insert when adding headers
1987 RCS and CVS.
1989 vc-static-header-alist By default, version headers inserted in C files
1990 get stuffed in a static string area so that
1991 ident(RCS/CVS) or what(SCCS) can see them in
1992 the compiled object code. You can override
1993 this by setting this variable to nil, or change
1994 the header template by changing it.
1996 vc-command-messages if non-nil, display run messages from the
1997 actual version-control utilities (this is
1998 intended primarily for people hacking vc
1999 itself).
2000 "
2013 )
2015 ;; Initialization code, to be done just once at load-time
2017 nil
2024 )
2026 ;;; These things should probably be generally available
2029 "Walk recursively through default directory.
2030 Invoke FUNC f ARGS on each non-directory file f underneath it."
2051 "Invoke FUNC f ARGS on each regular file f in default directory."
2063 ;;; DEVELOPER'S NOTES ON CONCURRENCY PROBLEMS IN THIS CODE
2064 ;;;
2065 ;;; These may be useful to anyone who has to debug or extend the package.
2066 ;;;
2067 ;;; A fundamental problem in VC is that there are time windows between
2068 ;;; vc-next-action's computations of the file's version-control state and
2069 ;;; the actions that change it. This is a window open to lossage in a
2070 ;;; multi-user environment; someone else could nip in and change the state
2071 ;;; of the master during it.
2072 ;;;
2073 ;;; The performance problem is that rlog/prs calls are very expensive; we want
2074 ;;; to avoid them as much as possible.
2075 ;;;
2076 ;;; ANALYSIS:
2077 ;;;
2078 ;;; The performance problem, it turns out, simplifies in practice to the
2079 ;;; problem of making vc-locking-user fast. The two other functions that call
2080 ;;; prs/rlog will not be so commonly used that the slowdown is a problem; one
2081 ;;; makes snapshots, the other deletes the calling user's last change in the
2082 ;;; master.
2083 ;;;
2084 ;;; The race condition implies that we have to either (a) lock the master
2085 ;;; during the entire execution of vc-next-action, or (b) detect and
2086 ;;; recover from errors resulting from dispatch on an out-of-date state.
2087 ;;;
2088 ;;; Alternative (a) appears to be unfeasible. The problem is that we can't
2089 ;;; guarantee that the lock will ever be removed. Suppose a user starts a
2090 ;;; checkin, the change message buffer pops up, and the user, having wandered
2091 ;;; off to do something else, simply forgets about it?
2092 ;;;
2093 ;;; Alternative (b), on the other hand, works well with a cheap way to speed up
2094 ;;; vc-locking-user. Usually, if a file is registered, we can read its locked/
2095 ;;; unlocked state and its current owner from its permissions.
2096 ;;;
2097 ;;; This shortcut will fail if someone has manually changed the workfile's
2098 ;;; permissions; also if developers are munging the workfile in several
2099 ;;; directories, with symlinks to a master (in this latter case, the
2100 ;;; permissions shortcut will fail to detect a lock asserted from another
2101 ;;; directory).
2102 ;;;
2103 ;;; Note that these cases correspond exactly to the errors which could happen
2104 ;;; because of a competing checkin/checkout race in between two instances of
2105 ;;; vc-next-action.
2106 ;;;
2107 ;;; For VC's purposes, a workfile/master pair may have the following states:
2108 ;;;
2109 ;;; A. Unregistered. There is a workfile, there is no master.
2110 ;;;
2111 ;;; B. Registered and not locked by anyone.
2112 ;;;
2113 ;;; C. Locked by calling user and unchanged.
2114 ;;;
2115 ;;; D. Locked by the calling user and changed.
2116 ;;;
2117 ;;; E. Locked by someone other than the calling user.
2118 ;;;
2119 ;;; This makes for 25 states and 20 error conditions. Here's the matrix:
2120 ;;;
2121 ;;; VC's idea of state
2122 ;;; |
2123 ;;; V Actual state RCS action SCCS action Effect
2124 ;;; A B C D E
2125 ;;; A . 1 2 3 4 ci -u -t- admin -fb -i<file> initial admin
2126 ;;; B 5 . 6 7 8 co -l get -e checkout
2127 ;;; C 9 10 . 11 12 co -u unget; get revert
2128 ;;; D 13 14 15 . 16 ci -u -m<comment> delta -y<comment>; get checkin
2129 ;;; E 17 18 19 20 . rcs -u -M ; rcs -l unget -n ; get -g steal lock
2130 ;;;
2131 ;;; All commands take the master file name as a last argument (not shown).
2132 ;;;
2133 ;;; In the discussion below, a "self-race" is a pathological situation in
2134 ;;; which VC operations are being attempted simultaneously by two or more
2135 ;;; Emacsen running under the same username.
2136 ;;;
2137 ;;; The vc-next-action code has the following windows:
2138 ;;;
2139 ;;; Window P:
2140 ;;; Between the check for existence of a master file and the call to
2141 ;;; admin/checkin in vc-buffer-admin (apparent state A). This window may
2142 ;;; never close if the initial-comment feature is on.
2143 ;;;
2144 ;;; Window Q:
2145 ;;; Between the call to vc-workfile-unchanged-p in and the immediately
2146 ;;; following revert (apparent state C).
2147 ;;;
2148 ;;; Window R:
2149 ;;; Between the call to vc-workfile-unchanged-p in and the following
2150 ;;; checkin (apparent state D). This window may never close.
2151 ;;;
2152 ;;; Window S:
2153 ;;; Between the unlock and the immediately following checkout during a
2154 ;;; revert operation (apparent state C). Included in window Q.
2155 ;;;
2156 ;;; Window T:
2157 ;;; Between vc-locking-user and the following checkout (apparent state B).
2158 ;;;
2159 ;;; Window U:
2160 ;;; Between vc-locking-user and the following revert (apparent state C).
2161 ;;; Includes windows Q and S.
2162 ;;;
2163 ;;; Window V:
2164 ;;; Between vc-locking-user and the following checkin (apparent state
2165 ;;; D). This window may never be closed if the user fails to complete the
2166 ;;; checkin message. Includes window R.
2167 ;;;
2168 ;;; Window W:
2169 ;;; Between vc-locking-user and the following steal-lock (apparent
2170 ;;; state E). This window may never close if the user fails to complete
2171 ;;; the steal-lock message. Includes window X.
2172 ;;;
2173 ;;; Window X:
2174 ;;; Between the unlock and the immediately following re-lock during a
2175 ;;; steal-lock operation (apparent state E). This window may never cloce
2176 ;;; if the user fails to complete the steal-lock message.
2177 ;;;
2178 ;;; Errors:
2179 ;;;
2180 ;;; Apparent state A ---
2181 ;;;
2182 ;;; 1. File looked unregistered but is actually registered and not locked.
2183 ;;;
2184 ;;; Potential cause: someone else's admin during window P, with
2185 ;;; caller's admin happening before their checkout.
2186 ;;;
2187 ;;; RCS: ci will fail with a "no lock set by <user>" message.
2188 ;;; SCCS: admin will fail with error (ad19).
2189 ;;;
2190 ;;; We can let these errors be passed up to the user.
2191 ;;;
2192 ;;; 2. File looked unregistered but is actually locked by caller, unchanged.
2193 ;;;
2194 ;;; Potential cause: self-race during window P.
2195 ;;;
2196 ;;; RCS: will revert the file to the last saved version and unlock it.
2197 ;;; SCCS: will fail with error (ad19).
2198 ;;;
2199 ;;; Either of these consequences is acceptable.
2200 ;;;
2201 ;;; 3. File looked unregistered but is actually locked by caller, changed.
2202 ;;;
2203 ;;; Potential cause: self-race during window P.
2204 ;;;
2205 ;;; RCS: will register the caller's workfile as a delta with a
2206 ;;; null change comment (the -t- switch will be ignored).
2207 ;;; SCCS: will fail with error (ad19).
2208 ;;;
2209 ;;; 4. File looked unregistered but is locked by someone else.
2210 ;;;
2211 ;;; Potential cause: someone else's admin during window P, with
2212 ;;; caller's admin happening *after* their checkout.
2213 ;;;
2214 ;;; RCS: will fail with a "no lock set by <user>" message.
2215 ;;; SCCS: will fail with error (ad19).
2216 ;;;
2217 ;;; We can let these errors be passed up to the user.
2218 ;;;
2219 ;;; Apparent state B ---
2220 ;;;
2221 ;;; 5. File looked registered and not locked, but is actually unregistered.
2222 ;;;
2223 ;;; Potential cause: master file got nuked during window P.
2224 ;;;
2225 ;;; RCS: will fail with "RCS/<file>: No such file or directory"
2226 ;;; SCCS: will fail with error ut4.
2227 ;;;
2228 ;;; We can let these errors be passed up to the user.
2229 ;;;
2230 ;;; 6. File looked registered and not locked, but is actually locked by the
2231 ;;; calling user and unchanged.
2232 ;;;
2233 ;;; Potential cause: self-race during window T.
2234 ;;;
2235 ;;; RCS: in the same directory as the previous workfile, co -l will fail
2236 ;;; with "co error: writable foo exists; checkout aborted". In any other
2237 ;;; directory, checkout will succeed.
2238 ;;; SCCS: will fail with ge17.
2239 ;;;
2240 ;;; Either of these consequences is acceptable.
2241 ;;;
2242 ;;; 7. File looked registered and not locked, but is actually locked by the
2243 ;;; calling user and changed.
2244 ;;;
2245 ;;; As case 6.
2246 ;;;
2247 ;;; 8. File looked registered and not locked, but is actually locked by another
2248 ;;; user.
2249 ;;;
2250 ;;; Potential cause: someone else checks it out during window T.
2251 ;;;
2252 ;;; RCS: co error: revision 1.3 already locked by <user>
2253 ;;; SCCS: fails with ge4 (in directory) or ut7 (outside it).
2254 ;;;
2255 ;;; We can let these errors be passed up to the user.
2256 ;;;
2257 ;;; Apparent state C ---
2258 ;;;
2259 ;;; 9. File looks locked by calling user and unchanged, but is unregistered.
2260 ;;;
2261 ;;; As case 5.
2262 ;;;
2263 ;;; 10. File looks locked by calling user and unchanged, but is actually not
2264 ;;; locked.
2265 ;;;
2266 ;;; Potential cause: a self-race in window U, or by the revert's
2267 ;;; landing during window X of some other user's steal-lock or window S
2268 ;;; of another user's revert.
2269 ;;;
2270 ;;; RCS: succeeds, refreshing the file from the identical version in
2271 ;;; the master.
2272 ;;; SCCS: fails with error ut4 (p file nonexistent).
2273 ;;;
2274 ;;; Either of these consequences is acceptable.
2275 ;;;
2276 ;;; 11. File is locked by calling user. It looks unchanged, but is actually
2277 ;;; changed.
2278 ;;;
2279 ;;; Potential cause: the file would have to be touched by a self-race
2280 ;;; during window Q.
2281 ;;;
2282 ;;; The revert will succeed, removing whatever changes came with
2283 ;;; the touch. It is theoretically possible that work could be lost.
2284 ;;;
2285 ;;; 12. File looks like it's locked by the calling user and unchanged, but
2286 ;;; it's actually locked by someone else.
2287 ;;;
2288 ;;; Potential cause: a steal-lock in window V.
2289 ;;;
2290 ;;; RCS: co error: revision <rev> locked by <user>; use co -r or rcs -u
2291 ;;; SCCS: fails with error un2
2292 ;;;
2293 ;;; We can pass these errors up to the user.
2294 ;;;
2295 ;;; Apparent state D ---
2296 ;;;
2297 ;;; 13. File looks like it's locked by the calling user and changed, but it's
2298 ;;; actually unregistered.
2299 ;;;
2300 ;;; Potential cause: master file got nuked during window P.
2301 ;;;
2302 ;;; RCS: Checks in the user's version as an initial delta.
2303 ;;; SCCS: will fail with error ut4.
2304 ;;;
2305 ;;; This case is kind of nasty. It means VC may fail to detect the
2306 ;;; loss of previous version information.
2307 ;;;
2308 ;;; 14. File looks like it's locked by the calling user and changed, but it's
2309 ;;; actually unlocked.
2310 ;;;
2311 ;;; Potential cause: self-race in window V, or the checkin happening
2312 ;;; during the window X of someone else's steal-lock or window S of
2313 ;;; someone else's revert.
2314 ;;;
2315 ;;; RCS: ci will fail with "no lock set by <user>".
2316 ;;; SCCS: delta will fail with error ut4.
2317 ;;;
2318 ;;; 15. File looks like it's locked by the calling user and changed, but it's
2319 ;;; actually locked by the calling user and unchanged.
2320 ;;;
2321 ;;; Potential cause: another self-race --- a whole checkin/checkout
2322 ;;; sequence by the calling user would have to land in window R.
2323 ;;;
2324 ;;; SCCS: checks in a redundant delta and leaves the file unlocked as usual.
2325 ;;; RCS: reverts to the file state as of the second user's checkin, leaving
2326 ;;; the file unlocked.
2327 ;;;
2328 ;;; It is theoretically possible that work could be lost under RCS.
2329 ;;;
2330 ;;; 16. File looks like it's locked by the calling user and changed, but it's
2331 ;;; actually locked by a different user.
2332 ;;;
2333 ;;; RCS: ci error: no lock set by <user>
2334 ;;; SCCS: unget will fail with error un2
2335 ;;;
2336 ;;; We can pass these errors up to the user.
2337 ;;;
2338 ;;; Apparent state E ---
2339 ;;;
2340 ;;; 17. File looks like it's locked by some other user, but it's actually
2341 ;;; unregistered.
2342 ;;;
2343 ;;; As case 13.
2344 ;;;
2345 ;;; 18. File looks like it's locked by some other user, but it's actually
2346 ;;; unlocked.
2347 ;;;
2348 ;;; Potential cause: someone released a lock during window W.
2349 ;;;
2350 ;;; RCS: The calling user will get the lock on the file.
2351 ;;; SCCS: unget -n will fail with cm4.
2352 ;;;
2353 ;;; Either of these consequences will be OK.
2354 ;;;
2355 ;;; 19. File looks like it's locked by some other user, but it's actually
2356 ;;; locked by the calling user and unchanged.
2357 ;;;
2358 ;;; Potential cause: the other user relinquishing a lock followed by
2359 ;;; a self-race, both in window W.
2360 ;;;
2361 ;;; Under both RCS and SCCS, both unlock and lock will succeed, making
2362 ;;; the sequence a no-op.
2363 ;;;
2364 ;;; 20. File looks like it's locked by some other user, but it's actually
2365 ;;; locked by the calling user and changed.
2366 ;;;
2367 ;;; As case 19.
2368 ;;;
2369 ;;; PROBLEM CASES:
2370 ;;;
2371 ;;; In order of decreasing severity:
2372 ;;;
2373 ;;; Cases 11 and 15 under RCS are the only one that potentially lose work.
2374 ;;; They would require a self-race for this to happen.
2375 ;;;
2376 ;;; Case 13 in RCS loses information about previous deltas, retaining
2377 ;;; only the information in the current workfile. This can only happen
2378 ;;; if the master file gets nuked in window P.
2379 ;;;
2380 ;;; Case 3 in RCS and case 15 under SCCS insert a redundant delta with
2381 ;;; no change comment in the master. This would require a self-race in
2382 ;;; window P or R respectively.
2383 ;;;
2384 ;;; Cases 2, 10, 19 and 20 do extra work, but make no changes.
2385 ;;;
2386 ;;; Unfortunately, it appears to me that no recovery is possible in these
2387 ;;; cases. They don't yield error messages, so there's no way to tell that
2388 ;;; a race condition has occurred.
2389 ;;;
2390 ;;; All other cases don't change either the workfile or the master, and
2391 ;;; trigger command errors which the user will see.
2392 ;;;
2393 ;;; Thus, there is no explicit recovery code.
2395 ;;; vc.el ends here