| blob | 54f71fb0d93182d378fd002f4a691d8582347418 |
1 ;;; vc.el --- drive a version-control system from within Emacs
3 ;; Copyright (C) 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
5 ;; Author: Eric S. Raymond <esr@snark.thyrsus.com>
6 ;; Modified by:
7 ;; ttn@netcom.com
8 ;; Per Cederqvist <ceder@lysator.liu.edu>
9 ;; Andre Spiegel <spiegel@bruessel.informatik.uni-stuttgart.de>
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software; you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs; see the file COPYING. If not, write to
25 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
27 ;;; Commentary:
29 ;; This mode is fully documented in the Emacs user's manual.
30 ;;
31 ;; This was designed and implemented by Eric Raymond <esr@snark.thyrsus.com>.
32 ;; Paul Eggert <eggert@twinsun.com>, Sebastian Kremer <sk@thp.uni-koeln.de>,
33 ;; and Richard Stallman contributed valuable criticism, support, and testing.
34 ;; CVS support was added by Per Cederqvist <ceder@lysator.liu.se>
35 ;; in Jan-Feb 1994.
36 ;;
37 ;; Supported version-control systems presently include SCCS, RCS, and CVS.
38 ;; The RCS lock-stealing code doesn't work right unless you use RCS 5.6.2
39 ;; or newer. Currently (January 1994) that is only a beta test release.
40 ;; Even initial checkins will fail if your RCS version is so old that ci
41 ;; doesn't understand -t-; this has been known to happen to people running
42 ;; NExTSTEP 3.0.
43 ;;
44 ;; The RCS code assumes strict locking. You can support the RCS -x option
45 ;; by adding pairs to the vc-master-templates list.
46 ;;
47 ;; Proper function of the SCCS diff commands requires the shellscript vcdiff
48 ;; to be installed somewhere on Emacs's path for executables.
49 ;;
50 ;; If your site uses the ChangeLog convention supported by Emacs, the
51 ;; function vc-comment-to-change-log should prove a useful checkin hook.
52 ;;
53 ;; This code depends on call-process passing back the subprocess exit
54 ;; status. Thus, you need Emacs 18.58 or later to run it. For the
55 ;; vc-directory command to work properly as documented, you need 19.
56 ;; You also need Emacs 19's ring.el.
57 ;;
58 ;; The vc code maintains some internal state in order to reduce expensive
59 ;; version-control operations to a minimum. Some names are only computed
60 ;; once. If you perform version control operations with RCS/SCCS/CVS while
61 ;; vc's back is turned, or move/rename master files while vc is running,
62 ;; vc may get seriously confused. Don't do these things!
63 ;;
64 ;; Developer's notes on some concurrency issues are included at the end of
65 ;; the file.
67 ;;; Code:
76 minor-mode-alist)))
78 ;; General customization
96 ;;; This is duplicated in diff.el.
100 ;;;###autoload
105 "*List of functions called when a buffer is made writable. See `run-hooks.'
106 This hook is only used when the version control system is CVS. It
107 might be useful for sites who uses locking with CVS, or who uses link
110 ;; Header-insertion hair
118 "*Associate static header string templates with file types. A \%s in the
119 template is replaced with the first string associated with the file's
124 "*Special comment delimiters to be used in generating vc headers only.
125 Add an entry in this list if you need to override the normal comment-start
126 and comment-end variables. This will only be necessary if the mode language
129 ;; Default is to be extra careful for super-user.
131 "*Non-nil means be extra-careful in checkout.
132 Verify that the file really is not locked
135 ;; Variables the user doesn't need to know about.
140 ;; In a log entry buffer, this is a local variable
141 ;; that points to the buffer for which it was made
142 ;; (either a file, or a VC dired buffer).
158 ;; Back-portability to Emacs 18
168 ; Conditionally rebind some things for Emacs 18 compatibility
174 ))
179 ;; File property caching
182 "Clear all cached file properties and the comment ring."
185 ;; Note: there is potential for minor lossage here if there is an open
186 ;; log buffer with a nonzero local value of vc-comment-ring-index.
189 ;;; functions that operate on RCS revision numbers
191 ;; vc-occurences and vc-branch-p moved to vc-hooks.el
194 ;; return t if REV is a revision on the trunk
198 ;; return the minor revision number of REV,
199 ;; i.e. the number after the last dot.
203 ;; return the branch part of a revision number REV
206 ;; Random helper functions
216 "Look for a command anywhere on the subprocess-command search path."
229 exec-path)
230 nil)))
233 "Execute a version-control command, notifying user and checking for errors.
234 The command is successful if its exit status does not exceed OKSTATUS.
235 Output from COMMAND goes to buffer *vc*. The last argument of the command is
236 the master name of FILE if LAST is 'MASTER, or the workfile of FILE if LAST is
237 'WORKFILE; this is appended to an optional list of FLAGS."
245 status)
256 flags)
267 ;; Add vc-path to PATH for the execution of this command.
271 process-environment)))
284 status))
285 )
288 )
290 status)
291 )
293 ;; Everything eventually funnels through these functions. To implement
294 ;; support for a new version-control system, add another branch to the
295 ;; vc-backend-dispatch macro and fill it in in each call. The variable
296 ;; vc-master-templates in vc-hooks.el will also have to change.
299 "Execute FORM1, FORM2 or FORM3 depending whether we're using SCCS, RCS or CVS.
300 If FORM3 is RCS, use FORM2 even if we are using CVS. (CVS shares some code
301 with RCS)."
308 )))
310 ;;; Save a bit of the text around POSN in the current buffer, to help
311 ;;; us find the corresponding position again later. This works even
312 ;;; if all markers are destroyed or corrupted.
319 ;;; Return the position of CONTEXT in the current buffer, or nil if we
320 ;;; couldn't find it.
330 ;; Can't use search-backward since the match may continue
331 ;; after point.
333 ;; goto-char doesn't signal an error at
334 ;; beginning of buffer like backward-char would
336 ;; to beginning of OSTRING
340 ;; Most of this was shamelessly lifted from Sebastian Kremer's rcs.el mode.
341 ;; Revert buffer, try to keep point and mark where user expects them in spite
342 ;; of changes because of expanded version-control key words.
343 ;; This is quite important since otherwise typeahead won't work as expected.
347 ;; Use mark-marker to avoid confusion in transient-mark-mode.
350 ;; Make the right thing happen in transient-mark-mode.
352 ;; We may want to reparse the compilation buffer after revert
355 ;; Construct a list; each elt is nil or a buffer
356 ;; iff that buffer is a compilation output buffer
357 ;; that contains markers into the current buffer.
363 compilation-old-error-list
364 compilation-error-list))
379 ;; Reparse affected compilation buffers.
385 ;; Record the position in the compilation buffer of
386 ;; the last error next-error went to.
389 ;; Reparse the error messages as far as they were parsed before.
391 ;; Move the pointer up to find the error we were at before
392 ;; reparsing. Now next-error should properly go to the next one.
398 ;; Restore point and mark
407 ;; Make sure the current buffer and its working file are in sync
408 ;; NOT-URGENT means it is ok to continue if the user says not to save.
414 nil
419 ;; Has the given workfile changed since last checkout?
426 ;; 0 stands for an unknown time; it can't match any mod time.
428 unchanged)))))
431 ;;; If comment is specified, it will be used as an admin or checkin comment.
434 owner version)
437 ;; if there is no master file corresponding, create one
445 ;; if there is no lock on the file, assert one and get it
454 file))
465 )
475 ;; a checked-out version exists, but the user may not own the lock
481 file
484 owner))
486 ;; CVS: changes to the master file need to be
487 ;; merged back into the working file
489 ;; "0" means "added, but not yet committed"
499 "Buffer %s modified; merge file on disc anyhow? "
503 ;; Overlaps detected - what now? Should use some
504 ;; fancy RCS conflict resolving package, or maybe
505 ;; emerge, but for now, simply warn the user with a
506 ;; message.
512 ;; CVS: Buffer is read-only. Make the file "locked", i.e.
513 ;; make the buffer writable, and assert the user to be the locker
524 ;; Sites who make link farms to a read-only gold tree (or
525 ;; something similar) can use the hook below to break the
526 ;; sym-link.
529 ;; OK, user owns the lock on the file
533 ;; give luser a chance to save before checking in.
536 ;; Revert if file is unchanged and buffer is too.
537 ;; If buffer is modified, that means the user just said no
538 ;; to saving it; in that case, don't revert,
539 ;; because the user might intend to save
540 ;; after finishing the log entry.
543 ;; DO NOT revert the file without asking the user!
549 ;; user may want to set nonstandard parameters
553 ;; OK, let's do the checkin
555 )))))
558 ;; We've accepted a log comment, now do a vc-next-action using it on all
559 ;; marked files.
568 nil t)
570 )
572 ;; Here's the major entry point.
574 ;;;###autoload
576 "Do the next logical checkin or checkout operation on the current file.
577 If you call this from within a VC dired buffer with no files marked,
578 it will operate on the file in the current line.
579 If you call this from within a VC dired buffer, and one or more
580 files are marked, it will accept a log message and then operate on
581 each one. The log message will be used as a comment for any register
582 or checkin operations, but ignored when doing checkouts. Attempted
583 lock steals will raise an error.
584 A prefix argument lets you specify the version number to use.
586 For RCS and SCCS files:
587 If the file is not already registered, this registers it for version
588 control and then retrieves a writable, locked copy for editing.
589 If the file is registered and not locked by anyone, this checks out
590 a writable and locked file ready for editing.
591 If the file is checked out and locked by the calling user, this
592 first checks to see if the file has changed since checkout. If not,
593 it performs a revert.
594 If the file has been changed, this pops up a buffer for entry
595 of a log message; when the message has been entered, it checks in the
596 resulting changes along with the log message as change commentary. If
597 the variable `vc-keep-workfiles' is non-nil (which is its default), a
598 read-only copy of the changed file is left in place afterwards.
599 If the file is registered and locked by someone else, you are given
600 the option to steal the lock.
602 For CVS files:
603 If the file is not already registered, this registers it for version
605 If the file is added but not committed, it is committed.
606 If the file has not been changed, neither in your working area or
607 in the repository, a message is printed and nothing is done.
608 If your working file is changed, but the repository file is
609 unchanged, this pops up a buffer for entry of a log message; when the
610 message has been entered, it checks in the resulting changes along
611 with the logmessage as change commentary. A writable file is retained.
612 If the repository file is changed, you are asked if you want to
613 merge in the changes into your working copy."
622 "Enter a change comment for the marked files."
631 ;;; These functions help the vc-next-action entry point
634 "Retrieve a writable copy of the latest version of the current buffer's file."
636 )
638 ;;;###autoload
640 "Register the current file into your version-control system."
648 ;; Watch out for new buffers of size 0: the corresponding file
649 ;; does not exist yet, even though buffer-modified-p is nil.
656 buffer-file-name
660 )
663 ;; If the given file is in the current buffer,
664 ;; either revert on it so we see expanded keyworks,
665 ;; or unvisit it (depending on vc-keep-workfiles)
666 ;; NOQUERY if non-nil inhibits confirmation for reverting.
667 ;; NOQUERY should be t *only* if it is known the only difference
668 ;; between the buffer and the file is due to RCS rather than user editing!
679 ;; Accept a comment for an operation on FILE revision REV. If COMMENT
680 ;; is nil, pop up a VC-log buffer, emit MSG, and set the
681 ;; action on close to ACTION; otherwise, do action immediately.
682 ;; Remember the file's buffer in vc-parent-buffer (current one if no file).
683 ;; AFTER-HOOK specifies the local value for vc-log-operation-hook.
709 "Check a file into your version-control system.
710 FILE is the unmodified name of the file. REV should be the base version
711 level to check it in under. COMMENT, if specified, is the checkin comment."
715 nil))
718 "Retrieve a copy of the latest version of the given file."
719 ;; If ftp is on this system and the name matches the ange-ftp format
720 ;; for a remote file, the user is trying something that won't work.
726 )
729 "Steal the lock on the current workfile."
737 file-description owner)))
753 ;; This is called when the notification has been sent.
762 "Check in the file specified by FILE.
763 The optional argument REV may be a string specifying the new version level
764 \(if nil increment the current level). The file is either retained with write
765 permissions zeroed, or deleted (according to the value of `vc-keep-workfiles').
766 If the back-end is CVS, a writable workfile is always kept.
767 COMMENT is a comment string; if omitted, a buffer is
768 popped up to accept a comment."
773 ;;; Here is a checkin hook that may prove useful to sites using the
774 ;;; ChangeLog facility supported by Emacs.
776 "Enter last VC comment into change log file for current buffer's file.
777 Optional arg (interactive prefix) non-nil means prompt for user name and site.
778 Second arg is file name of change log. \
779 If nil, uses `change-log-default-name'."
783 ;; Make sure the defvar for add-log-current-defun-function has been executed
784 ;; before binding it.
788 ;; Don't let add-change-log-entry insert a defun name.
790 end)
791 ;; Call add-log to do half the work.
793 ;; Insert the VC comment, leaving point before it.
796 ;; It starts with an open-paren, as in "(foo): Frobbed."
797 ;; So remove the ": " add-log inserted.
799 ;; Canonicalize the white space between the file name and comment.
801 ;; Indent rest of the text the same way add-log indented the first line.
808 ;; Fill the inserted text, preserving open-parens at bol.
813 ;; Canonicalize the white space at the end of the entry so it is
814 ;; separated from the next entry by a single blank line.
822 "Complete the operation implied by the current log entry."
824 ;; Check and record the comment, if any.
830 ;; Comment too long?
832 ;; Record the comment in the comment ring
836 ))
837 ;; Sync parent buffer in case the user modified it while editing the comment.
838 ;; But not if it is a vc-dired buffer.
843 ;; OK, do it to it
847 vc-log-file
848 vc-log-version
851 ;; save the vc-log-after-operation-hook of log buffer
853 ;; Return to "parent" buffer of this checkin and remove checkin window
858 ;; Now make sure we see the expanded headers
863 ;; Code for access to the comment ring
866 "Cycle backwards through comment history."
874 ;; Initialize the index on the first use of this command
875 ;; so that the first M-p gets index 0, and the first M-n gets
876 ;; index -1.
887 "Cycle forwards through comment history."
892 "Searches backwards through comment history for substring match."
909 "Searches forwards through comment history for substring match."
925 ;; Additional entry points for examining version histories
927 ;;;###autoload
929 "Display diffs between file versions.
930 Normally this compares the current file and buffer with the most recent
931 checked in version of that file. This uses no arguments.
932 With a prefix argument, it reads the file name to use
933 and two version designators specifying which versions to compare."
945 unchanged)
953 ;; Ideally, we'd like at this point to parse the diff so that
954 ;; the buffer effectively goes into compilation mode and we
955 ;; can visit the old and new change locations via next-error.
956 ;; Unfortunately, this is just too painful to do. The basic
957 ;; problem is that the `old' file doesn't exist to be
958 ;; visited. This plays hell with numerous assumptions in
959 ;; the diff.el and compile.el machinery.
971 "For FILE, report diffs between two stored versions REL1 and REL2 of it.
972 If FILE is a directory, generate diffs between versions for all registered
973 files in or below it."
986 " and "
999 )))
1004 )
1009 ;;;###autoload
1011 "Visit version REV of the current buffer in another window.
1012 If the current buffer is named `F', the version is named `F.~REV~'.
1013 If `F.~REV~' already exists, it is used instead of being re-created."
1022 rev))
1029 ;; Header-insertion code
1031 ;;;###autoload
1033 "Insert headers in a file for use with your version-control system.
1034 Headers desired are inserted at the start of the buffer, and are pulled from
1035 the variable `vc-header-alist'."
1054 hdstrings)
1059 vc-static-header-alist))
1060 )
1061 )))))
1063 ;; The VC directory submode. Coopt Dired for this.
1064 ;; All VC commands get mapped into logical equivalents.
1073 minor-mode-map-alist)))
1076 "The augmented Dired minor mode used in VC directory buffers.
1077 All Dired commands operate normally. Users currently locking listed files
1078 are listed in place of the file's owner and group.
1079 Keystrokes bound to VC commands will execute as though they had been called
1080 on a buffer attached to the file named in the current Dired buffer line."
1085 ;; Hack a directory-listing line, plugging in locking-user info in
1086 ;; place of the user and group info. Should have the beneficial
1087 ;; side-effect of shortening the listing line. Each call starts with
1088 ;; point immediately following the dired mark area on the line to be
1089 ;; hacked.
1090 ;;
1091 ;; Simplest possible one:
1092 ;; (insert (concat x "\t")))
1093 ;;
1094 ;; This code, like dired, assumes UNIX -l format.
1097 ;; This hack is used by the CVS code. See vc-locking-user.
1114 )))
1116 ;;; Note in Emacs 18 the following defun gets overridden
1117 ;;; with the symbol 'vc-directory-18. See below.
1118 ;;;###autoload
1120 "Show version-control status of the current directory and subdirectories.
1121 Normally it creates a Dired buffer that lists only the locked files
1122 in all these directories. With a prefix argument, it lists all files."
1127 dired-buf
1128 dired-buf-mod-count)
1137 ;; This uses a semi-documented feature of dired; giving a switch
1138 ;; argument forces the buffer to refresh each time.
1141 dired-listing-switches)
1160 )
1163 ))
1165 ;; Emacs 18 version
1167 "Show version-control status of all files under the current directory."
1190 )
1195 ;; Named-configuration support for SCCS
1204 ))
1210 ;; (replace-regexp (concat ":" (regexp-quote file) "$") (concat ":" newname))
1215 ))
1218 ;; Return the numeric version corresponding to a named snapshot of file
1219 ;; If name is nil or a version number string it's just passed through
1223 name)
1228 )))
1230 ;; Named-configuration entry points
1233 ;; Return an example of why the current directory is not ready to be snapshot
1234 ;; or nil if no such example exists.
1240 nil))
1242 ;;;###autoload
1244 "Make a snapshot called NAME.
1245 The snapshot is made from all registered files at or below the current
1246 directory. For each file, the version level of its latest
1247 version becomes part of the named configuration."
1256 )))
1258 ;;;###autoload
1260 "Retrieve the snapshot called NAME.
1261 This function fails if any files are locked at or below the current directory
1262 Otherwise, all registered files are checked out (unlocked) at their version
1263 levels in the snapshot."
1273 )))
1275 ;; Miscellaneous other entry points
1277 ;;;###autoload
1279 "List the change log of the current buffer in a window."
1297 )
1299 )
1300 )
1302 ;;;###autoload
1304 "Revert the current buffer's file back to the latest checked-in version.
1305 This asks for confirmation if the buffer contents are not identical
1306 to that version.
1307 If the back-end is CVS, this will give you the most recent revision of
1308 the file on the branch you are editing."
1326 )
1327 )
1329 ;;;###autoload
1331 "Get rid of most recently checked in version of this file.
1332 A prefix argument means do not revert the buffer afterwards."
1341 "Remove your version %s from master? "
1344 nil
1350 ))
1352 ;;;###autoload
1354 "Rename file OLD to NEW, and rename its master file likewise."
1356 ;; There are several ways of renaming files under CVS 1.3, but they all
1357 ;; have serious disadvantages. See the FAQ (available from think.com in
1358 ;; pub/cvs/). I'd rather send the user an error, than do something he might
1359 ;; consider to be wrong. When the famous, long-awaited rename database is
1360 ;; implemented things might change for the better. This is unlikely to occur
1361 ;; until CVS 2.0 is released. --ceder 1994-01-23 21:27:51
1377 ;; This had FILE, I changed it to OLD. -- rms.
1381 oldmaster
1395 vc-master-templates)
1399 ; ?? Renaming a file might change its contents due to keyword expansion.
1400 ; We should really check out a new copy if the old copy was precisely equal
1401 ; to some checked in version. However, testing for this is tricky....
1407 ;; This had FILE, I changed it to OLD. -- rms.
1410 nil ;RCS
1411 nil ;CVS
1412 )
1413 )
1415 ;;;###autoload
1417 "Find change log file and add entries from recent RCS logs.
1418 The mark is left at the end of the text prepended to the change log.
1419 With prefix arg of C-u, only find log entries for the current buffer's file.
1420 With any numeric prefix arg, find log entries for all files currently visited.
1421 Otherwise, find log entries for all registered files in the default directory.
1422 From a program, any arguments are passed to the `rcs2log' script."
1429 file)
1435 files))
1443 f)))
1456 "-u"
1461 user-mail-address)
1466 f
1468 args))))
1471 ;; Collect back-end-dependent stuff here
1474 ;; Register a file into the version-control system
1475 ;; Automatically retrieves a read-only version of the file with
1476 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1477 ;; it deletes the workfile.
1492 "-fb"
1506 file))
1509 "add"
1512 )))
1514 )
1517 ;; Retrieve a copy of a saved version into a workfile
1521 ;; Change buffers to get local value of vc-checkin-switches.
1525 ;; Some SCCS implementations allow checking out directly to a
1526 ;; file using the -G option, but then some don't so use the
1527 ;; least common denominator approach and use the -p option
1528 ;; ala RCS.
1536 ;; Some shells make the "" dummy argument into $0
1537 ;; while others use the shell's name as $0 and
1538 ;; use the "" as $1. The if-statement
1539 ;; converts the latter case to the former.
1546 filename
1550 vc-checkout-switches)
1556 vc-checkout-switches))
1558 ;; RCS doesn't let us check out into arbitrary file names directly.
1559 ;; Use `co -p' and make stdout point to the correct file.
1567 ;; See the SCCS case, above, regarding the
1568 ;; if-statement.
1575 filename
1578 vc-checkout-switches)
1586 ;; if no explicit revision was specified,
1587 ;; check out that of the working file
1590 nil)))
1591 vc-checkout-switches)
1601 ;; CVS is much like RCS
1609 workfile
1611 "-p"
1612 vc-checkout-switches)
1616 "update"
1618 vc-checkout-switches))
1619 ))
1624 )
1633 nil ;; RCS
1635 )
1638 ;; Register changes to FILE as level REV with explanatory COMMENT.
1639 ;; Automatically retrieves a read-only version of the file with
1640 ;; keywords expanded if vc-keep-workfiles is non-nil, otherwise
1641 ;; it deletes the workfile.
1642 ;; Adaption for RCS branch support: if this is an explicit checkin,
1643 ;; or if the checkin creates a new branch, set the master file branch
1644 ;; accordingly.
1647 ;; Change buffers to get local value of vc-checkin-switches.
1650 ;; SCCS
1655 vc-checkin-switches)
1660 )
1661 ;; RCS
1663 ;; if this is an explicit check-in to a different branch,
1664 ;; remember the workfile version (in order to remove the lock later)
1674 vc-checkin-switches)
1678 ;; determine the new workfile version and
1679 ;; adjust the master file branch accordingly
1680 ;; (this currently has to be done on every check-in)
1693 ;; exit status of 1 is also accepted.
1694 ;; It means that the lock was removed before.
1697 ;; CVS
1699 ;; explicit check-in to the trunk requires a
1700 ;; double check-in (first unexplicit) (CVS-1.3)
1704 vc-checkin-switches))
1710 vc-checkin-switches)
1711 ;; determine and store the new workfile version
1720 ;; if this was an explicit check-in, remove the sticky tag
1727 )
1730 ;; Revert file to latest checked-in version.
1731 ;; (for RCS, to workfile version)
1734 file
1735 ;; SCCS
1739 ;; RCS
1742 ;; CVS
1749 )
1752 ;; Steal the lock on the current workfile. Needs RCS 5.6.2 or later for -M.
1758 )
1762 )
1765 )
1768 ;; Undo the latest checkin. Note: this code will have to get a lot
1769 ;; smarter when we support multiple branches.
1775 )
1777 )
1780 ;; Print change log associated with FILE to buffer *vc*.
1782 file
1788 ;; Assign to a FILE's latest version a given NAME.
1793 )
1794 )
1797 ;; Get a difference report between two versions of FILE.
1798 ;; Get only a brief comparison report if CMP, a difference report otherwise.
1806 ;; SCCS and RCS shares a lot of code.
1810 "vcdiff"
1814 "-q"
1819 diff-switches
1822 ;; Some RCS versions don't understand "--brief"; work around this.
1826 status)))
1827 ;; CVS is different.
1828 ;; cmp is not yet implemented -- we always do a full diff.
1831 ;; This file is added but not yet committed; there is no master file.
1832 ;; diff it against /dev/null.
1838 diff-switches
1845 diff-switches
1851 ;; Merge in any new changes made to FILE.
1853 file
1857 ))
1860 "Check if the current file has any headers in it."
1866 (re-search-forward "\\$[A-Za-z\300-\326\330-\366\370-\377]+\\(: [\t -#%-\176\240-\377]*\\)?\\$" nil t) ;; RCS
1868 )
1869 ))
1871 ;; Back-end-dependent stuff ends here.
1873 ;; Set up key bindings for use while editing log messages
1876 "Minor mode for driving version-control tools.
1877 These bindings are added to the global keymap when you enter this mode:
1890 While you are entering a change log message for a version, the following
1891 additional bindings will be in effect.
1895 Whenever you do a checkin, your log comment is added to a ring of
1896 saved comments. These can be recalled as follows:
1903 Entry to the change-log submode calls the value of text-mode-hook, then
1904 the value of vc-log-mode-hook.
1906 Global user options:
1907 vc-initial-comment If non-nil, require user to enter a change
1908 comment upon first checkin of the file.
1910 vc-keep-workfiles Non-nil value prevents workfiles from being
1911 deleted when changes are checked in
1913 vc-suppress-confirm Suppresses some confirmation prompts,
1914 notably for reversions.
1916 vc-header-alist Which keywords to insert when adding headers
1919 RCS and CVS.
1921 vc-static-header-alist By default, version headers inserted in C files
1922 get stuffed in a static string area so that
1923 ident(RCS/CVS) or what(SCCS) can see them in
1924 the compiled object code. You can override
1925 this by setting this variable to nil, or change
1926 the header template by changing it.
1928 vc-command-messages if non-nil, display run messages from the
1929 actual version-control utilities (this is
1930 intended primarily for people hacking vc
1931 itself).
1932 "
1945 )
1947 ;; Initialization code, to be done just once at load-time
1949 nil
1956 )
1958 ;;; These things should probably be generally available
1961 "Walk recursively through default directory.
1962 Invoke FUNC f ARGS on each non-directory file f underneath it."
1985 ;;; DEVELOPER'S NOTES ON CONCURRENCY PROBLEMS IN THIS CODE
1986 ;;;
1987 ;;; These may be useful to anyone who has to debug or extend the package.
1988 ;;; (Note that this information corresponds to versions 5.x. Some of it
1989 ;;; might have been invalidated by the additions to support branching
1990 ;;; and RCS keyword lookup. AS, 1995/03/24)
1991 ;;;
1992 ;;; A fundamental problem in VC is that there are time windows between
1993 ;;; vc-next-action's computations of the file's version-control state and
1994 ;;; the actions that change it. This is a window open to lossage in a
1995 ;;; multi-user environment; someone else could nip in and change the state
1996 ;;; of the master during it.
1997 ;;;
1998 ;;; The performance problem is that rlog/prs calls are very expensive; we want
1999 ;;; to avoid them as much as possible.
2000 ;;;
2001 ;;; ANALYSIS:
2002 ;;;
2003 ;;; The performance problem, it turns out, simplifies in practice to the
2004 ;;; problem of making vc-locking-user fast. The two other functions that call
2005 ;;; prs/rlog will not be so commonly used that the slowdown is a problem; one
2006 ;;; makes snapshots, the other deletes the calling user's last change in the
2007 ;;; master.
2008 ;;;
2009 ;;; The race condition implies that we have to either (a) lock the master
2010 ;;; during the entire execution of vc-next-action, or (b) detect and
2011 ;;; recover from errors resulting from dispatch on an out-of-date state.
2012 ;;;
2013 ;;; Alternative (a) appears to be unfeasible. The problem is that we can't
2014 ;;; guarantee that the lock will ever be removed. Suppose a user starts a
2015 ;;; checkin, the change message buffer pops up, and the user, having wandered
2016 ;;; off to do something else, simply forgets about it?
2017 ;;;
2018 ;;; Alternative (b), on the other hand, works well with a cheap way to speed up
2019 ;;; vc-locking-user. Usually, if a file is registered, we can read its locked/
2020 ;;; unlocked state and its current owner from its permissions.
2021 ;;;
2022 ;;; This shortcut will fail if someone has manually changed the workfile's
2023 ;;; permissions; also if developers are munging the workfile in several
2024 ;;; directories, with symlinks to a master (in this latter case, the
2025 ;;; permissions shortcut will fail to detect a lock asserted from another
2026 ;;; directory).
2027 ;;;
2028 ;;; Note that these cases correspond exactly to the errors which could happen
2029 ;;; because of a competing checkin/checkout race in between two instances of
2030 ;;; vc-next-action.
2031 ;;;
2032 ;;; For VC's purposes, a workfile/master pair may have the following states:
2033 ;;;
2034 ;;; A. Unregistered. There is a workfile, there is no master.
2035 ;;;
2036 ;;; B. Registered and not locked by anyone.
2037 ;;;
2038 ;;; C. Locked by calling user and unchanged.
2039 ;;;
2040 ;;; D. Locked by the calling user and changed.
2041 ;;;
2042 ;;; E. Locked by someone other than the calling user.
2043 ;;;
2044 ;;; This makes for 25 states and 20 error conditions. Here's the matrix:
2045 ;;;
2046 ;;; VC's idea of state
2047 ;;; |
2048 ;;; V Actual state RCS action SCCS action Effect
2049 ;;; A B C D E
2050 ;;; A . 1 2 3 4 ci -u -t- admin -fb -i<file> initial admin
2051 ;;; B 5 . 6 7 8 co -l get -e checkout
2052 ;;; C 9 10 . 11 12 co -u unget; get revert
2053 ;;; D 13 14 15 . 16 ci -u -m<comment> delta -y<comment>; get checkin
2054 ;;; E 17 18 19 20 . rcs -u -M ; rcs -l unget -n ; get -g steal lock
2055 ;;;
2056 ;;; All commands take the master file name as a last argument (not shown).
2057 ;;;
2058 ;;; In the discussion below, a "self-race" is a pathological situation in
2059 ;;; which VC operations are being attempted simultaneously by two or more
2060 ;;; Emacsen running under the same username.
2061 ;;;
2062 ;;; The vc-next-action code has the following windows:
2063 ;;;
2064 ;;; Window P:
2065 ;;; Between the check for existence of a master file and the call to
2066 ;;; admin/checkin in vc-buffer-admin (apparent state A). This window may
2067 ;;; never close if the initial-comment feature is on.
2068 ;;;
2069 ;;; Window Q:
2070 ;;; Between the call to vc-workfile-unchanged-p in and the immediately
2071 ;;; following revert (apparent state C).
2072 ;;;
2073 ;;; Window R:
2074 ;;; Between the call to vc-workfile-unchanged-p in and the following
2075 ;;; checkin (apparent state D). This window may never close.
2076 ;;;
2077 ;;; Window S:
2078 ;;; Between the unlock and the immediately following checkout during a
2079 ;;; revert operation (apparent state C). Included in window Q.
2080 ;;;
2081 ;;; Window T:
2082 ;;; Between vc-locking-user and the following checkout (apparent state B).
2083 ;;;
2084 ;;; Window U:
2085 ;;; Between vc-locking-user and the following revert (apparent state C).
2086 ;;; Includes windows Q and S.
2087 ;;;
2088 ;;; Window V:
2089 ;;; Between vc-locking-user and the following checkin (apparent state
2090 ;;; D). This window may never be closed if the user fails to complete the
2091 ;;; checkin message. Includes window R.
2092 ;;;
2093 ;;; Window W:
2094 ;;; Between vc-locking-user and the following steal-lock (apparent
2095 ;;; state E). This window may never close if the user fails to complete
2096 ;;; the steal-lock message. Includes window X.
2097 ;;;
2098 ;;; Window X:
2099 ;;; Between the unlock and the immediately following re-lock during a
2100 ;;; steal-lock operation (apparent state E). This window may never cloce
2101 ;;; if the user fails to complete the steal-lock message.
2102 ;;;
2103 ;;; Errors:
2104 ;;;
2105 ;;; Apparent state A ---
2106 ;;;
2107 ;;; 1. File looked unregistered but is actually registered and not locked.
2108 ;;;
2109 ;;; Potential cause: someone else's admin during window P, with
2110 ;;; caller's admin happening before their checkout.
2111 ;;;
2112 ;;; RCS: ci will fail with a "no lock set by <user>" message.
2113 ;;; SCCS: admin will fail with error (ad19).
2114 ;;;
2115 ;;; We can let these errors be passed up to the user.
2116 ;;;
2117 ;;; 2. File looked unregistered but is actually locked by caller, unchanged.
2118 ;;;
2119 ;;; Potential cause: self-race during window P.
2120 ;;;
2121 ;;; RCS: will revert the file to the last saved version and unlock it.
2122 ;;; SCCS: will fail with error (ad19).
2123 ;;;
2124 ;;; Either of these consequences is acceptable.
2125 ;;;
2126 ;;; 3. File looked unregistered but is actually locked by caller, changed.
2127 ;;;
2128 ;;; Potential cause: self-race during window P.
2129 ;;;
2130 ;;; RCS: will register the caller's workfile as a delta with a
2131 ;;; null change comment (the -t- switch will be ignored).
2132 ;;; SCCS: will fail with error (ad19).
2133 ;;;
2134 ;;; 4. File looked unregistered but is locked by someone else.
2135 ;;;
2136 ;;; Potential cause: someone else's admin during window P, with
2137 ;;; caller's admin happening *after* their checkout.
2138 ;;;
2139 ;;; RCS: will fail with a "no lock set by <user>" message.
2140 ;;; SCCS: will fail with error (ad19).
2141 ;;;
2142 ;;; We can let these errors be passed up to the user.
2143 ;;;
2144 ;;; Apparent state B ---
2145 ;;;
2146 ;;; 5. File looked registered and not locked, but is actually unregistered.
2147 ;;;
2148 ;;; Potential cause: master file got nuked during window P.
2149 ;;;
2150 ;;; RCS: will fail with "RCS/<file>: No such file or directory"
2151 ;;; SCCS: will fail with error ut4.
2152 ;;;
2153 ;;; We can let these errors be passed up to the user.
2154 ;;;
2155 ;;; 6. File looked registered and not locked, but is actually locked by the
2156 ;;; calling user and unchanged.
2157 ;;;
2158 ;;; Potential cause: self-race during window T.
2159 ;;;
2160 ;;; RCS: in the same directory as the previous workfile, co -l will fail
2161 ;;; with "co error: writable foo exists; checkout aborted". In any other
2162 ;;; directory, checkout will succeed.
2163 ;;; SCCS: will fail with ge17.
2164 ;;;
2165 ;;; Either of these consequences is acceptable.
2166 ;;;
2167 ;;; 7. File looked registered and not locked, but is actually locked by the
2168 ;;; calling user and changed.
2169 ;;;
2170 ;;; As case 6.
2171 ;;;
2172 ;;; 8. File looked registered and not locked, but is actually locked by another
2173 ;;; user.
2174 ;;;
2175 ;;; Potential cause: someone else checks it out during window T.
2176 ;;;
2177 ;;; RCS: co error: revision 1.3 already locked by <user>
2178 ;;; SCCS: fails with ge4 (in directory) or ut7 (outside it).
2179 ;;;
2180 ;;; We can let these errors be passed up to the user.
2181 ;;;
2182 ;;; Apparent state C ---
2183 ;;;
2184 ;;; 9. File looks locked by calling user and unchanged, but is unregistered.
2185 ;;;
2186 ;;; As case 5.
2187 ;;;
2188 ;;; 10. File looks locked by calling user and unchanged, but is actually not
2189 ;;; locked.
2190 ;;;
2191 ;;; Potential cause: a self-race in window U, or by the revert's
2192 ;;; landing during window X of some other user's steal-lock or window S
2193 ;;; of another user's revert.
2194 ;;;
2195 ;;; RCS: succeeds, refreshing the file from the identical version in
2196 ;;; the master.
2197 ;;; SCCS: fails with error ut4 (p file nonexistent).
2198 ;;;
2199 ;;; Either of these consequences is acceptable.
2200 ;;;
2201 ;;; 11. File is locked by calling user. It looks unchanged, but is actually
2202 ;;; changed.
2203 ;;;
2204 ;;; Potential cause: the file would have to be touched by a self-race
2205 ;;; during window Q.
2206 ;;;
2207 ;;; The revert will succeed, removing whatever changes came with
2208 ;;; the touch. It is theoretically possible that work could be lost.
2209 ;;;
2210 ;;; 12. File looks like it's locked by the calling user and unchanged, but
2211 ;;; it's actually locked by someone else.
2212 ;;;
2213 ;;; Potential cause: a steal-lock in window V.
2214 ;;;
2215 ;;; RCS: co error: revision <rev> locked by <user>; use co -r or rcs -u
2216 ;;; SCCS: fails with error un2
2217 ;;;
2218 ;;; We can pass these errors up to the user.
2219 ;;;
2220 ;;; Apparent state D ---
2221 ;;;
2222 ;;; 13. File looks like it's locked by the calling user and changed, but it's
2223 ;;; actually unregistered.
2224 ;;;
2225 ;;; Potential cause: master file got nuked during window P.
2226 ;;;
2227 ;;; RCS: Checks in the user's version as an initial delta.
2228 ;;; SCCS: will fail with error ut4.
2229 ;;;
2230 ;;; This case is kind of nasty. It means VC may fail to detect the
2231 ;;; loss of previous version information.
2232 ;;;
2233 ;;; 14. File looks like it's locked by the calling user and changed, but it's
2234 ;;; actually unlocked.
2235 ;;;
2236 ;;; Potential cause: self-race in window V, or the checkin happening
2237 ;;; during the window X of someone else's steal-lock or window S of
2238 ;;; someone else's revert.
2239 ;;;
2240 ;;; RCS: ci will fail with "no lock set by <user>".
2241 ;;; SCCS: delta will fail with error ut4.
2242 ;;;
2243 ;;; 15. File looks like it's locked by the calling user and changed, but it's
2244 ;;; actually locked by the calling user and unchanged.
2245 ;;;
2246 ;;; Potential cause: another self-race --- a whole checkin/checkout
2247 ;;; sequence by the calling user would have to land in window R.
2248 ;;;
2249 ;;; SCCS: checks in a redundant delta and leaves the file unlocked as usual.
2250 ;;; RCS: reverts to the file state as of the second user's checkin, leaving
2251 ;;; the file unlocked.
2252 ;;;
2253 ;;; It is theoretically possible that work could be lost under RCS.
2254 ;;;
2255 ;;; 16. File looks like it's locked by the calling user and changed, but it's
2256 ;;; actually locked by a different user.
2257 ;;;
2258 ;;; RCS: ci error: no lock set by <user>
2259 ;;; SCCS: unget will fail with error un2
2260 ;;;
2261 ;;; We can pass these errors up to the user.
2262 ;;;
2263 ;;; Apparent state E ---
2264 ;;;
2265 ;;; 17. File looks like it's locked by some other user, but it's actually
2266 ;;; unregistered.
2267 ;;;
2268 ;;; As case 13.
2269 ;;;
2270 ;;; 18. File looks like it's locked by some other user, but it's actually
2271 ;;; unlocked.
2272 ;;;
2273 ;;; Potential cause: someone released a lock during window W.
2274 ;;;
2275 ;;; RCS: The calling user will get the lock on the file.
2276 ;;; SCCS: unget -n will fail with cm4.
2277 ;;;
2278 ;;; Either of these consequences will be OK.
2279 ;;;
2280 ;;; 19. File looks like it's locked by some other user, but it's actually
2281 ;;; locked by the calling user and unchanged.
2282 ;;;
2283 ;;; Potential cause: the other user relinquishing a lock followed by
2284 ;;; a self-race, both in window W.
2285 ;;;
2286 ;;; Under both RCS and SCCS, both unlock and lock will succeed, making
2287 ;;; the sequence a no-op.
2288 ;;;
2289 ;;; 20. File looks like it's locked by some other user, but it's actually
2290 ;;; locked by the calling user and changed.
2291 ;;;
2292 ;;; As case 19.
2293 ;;;
2294 ;;; PROBLEM CASES:
2295 ;;;
2296 ;;; In order of decreasing severity:
2297 ;;;
2298 ;;; Cases 11 and 15 under RCS are the only one that potentially lose work.
2299 ;;; They would require a self-race for this to happen.
2300 ;;;
2301 ;;; Case 13 in RCS loses information about previous deltas, retaining
2302 ;;; only the information in the current workfile. This can only happen
2303 ;;; if the master file gets nuked in window P.
2304 ;;;
2305 ;;; Case 3 in RCS and case 15 under SCCS insert a redundant delta with
2306 ;;; no change comment in the master. This would require a self-race in
2307 ;;; window P or R respectively.
2308 ;;;
2309 ;;; Cases 2, 10, 19 and 20 do extra work, but make no changes.
2310 ;;;
2311 ;;; Unfortunately, it appears to me that no recovery is possible in these
2312 ;;; cases. They don't yield error messages, so there's no way to tell that
2313 ;;; a race condition has occurred.
2314 ;;;
2315 ;;; All other cases don't change either the workfile or the master, and
2316 ;;; trigger command errors which the user will see.
2317 ;;;
2318 ;;; Thus, there is no explicit recovery code.
2320 ;;; vc.el ends here