vc.el 152 KB
Newer Older
1
;;; vc.el --- drive a version-control system from within Emacs
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3
;; Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000,
Glenn Morris's avatar
Glenn Morris committed
4
;;   2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
5

6 7
;; Author:     FSF (see below for full credits)
;; Maintainer: Andre Spiegel <spiegel@gnu.org>
Gerd Moellmann's avatar
Gerd Moellmann committed
8
;; Keywords: tools
Eric S. Raymond's avatar
Eric S. Raymond committed
9

10
;; $Id$
11

Eric S. Raymond's avatar
Eric S. Raymond committed
12 13 14 15 16 17 18 19 20 21 22 23 24
;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
Erik Naggum's avatar
Erik Naggum committed
25
;; along with GNU Emacs; see the file COPYING.  If not, write to the
Lute Kamstra's avatar
Lute Kamstra committed
26 27
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
Eric S. Raymond's avatar
Eric S. Raymond committed
28

29 30 31 32 33 34 35 36 37
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
;; <esr@snark.thyrsus.com>.  Over the years, many people have
;; contributed substantial amounts of work to VC.  These include:
;;   Per Cederqvist <ceder@lysator.liu.se>
;;   Paul Eggert <eggert@twinsun.com>
;;   Sebastian Kremer <sk@thp.uni-koeln.de>
;;   Martin Lorentzson <martinl@gnu.org>
Dave Love's avatar
Dave Love committed
38
;;   Dave Love <fx@gnu.org>
39
;;   Stefan Monnier <monnier@cs.yale.edu>
André Spiegel's avatar
André Spiegel committed
40
;;   J.D. Smith <jdsmith@alum.mit.edu>
41 42
;;   Andre Spiegel <spiegel@gnu.org>
;;   Richard Stallman <rms@gnu.org>
André Spiegel's avatar
André Spiegel committed
43
;;   Thien-Thi Nguyen <ttn@gnu.org>
44

Eric S. Raymond's avatar
Eric S. Raymond committed
45 46
;;; Commentary:

47 48
;; This mode is fully documented in the Emacs user's manual.
;;
49 50 51
;; Supported version-control systems presently include CVS, RCS, GNU
;; Arch, Subversion, Bzr, Mercurial, Meta-CVS, and SCCS (or its free
;; replacement, CSSC).
52 53 54
;;
;; Some features will not work with old RCS versions.  Where
;; appropriate, VC finds out which version you have, and allows or
55
;; disallows those features (stealing locks, for example, works only
56
;; from 5.6.2 onwards).
57 58
;; Even initial checkins will fail if your RCS version is so old that ci
;; doesn't understand -t-; this has been known to happen to people running
59
;; NExTSTEP 3.0.
Eric S. Raymond's avatar
Eric S. Raymond committed
60
;;
61
;; You can support the RCS -x option by customizing vc-rcs-master-templates.
Eric S. Raymond's avatar
Eric S. Raymond committed
62 63 64 65
;;
;; Proper function of the SCCS diff commands requires the shellscript vcdiff
;; to be installed somewhere on Emacs's path for executables.
;;
66
;; If your site uses the ChangeLog convention supported by Emacs, the
67 68 69
;; function log-edit-comment-to-change-log could prove a useful checkin hook,
;; although you might prefer to use C-c C-a (i.e. log-edit-insert-changelog)
;; from the commit buffer instead or to set `log-edit-setup-invert'.
70
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
71 72
;; The vc code maintains some internal state in order to reduce expensive
;; version-control operations to a minimum.  Some names are only computed
73
;; once.  If you perform version control operations with the backend while
Eric S. Raymond's avatar
Eric S. Raymond committed
74 75 76 77 78
;; vc's back is turned, or move/rename master files while vc is running,
;; vc may get seriously confused.  Don't do these things!
;;
;; Developer's notes on some concurrency issues are included at the end of
;; the file.
79
;;
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
;; ADDING SUPPORT FOR OTHER BACKENDS
;;
;; VC can use arbitrary version control systems as a backend.  To add
;; support for a new backend named SYS, write a library vc-sys.el that
;; contains functions of the form `vc-sys-...' (note that SYS is in lower
;; case for the function and library names).  VC will use that library if
;; you put the symbol SYS somewhere into the list of
;; `vc-handled-backends'.  Then, for example, if `vc-sys-registered'
;; returns non-nil for a file, all SYS-specific versions of VC commands
;; will be available for that file.
;;
;; VC keeps some per-file information in the form of properties (see
;; vc-file-set/getprop in vc-hooks.el).  The backend-specific functions
;; do not generally need to be aware of these properties.  For example,
;; `vc-sys-workfile-version' should compute the workfile version and
;; return it; it should not look it up in the property, and it needn't
;; store it there either.  However, if a backend-specific function does
;; store a value in a property, that value takes precedence over any
98
;; value that the generic code might want to set (check for uses of
99 100 101 102 103 104
;; the macro `with-vc-properties' in vc.el).
;;
;; In the list of functions below, each identifier needs to be prepended
;; with `vc-sys-'.  Some of the functions are mandatory (marked with a
;; `*'), others are optional (`-').
;;
105 106 107 108 109 110
;; BACKEND PROPERTIES
;;
;; * revision-granularity
;;
;;   Takes no arguments.  Returns either 'file or 'repository.
;;
111 112
;; STATE-QUERYING FUNCTIONS
;;
113
;; * registered (file)
114
;;
115 116 117
;;   Return non-nil if FILE is registered in this backend.  Both this
;;   function as well as `state' should be careful to fail gracefully in the
;;   event that the backend executable is absent.
118
;;
119
;; * state (file)
120 121 122 123 124 125 126
;;
;;   Return the current version control state of FILE.  For a list of
;;   possible values, see `vc-state'.  This function should do a full and
;;   reliable state computation; it is usually called immediately after
;;   C-x v v.  If you want to use a faster heuristic when visiting a
;;   file, put that into `state-heuristic' below.
;;
127
;; - state-heuristic (file)
128 129 130 131 132 133
;;
;;   If provided, this function is used to estimate the version control
;;   state of FILE at visiting time.  It should be considerably faster
;;   than the implementation of `state'.  For a list of possible values,
;;   see the doc string of `vc-state'.
;;
134
;; - dir-state (dir)
135 136 137 138 139 140
;;
;;   If provided, this function is used to find the version control state
;;   of all files in DIR in a fast way.  The function should not return
;;   anything, but rather store the files' states into the corresponding
;;   `vc-state' properties.
;;
141
;; * workfile-version (file)
142 143 144 145 146 147 148 149 150 151
;;
;;   Return the current workfile version of FILE.
;;
;; - latest-on-branch-p (file)
;;
;;   Return non-nil if the current workfile version of FILE is the latest
;;   on its branch.  The default implementation always returns t, which
;;   means that working with non-current versions is not supported by
;;   default.
;;
152
;; * checkout-model (file)
153 154 155 156
;;
;;   Indicate whether FILE needs to be "checked out" before it can be
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
157
;; - workfile-unchanged-p (file)
158 159 160 161 162 163
;;
;;   Return non-nil if FILE is unchanged from its current workfile
;;   version.  This function should do a brief comparison of FILE's
;;   contents with those of the master version.  If the backend does not
;;   have such a brief-comparison feature, the default implementation of
;;   this function can be used, which delegates to a full
164
;;   vc-BACKEND-diff.  (Note that vc-BACKEND-diff must not run
165
;;   asynchronously in this case, see variable `vc-disable-async-diff'.)
166
;;
167
;; - mode-line-string (file)
168 169 170 171 172
;;
;;   If provided, this function should return the VC-specific mode line
;;   string for FILE.  The default implementation deals well with all
;;   states that `vc-state' can return.
;;
173
;; - dired-state-info (file)
174 175 176 177 178 179 180
;;
;;   Translate the `vc-state' property of FILE into a string that can be
;;   used in a vc-dired buffer.  The default implementation deals well
;;   with all states that `vc-state' can return.
;;
;; STATE-CHANGING FUNCTIONS
;;
181
;; * create-repo ()
182 183 184 185 186 187
;;
;;   Create an empty repository in the current directory and initialize 
;;   it so VC mode can add files to it.  For file-oriented systems, this 
;;   need do no more than create a subdirectory with the right name.
;;
;; * register (files &optional rev comment)
188
;;
189 190 191
;;   Register FILES in this backend.  Optionally, an initial revision REV
;;   and an initial description of the file, COMMENT, may be specified,
;;   but it is not guaranteed that the backend will do anything with this.
192
;;   The implementation should pass the value of vc-register-switches
193 194
;;   to the backend command.  (Note: in older versions of VC, this 
;;   command took a single file argument and not a list.)
195
;;
196 197 198 199 200 201
;; - init-version (file)
;;
;;   The initial version to use when registering FILE if one is not
;;   specified by the user.  If not provided, the variable
;;   vc-default-init-version is used instead.
;;
202
;; - responsible-p (file)
203 204 205 206 207 208 209
;;
;;   Return non-nil if this backend considers itself "responsible" for
;;   FILE, which can also be a directory.  This function is used to find
;;   out what backend to use for registration of new files and for things
;;   like change log generation.  The default implementation always
;;   returns nil.
;;
210
;; - could-register (file)
211 212 213 214
;;
;;   Return non-nil if FILE could be registered under this backend.  The
;;   default implementation always returns t.
;;
215
;; - receive-file (file rev)
216 217 218 219 220 221 222 223 224 225 226 227
;;
;;   Let this backend "receive" a file that is already registered under
;;   another backend.  The default implementation simply calls `register'
;;   for FILE, but it can be overridden to do something more specific,
;;   e.g. keep revision numbers consistent or choose editing modes for
;;   FILE that resemble those of the other backend.
;;
;; - unregister (file)
;;
;;   Unregister FILE from this backend.  This is only needed if this
;;   backend may be used as a "more local" backend for temporary editing.
;;
228
;; * checkin (files rev comment)
229
;;
230 231 232 233 234 235
;;   Commit changes in FILES to this backend.  If REV is non-nil, that
;;   should become the new revision number (not all backends do
;;   anything with it).  COMMENT is used as a check-in comment.  The
;;   implementation should pass the value of vc-checkin-switches to
;;   the backend command. (Note: in older versions of VC, this 
;;   command took a single file argument and not a list.)
236
;;
237 238 239 240 241 242 243
;; * find-version (file rev buffer)
;;
;;   Fetch revision REV of file FILE and put it into BUFFER.
;;   If REV is the empty string, fetch the head of the trunk.
;;   The implementation should pass the value of vc-checkout-switches
;;   to the backend command.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
244
;; * checkout (file &optional editable rev)
245 246 247 248
;;
;;   Check out revision REV of FILE into the working area.  If EDITABLE
;;   is non-nil, FILE should be writable by the user and if locking is
;;   used for FILE, a lock should also be set.  If REV is non-nil, that
249 250 251 252
;;   is the revision to check out (default is current workfile version).
;;   If REV is t, that means to check out the head of the current branch;
;;   if it is the empty string, check out the head of the trunk.
;;   The implementation should pass the value of vc-checkout-switches
253
;;   to the backend command.
254
;;
255
;; * revert (file &optional contents-done)
256
;;
257 258 259 260
;;   Revert FILE back to the current workfile version.  If optional
;;   arg CONTENTS-DONE is non-nil, then the contents of FILE have
;;   already been reverted from a version backup, and this function
;;   only needs to update the status of FILE within the backend.
261
;;
262
;; - rollback (files)
263
;;
264 265 266 267 268 269
;;   Remove the tip version of each of FILES from the repository.  If
;;   this function is not provided, trying to cancel a version is
;;   caught as an error.  (Most backends don't provide it.)  (Also
;;   note that older versions of this backend command were called
;;   'cancel-version' and took a single file arg, not a list of
;;   files.)
270
;;
271
;; - merge (file rev1 rev2)
272 273 274
;;
;;   Merge the changes between REV1 and REV2 into the current working file.
;;
275
;; - merge-news (file)
276 277 278
;;
;;   Merge recent changes from the current branch into FILE.
;;
279
;; - steal-lock (file &optional version)
280 281 282 283 284 285 286 287
;;
;;   Steal any lock on the current workfile version of FILE, or on
;;   VERSION if that is provided.  This function is only needed if
;;   locking is used for files under this backend, and if files can
;;   indeed be locked by other users.
;;
;; HISTORY FUNCTIONS
;;
288
;; * print-log (files &optional buffer)
289
;;
290 291 292
;;   Insert the revision log for FILES into BUFFER, or the *vc* buffer
;;   if BUFFER is nil.  (Note: older versions of this function expected
;;   only a single file argument.)
293
;;
294 295 296 297 298 299
;; - log-view-mode ()
;;
;;   Mode to use for the output of print-log.  This defaults to
;;   `log-view-mode' and is expected to be changed (if at all) to a derived
;;   mode of `log-view-mode'.
;;
300
;; - show-log-entry (version)
301 302 303 304 305
;;
;;   If provided, search the log entry for VERSION in the current buffer,
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
306
;; - wash-log (file)
307 308 309 310
;;
;;   Remove all non-comment information from the output of print-log.  The
;;   default implementation of this function works for RCS-style logs.
;;
311
;; - logentry-check ()
312 313 314 315 316 317
;;
;;   If defined, this function is run to find out whether the user
;;   entered a valid log entry for check-in.  The log entry is in the
;;   current buffer, and if it is not a valid one, the function should
;;   throw an error.
;;
318
;; - comment-history (file)
319 320 321 322 323 324 325
;;
;;   Return a string containing all log entries that were made for FILE.
;;   This is used for transferring a file from one backend to another,
;;   retaining comment information.  The default implementation of this
;;   function does this by calling print-log and then wash-log, and
;;   returning the resulting buffer contents as a string.
;;
326
;; - update-changelog (files)
327 328 329 330 331 332
;;
;;   Using recent log entries, create ChangeLog entries for FILES, or for
;;   all files at or below the default-directory if FILES is nil.  The
;;   default implementation runs rcs2log, which handles RCS- and
;;   CVS-style logs.
;;
333
;; * diff (file &optional rev1 rev2 buffer)
334
;;
335 336 337 338 339 340 341 342 343
;;   Insert the diff for FILE into BUFFER, or the *vc-diff* buffer if
;;   BUFFER is nil.  If REV1 and REV2 are non-nil, report differences
;;   from REV1 to REV2.  If REV1 is nil, use the current workfile
;;   version (as found in the repository) as the older version; if
;;   REV2 is nil, use the current workfile contents as the newer
;;   version.  This function should pass the value of (vc-switches
;;   BACKEND 'diff) to the backend command.  It should return a status
;;   of either 0 (no differences found), or 1 (either non-empty diff
;;   or the diff is run asynchronously).
344
;;
345 346 347 348 349
;; - revision-completion-table (file)
;;
;;   Return a completion table for existing revisions of FILE.
;;   The default is to not use any completion table.
;;
350
;; - diff-tree (dir &optional rev1 rev2)
351 352
;;
;;   Insert the diff for all files at and below DIR into the *vc-diff*
353
;;   buffer.  The meaning of REV1 and REV2 is the same as for
354 355 356
;;   vc-BACKEND-diff.  The default implementation does an explicit tree
;;   walk, calling vc-BACKEND-diff for each individual file.
;;
357
;; - annotate-command (file buf &optional rev)
358
;;
359 360 361 362 363
;;   If this function is provided, it should produce an annotated display
;;   of FILE in BUF, relative to version REV.  Annotation means each line
;;   of FILE displayed is prefixed with version information associated with
;;   its addition (deleted lines leave no history) and that the text of the
;;   file is fontified according to age.
364
;;
365
;; - annotate-time ()
366 367
;;
;;   Only required if `annotate-command' is defined for the backend.
368 369 370 371
;;   Return the time of the next line of annotation at or after point,
;;   as a floating point fractional number of days.  The helper
;;   function `vc-annotate-convert-time' may be useful for converting
;;   multi-part times as returned by `current-time' and `encode-time'
Pavel Janík's avatar
Pavel Janík committed
372
;;   to this format.  Return nil if no more lines of annotation appear
373 374 375
;;   in the buffer.  You can safely assume that point is placed at the
;;   beginning of each line, starting at `point-min'.  The buffer that
;;   point is placed in is the Annotate output, as defined by the
376 377
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
378 379 380 381 382 383 384 385
;;
;; - annotate-current-time ()
;;
;;   Only required if `annotate-command' is defined for the backend,
;;   AND you'd like the current time considered to be anything besides
;;   (vs-annotate-convert-time (current-time)) -- i.e. the current
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
386
;;
387 388 389 390 391 392 393
;; - annotate-extract-revision-at-line ()
;;
;;   Only required if `annotate-command' is defined for the backend.
;;   Invoked from a buffer in vc-annotate-mode, return the revision
;;   corresponding to the current line, or nil if there is no revision
;;   corresponding to the current line.
;;
394 395
;; SNAPSHOT SYSTEM
;;
396
;; - create-snapshot (dir name branchp)
397 398 399 400 401 402 403 404 405 406 407 408 409 410
;;
;;   Take a snapshot of the current state of files under DIR and name it
;;   NAME.  This should make sure that files are up-to-date before
;;   proceeding with the action.  DIR can also be a file and if BRANCHP
;;   is specified, NAME should be created as a branch and DIR should be
;;   checked out under this new branch.  The default implementation does
;;   not support branches but does a sanity check, a tree traversal and
;;   for each file calls `assign-name'.
;;
;; - assign-name (file name)
;;
;;   Give name NAME to the current version of FILE, assuming it is
;;   up-to-date.  Only used by the default version of `create-snapshot'.
;;
411
;; - retrieve-snapshot (dir name update)
412 413 414 415 416 417 418 419 420 421
;;
;;   Retrieve a named snapshot of all registered files at or below DIR.
;;   If UPDATE is non-nil, then update buffers of any files in the
;;   snapshot that are currently visited.  The default implementation
;;   does a sanity check whether there aren't any uncommitted changes at
;;   or below DIR, and then performs a tree walk, using the `checkout'
;;   function to retrieve the corresponding versions.
;;
;; MISCELLANEOUS
;;
422
;; - make-version-backups-p (file)
423 424 425 426 427 428
;;
;;   Return non-nil if unmodified repository versions of FILE should be
;;   backed up locally.  If this is done, VC can perform `diff' and
;;   `revert' operations itself, without calling the backend system.  The
;;   default implementation always returns nil.
;;
429 430 431 432
;; - repository-hostname (dirname)
;;
;;   Return the hostname that the backend will have to contact
;;   in order to operate on a file in DIRNAME.  If the return value
433
;;   is nil, it means that the repository is local.
434 435 436
;;   This function is used in `vc-stay-local-p' which backends can use
;;   for their convenience.
;;
437 438
;; - previous-version (file rev)
;;
439 440 441 442 443 444 445
;;   Return the version number that precedes REV for FILE, or nil if no such
;;   version exists.
;;
;; - next-version (file rev)
;;
;;   Return the version number that follows REV for FILE, or nil if no such
;;   version exists.
446
;;
447
;; - check-headers ()
448 449 450
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
451
;; - clear-headers ()
452 453 454 455 456 457 458 459
;;
;;   In the current buffer, reset all version headers to their unexpanded
;;   form.  This function should be provided if the state-querying code
;;   for this backend uses the version headers to determine the state of
;;   a file.  This function will then be called whenever VC changes the
;;   version control state in such a way that the headers would give
;;   wrong information.
;;
460 461 462 463 464 465
;; - delete-file (file)
;;
;;   Delete FILE and mark it as deleted in the repository.  If this
;;   function is not provided, the command `vc-delete-file' will
;;   signal an error.
;;
466
;; - rename-file (old new)
467 468
;;
;;   Rename file OLD to NEW, both in the working area and in the
469 470
;;   repository.  If this function is not provided, the renaming
;;   will be done by (vc-delete-file old) and (vc-register new).
Luc Teirlinck's avatar
Luc Teirlinck committed
471
;;
472 473
;; - find-file-hook ()
;;
474
;;   Operation called in current buffer when opening a file.  This can
475
;;   be used by the backend to setup some local variables it might need.
476 477 478 479 480
;
;; - find-file-not-found-hook ()
;;
;;   Operation called in current buffer when opening a non-existing file.
;;   By default, this asks the user if she wants to check out the file.
481

482
;;; Code:
483

Eric S. Raymond's avatar
Eric S. Raymond committed
484
(require 'vc-hooks)
485
(require 'ring)
486
(eval-when-compile
487
  (require 'cl)
488 489 490
  (require 'compile)
  (require 'dired)      ; for dired-map-over-marks macro
  (require 'dired-aux))	; for dired-kill-{line,tree}
491 492 493 494 495

(if (not (assoc 'vc-parent-buffer minor-mode-alist))
    (setq minor-mode-alist
	  (cons '(vc-parent-buffer vc-parent-buffer-name)
		minor-mode-alist)))
Eric S. Raymond's avatar
Eric S. Raymond committed
496 497 498

;; General customization

499 500 501 502 503
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-suppress-confirm nil
504
  "If non-nil, treat user as expert; suppress yes-no prompts on some things."
505 506 507
  :type 'boolean
  :group 'vc)

508
(defcustom vc-delete-logbuf-window t
509
  "If non-nil, delete the *VC-log* buffer and window after each logical action.
510 511 512 513 514 515
If nil, bury that buffer instead.
This is most useful if you have multiple windows on a frame and would like to
preserve the setting."
  :type 'boolean
  :group 'vc)

516
(defcustom vc-initial-comment nil
517
  "If non-nil, prompt for initial comment when a file is registered."
518 519 520
  :type 'boolean
  :group 'vc)

521
(defcustom vc-default-init-version "1.1"
522
  "A string used as the default version number when a new file is registered.
523 524
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
525
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
526 527
  :group 'vc
  :version "20.3")
528

529
(defcustom vc-command-messages nil
530
  "If non-nil, display run messages from back-end commands."
531 532 533 534
  :type 'boolean
  :group 'vc)

(defcustom vc-checkin-switches nil
535
  "A string or list of strings specifying extra switches for checkin.
536 537 538 539 540 541 542 543 544
These are passed to the checkin program by \\[vc-checkin]."
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc)

(defcustom vc-checkout-switches nil
545
  "A string or list of strings specifying extra switches for checkout.
546 547 548 549 550 551 552 553 554
These are passed to the checkout program by \\[vc-checkout]."
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc)

(defcustom vc-register-switches nil
555
  "A string or list of strings; extra switches for registering a file.
556 557 558 559 560 561 562 563
These are passed to the checkin program by \\[vc-register]."
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc)

564
(defcustom vc-dired-listing-switches "-al"
565
  "Switches passed to `ls' for vc-dired.  MUST contain the `l' option."
566 567
  :type 'string
  :group 'vc
568
  :version "21.1")
569

570
(defcustom vc-dired-recurse t
571
  "If non-nil, show directory trees recursively in VC Dired."
572 573 574 575 576
  :type 'boolean
  :group 'vc
  :version "20.3")

(defcustom vc-dired-terse-display t
577
  "If non-nil, show only locked files in VC Dired."
578 579 580 581
  :type 'boolean
  :group 'vc
  :version "20.3")

582 583
(defcustom vc-directory-exclusion-list '("SCCS" "RCS" "CVS" "MCVS" ".svn" 
					 ".hg" ".bzr" "{arch}")
584
  "List of directory names to be ignored when walking directory trees."
585 586
  :type '(repeat string)
  :group 'vc)
587

588
(defcustom vc-diff-switches nil
589
  "A string or list of strings specifying switches for diff under VC.
590 591 592 593 594
When running diff under a given BACKEND, VC concatenates the values of
`diff-switches', `vc-diff-switches', and `vc-BACKEND-diff-switches' to
get the switches for that command.  Thus, `vc-diff-switches' should
contain switches that are specific to version control, but not
specific to any particular backend."
595 596 597 598 599 600 601 602
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc
  :version "21.1")

603 604 605 606 607 608 609
(defcustom vc-diff-knows-L nil
  "*Indicates whether diff understands the -L option.
The value is either `yes', `no', or nil.  If it is nil, VC tries
to use -L and sets this variable to remember whether it worked."
  :type '(choice (const :tag "Work out" nil) (const yes) (const no))
  :group 'vc)

610
(defcustom vc-allow-async-revert nil
611
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
612 613 614 615 616
Enabling this option means that you can confirm a revert operation even
if the local changes in the file have not been found and displayed yet."
  :type '(choice (const :tag "No" nil)
                 (const :tag "Yes" t))
  :group 'vc
617
  :version "22.1")
618

André Spiegel's avatar
André Spiegel committed
619 620
;;;###autoload
(defcustom vc-checkout-hook nil
621
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
622 623 624 625 626
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

627
(defcustom vc-annotate-display-mode 'fullscale
André Spiegel's avatar
André Spiegel committed
628
  "Which mode to color the output of \\[vc-annotate] with by default."
629
  :type '(choice (const :tag "By Color Map Range" nil)
630 631 632 633 634 635
		 (const :tag "Scale to Oldest" scale)
		 (const :tag "Scale Oldest->Newest" fullscale)
		 (number :tag "Specify Fractional Number of Days"
			 :value "20.5"))
  :group 'vc)

636 637
;;;###autoload
(defcustom vc-checkin-hook nil
638
  "Normal hook (list of functions) run after a checkin is done.
639
See also `log-edit-done-hook'."
640
  :type 'hook
641
  :options '(log-edit-comment-to-change-log)
642 643 644 645
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
646
  "Normal hook (list of functions) run before a file is checked in.
647 648 649 650 651
See `run-hooks'."
  :type 'hook
  :group 'vc)

(defcustom vc-logentry-check-hook nil
652
  "Normal hook run by `vc-backend-logentry-check'.
653 654 655 656
Use this to impose your own rules on the entry in addition to any the
version control backend imposes itself."
  :type 'hook
  :group 'vc)
657

658
;; Annotate customization
659
(defcustom vc-annotate-color-map
660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708
  (if (and (tty-display-color-p) (<= (display-color-cells) 8))
      ;; A custom sorted TTY colormap
      (let* ((colors
	      (sort
	       (delq nil
		     (mapcar (lambda (x)
			       (if (not (or
					 (string-equal (car x) "white")
					 (string-equal (car x) "black") ))
				   (car x)))
			     (tty-color-alist)))
	       (lambda (a b)
		 (cond
		  ((or (string-equal a "red") (string-equal b "blue")) t)
		  ((or (string-equal b "red") (string-equal a "blue")) nil)
		  ((string-equal a "yellow") t)
		  ((string-equal b "yellow") nil)
		  ((string-equal a "cyan") t)
		  ((string-equal b "cyan") nil)
		  ((string-equal a "green") t)
		  ((string-equal b "green") nil)
		  ((string-equal a "magenta") t)
		  ((string-equal b "magenta") nil)
		  (t (string< a b))))))
	     (date 20.)
	     (delta (/ (- 360. date) (1- (length colors)))))
	(mapcar (lambda (x)
		  (prog1
		      (cons date x)
		    (setq date (+ date delta)))) colors))
    ;; Normal colormap: hue stepped from 0-240deg, value=1., saturation=0.75
    '(( 20. . "#FF3F3F")
      ( 40. . "#FF6C3F")
      ( 60. . "#FF993F")
      ( 80. . "#FFC63F")
      (100. . "#FFF33F")
      (120. . "#DDFF3F")
      (140. . "#B0FF3F")
      (160. . "#83FF3F")
      (180. . "#56FF3F")
      (200. . "#3FFF56")
      (220. . "#3FFF83")
      (240. . "#3FFFB0")
      (260. . "#3FFFDD")
      (280. . "#3FF3FF")
      (300. . "#3FC6FF")
      (320. . "#3F99FF")
      (340. . "#3F6CFF")
      (360. . "#3F3FFF")))
709
  "Association list of age versus color, for \\[vc-annotate].
710 711 712 713
Ages are given in units of fractional days.  Default is eighteen
steps using a twenty day increment, from red to blue.  For TTY
displays with 8 or fewer colors, the default is red to blue with
all other colors between (excluding black and white)."
714
  :type 'alist
715 716
  :group 'vc)

717
(defcustom vc-annotate-very-old-color "#3F3FFF"
718
  "Color for lines older than the current color range in \\[vc-annotate]]."
719 720 721 722
  :type 'string
  :group 'vc)

(defcustom vc-annotate-background "black"
723
  "Background color for \\[vc-annotate].
724 725 726 727 728
Default color is used if nil."
  :type 'string
  :group 'vc)

(defcustom vc-annotate-menu-elements '(2 0.5 0.1 0.01)
729
  "Menu elements for the mode-specific menu of VC-Annotate mode.
730
List of factors, used to expand/compress the time scale.  See `vc-annotate'."
731
  :type '(repeat number)
732 733
  :group 'vc)

734 735
(defvar vc-annotate-mode-map
  (let ((m (make-sparse-keymap)))
736 737 738 739 740 741 742
    (define-key m "A" 'vc-annotate-revision-previous-to-line)
    (define-key m "D" 'vc-annotate-show-diff-revision-at-line)
    (define-key m "J" 'vc-annotate-revision-at-line)
    (define-key m "L" 'vc-annotate-show-log-revision-at-line)
    (define-key m "N" 'vc-annotate-next-version)
    (define-key m "P" 'vc-annotate-prev-version)
    (define-key m "W" 'vc-annotate-workfile-version)
743 744
    m)
  "Local keymap used for VC-Annotate mode.")
745

Eric S. Raymond's avatar
Eric S. Raymond committed
746 747
;; Header-insertion hair

748
(defcustom vc-static-header-alist
749
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
750
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
751 752
  "*Associate static header string templates with file types.
A \%s in the template is replaced with the first string associated with
753
the file's version control type in `vc-header-alist'."
754 755 756 757
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
758

759
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
760
  '((nroff-mode ".\\\"" ""))
André Spiegel's avatar
André Spiegel committed
761
  "*Special comment delimiters for generating VC headers.
762 763
Add an entry in this list if you need to override the normal `comment-start'
and `comment-end' variables.  This will only be necessary if the mode language
764 765 766 767 768 769
is sensitive to blank lines."
  :type '(repeat (list :format "%v"
		       (symbol :tag "Mode")
		       (string :tag "Comment Start")
		       (string :tag "Comment End")))
  :group 'vc)
Eric S. Raymond's avatar
Eric S. Raymond committed
770

771
(defcustom vc-checkout-carefully (= (user-uid) 0)
772
  "*Non-nil means be extra-careful in checkout.
773
Verify that the file really is not locked
774 775 776
and that its contents match what the master file says."
  :type 'boolean
  :group 'vc)
777 778 779
(make-obsolete-variable 'vc-checkout-carefully
                        "the corresponding checks are always done now."
                        "21.1")
780

781

Eric S. Raymond's avatar
Eric S. Raymond committed
782 783
;; Variables the user doesn't need to know about.
(defvar vc-log-operation nil)
784
(defvar vc-log-after-operation-hook nil)
785

Richard M. Stallman's avatar
Richard M. Stallman committed
786 787 788
;; In a log entry buffer, this is a local variable
;; that points to the buffer for which it was made
;; (either a file, or a VC dired buffer).
789
(defvar vc-parent-buffer nil)
790
(put 'vc-parent-buffer 'permanent-local t)
791
(defvar vc-parent-buffer-name nil)
792
(put 'vc-parent-buffer-name 'permanent-local t)
Eric S. Raymond's avatar
Eric S. Raymond committed
793

794 795 796 797 798
(defvar vc-disable-async-diff nil
  "VC sets this to t locally to disable some async diff operations.
Backends that offer asynchronous diffs should respect this variable
in their implementation of vc-BACKEND-diff.")

799 800 801
(defvar vc-log-file)
(defvar vc-log-version)

802
(defvar vc-dired-mode nil)
803 804
(make-variable-buffer-local 'vc-dired-mode)

805 806 807
;; functions that operate on RCS revision numbers.  This code should
;; also be moved into the backends.  It stays for now, however, since
;; it is used in code below.
808
;;;###autoload
809
(defun vc-trunk-p (rev)
810
  "Return t if REV is a revision on the trunk."
811 812
  (not (eq nil (string-match "\\`[0-9]+\\.[0-9]+\\'" rev))))

813
(defun vc-branch-p (rev)
814
  "Return t if REV is a branch revision."
815 816
  (not (eq nil (string-match "\\`[0-9]+\\(\\.[0-9]+\\.[0-9]+\\)*\\'" rev))))

817
;;;###autoload
818
(defun vc-branch-part (rev)
819
  "Return the branch part of a revision number REV."
820 821 822
  (let ((index (string-match "\\.[0-9]+\\'" rev)))
    (if index
        (substring rev 0 index))))
823

824
(defun vc-minor-part (rev)
825
  "Return the minor version number of a revision number REV."
826 827 828
  (string-match "[0-9]+\\'" rev)
  (substring rev (match-beginning 0) (match-end 0)))

829
(defun vc-default-previous-version (backend file rev)
830 831
  "Return the version number immediately preceding REV for FILE,
or nil if there is no previous version.  This default
832
implementation works for MAJOR.MINOR-style version numbers as
833
used by RCS and CVS."
834 835
  (let ((branch (vc-branch-part rev))
        (minor-num (string-to-number (vc-minor-part rev))))
836 837 838 839 840 841 842 843 844 845 846
    (when branch
      (if (> minor-num 1)
          ;; version does probably not start a branch or release
          (concat branch "." (number-to-string (1- minor-num)))
        (if (vc-trunk-p rev)
            ;; we are at the beginning of the trunk --
            ;; don't know anything to return here
            nil
          ;; we are at the beginning of a branch --
          ;; return version of starting point
          (vc-branch-part branch))))))
847

848 849 850
(defun vc-default-next-version (backend file rev)
  "Return the version number immediately following REV for FILE,
or nil if there is no next version.  This default implementation
851
works for MAJOR.MINOR-style version numbers as used by RCS
852 853 854 855 856 857
and CVS."
  (when (not (string= rev (vc-workfile-version file)))
    (let ((branch (vc-branch-part rev))
	  (minor-num (string-to-number (vc-minor-part rev))))
      (concat branch "." (number-to-string (1+ minor-num))))))

Eric S. Raymond's avatar
Eric S. Raymond committed
858 859
;; File property caching

860
(defun vc-clear-context ()
861
  "Clear all cached file properties."
862
  (interactive)
863
  (fillarray vc-file-prop-obarray 0))
864

865
(defmacro with-vc-properties (file form settings)
André Spiegel's avatar
André Spiegel committed
866 867 868 869
  "Execute FORM, then maybe set per-file properties for FILE.
SETTINGS is an association list of property/value pairs.  After
executing FORM, set those properties from SETTINGS that have not yet
been updated to their corresponding values."
870
  (declare (debug t))
871
  `(let ((vc-touched-properties (list t)))
872 873
     ,form
     (mapcar (lambda (setting)
874
	       (let ((property (car setting)))
875
		 (unless (memq property vc-touched-properties)
876
		   (put (intern ,file vc-file-prop-obarray)
877
			property (cdr setting)))))
878 879
	     ,settings)))

Eric S. Raymond's avatar
Eric S. Raymond committed
880 881
;; Random helper functions

882
(defsubst vc-editable-p (file)
André Spiegel's avatar
André Spiegel committed
883
  "Return non-nil if FILE can be edited."
884
  (or (eq (vc-checkout-model file) 'implicit)
885
      (memq (vc-state file) '(edited needs-merge))))
886

887
;; Two macros for elisp programming
888 889
;;;###autoload
(defmacro with-vc-file (file comment &rest body)
André Spiegel's avatar
André Spiegel committed
890
  "Check out a writable copy of FILE if necessary, then execute BODY.
891 892 893
Check in FILE with COMMENT (a string) after BODY has been executed.
FILE is passed through `expand-file-name'; BODY executed within
`save-excursion'.  If FILE is not under version control, or locked by
894
somebody else, signal error."
895
  (declare (debug t) (indent 2))
896 897 898
  (let ((filevar (make-symbol "file")))
    `(let ((,filevar (expand-file-name ,file)))
       (or (vc-backend ,filevar)
899
           (error "File not under version control: `%s'" file))
900 901
       (unless (vc-editable-p ,filevar)
         (let ((state (vc-state ,filevar)))
902
           (if (stringp state)
903
               (error "`%s' is locking `%s'" state ,filevar)
904 905 906 907 908
             (vc-checkout ,filevar t))))
       (save-excursion
         ,@body)
       (vc-checkin ,filevar nil ,comment))))

909 910
;;;###autoload
(defmacro edit-vc-file (file comment &rest body)
911 912
  "Edit FILE under version control, executing body.
Checkin with COMMENT after executing BODY.
913 914
This macro uses `with-vc-file', passing args to it.
However, before executing BODY, find FILE, and after BODY, save buffer."
915
  (declare (debug t) (indent 2))
916 917 918 919 920 921 922 923
  (let ((filevar (make-symbol "file")))
    `(let ((,filevar (expand-file-name ,file)))
       (with-vc-file
        ,filevar ,comment
        (set-buffer (find-file-noselect ,filevar))
        ,@body
        (save-buffer)))))

924
(defun vc-ensure-vc-buffer ()
925
  "Make sure that the current buffer visits a version-controlled file."
926 927 928
  (if vc-dired-mode
      (set-buffer (find-file-noselect (dired-get-filename)))
    (while vc-parent-buffer
929
      (set-buffer vc-parent-buffer))
930
    (if (not buffer-file-name)
931
	(error "Buffer %s is not associated with a file" (buffer-name))
932 933
      (if (not (vc-backend buffer-file-name))
	  (error "File %s is not under version control" buffer-file-name)))))
934

935
(defun vc-process-filter (p s)
936
  "An alternative output filter for async process P.
937 938
One difference with the default filter is that this inserts S after markers.
Another is that undo information is not kept."
939 940
  (with-current-buffer (process-buffer p)
    (save-excursion
941 942
      (let ((buffer-undo-list t)
            (inhibit-read-only t))
943 944 945 946 947
	(goto-char (process-mark p))
	(insert s)
	(set-marker (process-mark p) (point))))))

(defun vc-setup-buffer (&optional buf)
André Spiegel's avatar
André Spiegel committed
948
  "Prepare BUF for executing a VC command and make it current.
949 950 951 952 953 954 955 956 957 958
BUF defaults to \"*vc*\", can be a string and will be created if necessary."
  (unless buf (setq buf "*vc*"))
  (let ((camefrom (current-buffer))
	(olddir default-directory))
    (set-buffer (get-buffer-create buf))
    (kill-all-local-variables)
    (set (make-local-variable 'vc-parent-buffer) camefrom)
    (set (make-local-variable 'vc-parent-buffer-name)
	 (concat " from " (buffer-name camefrom)))
    (setq default-directory olddir)
959 960
    (let ((buffer-undo-list t)
          (inhibit-read-only t))
961 962 963 964 965 966 967 968 969
      (erase-buffer))))

(defun vc-exec-after (code)
  "Eval CODE when the current buffer's process is done.
If the current buffer has no process, just evaluate CODE.
Else, add CODE to the process' sentinel."
  (let ((proc (get-buffer-process (current-buffer))))
    (cond
     ;; If there's no background process, just execute the code.
970 971 972 973 974
     ;; We used to explicitly call delete-process on exited processes,
     ;; but this led to timing problems causing process output to be
     ;; lost.  Terminated processes get deleted automatically
     ;; anyway. -- cyd
     ((or (null proc) (eq (process-status proc) 'exit))
975 976
      ;; Make sure we've read the process's output before going further.
      (if proc (accept-process-output proc))
977
      (eval code))
978 979 980 981 982 983
     ;; If a process is running, add CODE to the sentinel
     ((eq (process-status proc) 'run)
      (let ((sentinel (process-sentinel proc)))
	(set-process-sentinel proc
	  `(lambda (p s)
	     (with-current-buffer ',(current-buffer)
984 985 986 987 988 989 990
               (save-excursion
                (goto-char (process-mark p))
 	        ,@(append (cdr (cdr (car   ;Strip off (save-exc (goto-char...)
                           (cdr (cdr       ;Strip off (with-current-buffer buf
 			    (car (cdr (cdr ;Strip off (lambda (p s)
                             sentinel))))))))
 			  (list `(vc-exec-after ',code)))))))))
991 992 993 994 995 996
     (t (error "Unexpected process state"))))
  nil)

(defvar vc-post-command-functions nil
  "Hook run at the end of `vc-do-command'.
Each function is called inside the buffer in which the command was run
André Spiegel's avatar
André Spiegel committed
997
and is passed 3 arguments: the COMMAND, the FILE and the FLAGS.")
998

999 1000
(defun vc-delistify (filelist)
  "Smash a FILELIST into a file list string suitable for info messages."
1001
  (if (not filelist) "."  (mapconcat 'identity filelist " ")))
1002

1003
(defvar w32-quote-process-args)
Stefan Monnier's avatar
Stefan Monnier committed
1004
;;;###autoload
1005
(defun vc-do-command (buffer okstatus command file-or-list &rest flags)
André Spiegel's avatar
André Spiegel committed
1006
  "Execute a VC command, notifying user and checking for errors.
1007 1008 1009 1010
Output from COMMAND goes to BUFFER, or *vc* if BUFFER is nil or the
current buffer if BUFFER is t.  If the destination buffer is not
already current, set it up properly and erase it.  The command is
considered successful if its exit status does not exceed OKSTATUS (if
1011
OKSTATUS is nil, that means to ignore error status, if it is `async', that
1012
means not to wait for termination of the subprocess; if it is t it means to
1013 1014 1015
ignore all execution errors).  FILE-OR-LIST is the name of a working file;
it may be a list of files or be nil (to execute commands that don't expect 
a file name or set of files).  If an optional list of FLAGS is present,
1016
that is inserted into the command line before the filename."
1017 1018 1019
  ;; FIXME: file-relative-name can return a bogus result because
  ;; it doesn't look at the actual file-system to see if symlinks
  ;; come into play.
1020 1021 1022 1023
  (let* ((files
	  (mapcar (lambda (f) (file-relative-name (expand-file-name f)))
		  (if (listp file-or-list) file-or-list (list file-or-list))))
         (full-command
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046