vc.el 160 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

Eric S. Raymond's avatar
Eric S. Raymond committed
10
;; $Id$
11

Eric S. Raymond's avatar
Eric S. Raymond committed
12 13 14 15
;; 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
16
;; the Free Software Foundation; either version 3, or (at your option)
Eric S. Raymond's avatar
Eric S. Raymond committed
17 18 19 20 21 22 23 24
;; 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
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
32
;; <esr@thyrsus.com> in 1992.  Over the years, many other people have
33
;; contributed substantial amounts of work to VC.  These include:
34
;;
35 36 37 38
;;   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
39
;;   Dave Love <fx@gnu.org>
40
;;   Stefan Monnier <monnier@cs.yale.edu>
André Spiegel's avatar
André Spiegel committed
41
;;   J.D. Smith <jdsmith@alum.mit.edu>
42 43
;;   Andre Spiegel <spiegel@gnu.org>
;;   Richard Stallman <rms@gnu.org>
André Spiegel's avatar
André Spiegel committed
44
;;   Thien-Thi Nguyen <ttn@gnu.org>
45 46 47 48 49 50 51
;;
;; In July 2007 ESR returned and redesigned the mode to cope better
;; with modern version-control systems that do commits by fileset
;; rather than per individual file.
;;
;; Features in the new version:
;; * Key commands (vc-next-action = C-x v v, vc-print-log = C-x v l, vc-revert
52
;;   = C-x v u, vc-rollback = C-x v c, vc-diff = C-x v =, vc-update = C-x v +)
53 54 55 56
;;   now operate on filesets rather than individual files.
;; * The fileset for a command is either (a) all marked files in VC-dired
;;   mode, (b) the currently visited file if it's under version control,
;;   or (c) the current directory if the visited buffer is not under
57
;;   version control and a wildcarding-enable flag has been set.
58
;;
59 60
;; If you maintain a client of the mode or customize it in your .emacs,
;; note that some backend functions which formerly took single file arguments
61 62
;; now take a list of files.  These include: register, checkin, print-log,
;; rollback, and diff.
63

Eric S. Raymond's avatar
Eric S. Raymond committed
64 65
;;; Commentary:

66 67
;; This mode is fully documented in the Emacs user's manual.
;;
68
;; Supported version-control systems presently include CVS, RCS, GNU
69 70
;; Arch, Subversion, Bzr, Git, Mercurial, Meta-CVS, Monotone and SCCS
;; (or its free replacement, CSSC).
71 72 73
;;
;; Some features will not work with old RCS versions.  Where
;; appropriate, VC finds out which version you have, and allows or
74
;; disallows those features (stealing locks, for example, works only
75
;; from 5.6.2 onwards).
76 77
;; 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
78
;; NExTSTEP 3.0.
Eric S. Raymond's avatar
Eric S. Raymond committed
79
;;
80
;; You can support the RCS -x option by customizing vc-rcs-master-templates.
Eric S. Raymond's avatar
Eric S. Raymond committed
81 82 83 84
;;
;; Proper function of the SCCS diff commands requires the shellscript vcdiff
;; to be installed somewhere on Emacs's path for executables.
;;
85
;; If your site uses the ChangeLog convention supported by Emacs, the
86 87
;; 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')
88
;; from the commit buffer instead or to set `log-edit-setup-invert'.
89
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
90 91
;; The vc code maintains some internal state in order to reduce expensive
;; version-control operations to a minimum.  Some names are only computed
92
;; once.  If you perform version control operations with the backend while
Eric S. Raymond's avatar
Eric S. Raymond committed
93 94 95 96 97
;; 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.
98
;;
99 100 101 102 103 104 105 106 107 108 109 110 111 112
;; 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,
Eric S. Raymond's avatar
Eric S. Raymond committed
113
;; `vc-sys-working-revision' should compute the working revision and
114 115 116
;; 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
117
;; value that the generic code might want to set (check for uses of
118 119 120 121 122 123
;; 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 (`-').
;;
124 125 126 127
;; BACKEND PROPERTIES
;;
;; * revision-granularity
;;
128 129 130 131
;;   Takes no arguments.  Returns either 'file or 'repository.  Backends
;;   that return 'file have per-file revision numbering; backends
;;   that return 'repository have per-repository revision numbering,
;;   so a revision level implicitly identifies a changeset
132
;;
133 134
;; STATE-QUERYING FUNCTIONS
;;
135
;; * registered (file)
136
;;
137
;;   Return non-nil if FILE is registered in this backend.  Both this
138 139 140 141 142 143
;;   function as well as `state' should be careful to fail gracefully
;;   in the event that the backend executable is absent.  It is
;;   preferable that this function's body is autoloaded, that way only
;;   calling vc-registered does not cause the backend to be loaded
;;   (all the vc-FOO-registered functions are called to try to find
;;   the controlling backend for FILE.
144
;;
145
;; * state (file)
146 147 148 149 150 151 152
;;
;;   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.
;;
153
;; - state-heuristic (file)
154 155 156 157 158 159
;;
;;   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'.
;;
160
;; - dir-state (dir)
161 162
;;
;;   If provided, this function is used to find the version control state
Eric S. Raymond's avatar
Eric S. Raymond committed
163 164 165 166 167
;;   of all files in DIR, and all subdirecties of DIR, in a fast way.  
;;   The function should not return anything, but rather store the files' 
;;   states into the corresponding `vc-state' properties.  (Note: in
;;   older versions this method was not required to recurse into 
;;   subdirectories.)
168
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
169
;; * working-revision (file)
170
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
171
;;   Return the working revision of FILE.  This is the revision fetched
172
;;   by the last checkout or upate, not necessarily the same thing as the
173
;;   head or tip revision.  Should return "0" for a file added but not yet
174
;;   committed.
175 176 177
;;
;; - latest-on-branch-p (file)
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
178 179
;;   Return non-nil if the working revision of FILE is the latest revision
;;   on its branch (many VCSes call this the 'tip' or 'head' revision).
180
;;   The default implementation always returns t, which means that
Eric S. Raymond's avatar
Eric S. Raymond committed
181
;;   working with non-current revisions is not supported by default.
182
;;
183
;; * checkout-model (file)
184 185 186 187
;;
;;   Indicate whether FILE needs to be "checked out" before it can be
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
188
;; - workfile-unchanged-p (file)
189
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
190 191 192 193 194 195 196
;;   Return non-nil if FILE is unchanged from the working revision.
;;   This function should do a brief comparison of FILE's contents
;;   with those of the repository master of the working revision.  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 vc-BACKEND-diff.  (Note that vc-BACKEND-diff
;;   must not run asynchronously in this case, see variable
197
;;   `vc-disable-async-diff'.)
198
;;
199
;; - mode-line-string (file)
200
;;
201
;;   If provided, this function should return the VC-specific mode
202
;;   line string for FILE.  The returned string should have a
203 204 205 206
;;   `help-echo' property which is the text to be displayed as a
;;   tooltip when the mouse hovers over the VC entry on the mode-line.
;;   The default implementation deals well with all states that
;;   `vc-state' can return.
207
;;
208
;; - dired-state-info (file)
209 210 211 212 213 214 215
;;
;;   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
;;
216
;; * create-repo (backend)
217
;;
218 219
;;   Create an empty repository in the current directory and initialize
;;   it so VC mode can add files to it.  For file-oriented systems, this
220 221 222
;;   need do no more than create a subdirectory with the right name.
;;
;; * register (files &optional rev comment)
223
;;
224 225 226
;;   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.
227
;;   The implementation should pass the value of vc-register-switches
228
;;   to the backend command.  (Note: in older versions of VC, this
229
;;   command took a single file argument and not a list.)
230
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
231
;; - init-revision (file)
232
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
233
;;   The initial revision to use when registering FILE if one is not
234
;;   specified by the user.  If not provided, the variable
Eric S. Raymond's avatar
Eric S. Raymond committed
235
;;   vc-default-init-revision is used instead.
236
;;
237
;; - responsible-p (file)
238 239 240 241 242 243 244
;;
;;   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.
;;
245
;; - could-register (file)
246 247 248 249
;;
;;   Return non-nil if FILE could be registered under this backend.  The
;;   default implementation always returns t.
;;
250
;; - receive-file (file rev)
251 252 253 254 255 256 257 258 259 260 261 262
;;
;;   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.
;;
263
;; * checkin (files rev comment)
264
;;
265 266 267 268
;;   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
269
;;   the backend command.  (Note: in older versions of VC, this
270
;;   command took a single file argument and not a list.)
271
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
272
;; * find-revision (file rev buffer)
273 274 275 276 277 278
;;
;;   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
279
;; * checkout (file &optional editable rev)
280 281 282 283
;;
;;   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
Eric S. Raymond's avatar
Eric S. Raymond committed
284
;;   is the revision to check out (default is the working revision).
285 286 287
;;   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
288
;;   to the backend command.
289
;;
290
;; * revert (file &optional contents-done)
291
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
292
;;   Revert FILE back to the working revision.  If optional
293 294 295
;;   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.
296
;;
297
;; - rollback (files)
298
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
299 300
;;   Remove the tip revision of each of FILES from the repository.  If
;;   this function is not provided, trying to cancel a revision is
301 302 303 304
;;   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.)
305
;;
306
;; - merge (file rev1 rev2)
307 308 309
;;
;;   Merge the changes between REV1 and REV2 into the current working file.
;;
310
;; - merge-news (file)
311 312 313
;;
;;   Merge recent changes from the current branch into FILE.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
314
;; - steal-lock (file &optional revision)
315
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
316
;;   Steal any lock on the working revision of FILE, or on REVISION if
317 318 319
;;   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.
320
;;
321 322 323 324 325
;; - modify-change-comment (files rev comment)
;;
;;   Modify the change comments associated with the files at the 
;;   given revision.  This is optional, many backends do not support it.
;;
326 327
;; HISTORY FUNCTIONS
;;
328
;; * print-log (files &optional buffer)
329
;;
330 331 332
;;   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.)
333
;;
334 335 336 337 338 339
;; - 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'.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
340
;; - show-log-entry (revision)
341
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
342
;;   If provided, search the log entry for REVISION in the current buffer,
343 344 345
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
346
;; - wash-log (file)
347
;;
348
;;   Remove all non-comment information from the output of print-log.
349
;;
350
;; - logentry-check ()
351 352 353 354 355 356
;;
;;   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.
;;
357
;; - comment-history (file)
358
;;
359
;;   Return a string containing all log entries that were made for FILE.
360 361 362 363 364
;;   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.
;;
365
;; - update-changelog (files)
366 367 368 369 370 371
;;
;;   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.
;;
372
;; * diff (files &optional rev1 rev2 buffer)
373
;;
374 375
;;   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
Eric S. Raymond's avatar
Eric S. Raymond committed
376 377 378 379 380 381 382
;;   from REV1 to REV2.  If REV1 is nil, use the working revision (as
;;   found in the repository) as the older revision; if REV2 is nil,
;;   use the current working-copy contents as the newer revision.  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).
383
;;
384
;; - revision-completion-table (files)
385
;;
386
;;   Return a completion table for existing revisions of FILES.
387 388
;;   The default is to not use any completion table.
;;
389
;; - annotate-command (file buf &optional rev)
390
;;
391
;;   If this function is provided, it should produce an annotated display
Eric S. Raymond's avatar
Eric S. Raymond committed
392
;;   of FILE in BUF, relative to revision REV.  Annotation means each line
393 394 395
;;   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.
396
;;
397
;; - annotate-time ()
398 399
;;
;;   Only required if `annotate-command' is defined for the backend.
400 401 402 403
;;   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
404
;;   to this format.  Return nil if no more lines of annotation appear
405 406 407
;;   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
408 409
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
410 411 412 413 414
;;
;; - 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
415
;;   (vc-annotate-convert-time (current-time)) -- i.e. the current
416 417
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
418
;;
419 420 421 422 423 424 425
;; - 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.
;;
426 427
;; SNAPSHOT SYSTEM
;;
428
;; - create-snapshot (dir name branchp)
429 430 431 432 433 434 435 436 437 438 439
;;
;;   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)
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
440
;;   Give name NAME to the working revision of FILE, assuming it is
441 442
;;   up-to-date.  Only used by the default version of `create-snapshot'.
;;
443
;; - retrieve-snapshot (dir name update)
444 445 446 447 448 449
;;
;;   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'
Eric S. Raymond's avatar
Eric S. Raymond committed
450
;;   function to retrieve the corresponding revisions.
451 452 453
;;
;; MISCELLANEOUS
;;
454
;; - make-version-backups-p (file)
455
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
456
;;   Return non-nil if unmodified repository revisions of FILE should be
457 458 459 460
;;   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.
;;
461 462 463 464
;; - 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
465
;;   is nil, it means that the repository is local.
466 467 468
;;   This function is used in `vc-stay-local-p' which backends can use
;;   for their convenience.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
469
;; - previous-revision (file rev)
470
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
471 472
;;   Return the revision number that precedes REV for FILE, or nil if no such
;;   revision exists.
473
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
474
;; - next-revision (file rev)
475
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
476 477
;;   Return the revision number that follows REV for FILE, or nil if no such
;;   revision exists.
478
;;
479
;; - check-headers ()
480 481 482
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
483
;; - clear-headers ()
484 485 486 487 488 489 490 491
;;
;;   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.
;;
492 493 494 495 496 497
;; - 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.
;;
498
;; - rename-file (old new)
499 500
;;
;;   Rename file OLD to NEW, both in the working area and in the
501 502
;;   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
503
;;
504 505
;; - find-file-hook ()
;;
506
;;   Operation called in current buffer when opening a file.  This can
507
;;   be used by the backend to setup some local variables it might need.
508
;;
509 510 511 512
;; - 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.
513 514 515 516 517 518 519 520 521
;;
;; - extra-menu ()
;;
;;   Return a menu keymap, the items in the keymap will appear at the
;;   end of the Version Control menu.  The goal is to allow backends
;;   to specify extra menu items that appear in the VC menu.  This way
;;   you can provide menu entries for functionality that is specific
;;   to your backend and which does not map to any of the VC generic
;;   concepts.
522

523
;;; Code:
524

Eric S. Raymond's avatar
Eric S. Raymond committed
525
(require 'vc-hooks)
526
(require 'ring)
527
(eval-when-compile
528
  (require 'cl)
529 530 531
  (require 'compile)
  (require 'dired)      ; for dired-map-over-marks macro
  (require 'dired-aux))	; for dired-kill-{line,tree}
532 533 534 535 536

(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
537 538 539

;; General customization

540 541 542 543 544
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-suppress-confirm nil
545
  "If non-nil, treat user as expert; suppress yes-no prompts on some things."
546 547 548
  :type 'boolean
  :group 'vc)

549
(defcustom vc-delete-logbuf-window t
550
  "If non-nil, delete the *VC-log* buffer and window after each logical action.
551 552 553 554 555 556
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)

557
(defcustom vc-initial-comment nil
558
  "If non-nil, prompt for initial comment when a file is registered."
559 560 561
  :type 'boolean
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
562 563
(defcustom vc-default-init-revision "1.1"
  "A string used as the default revision number when a new file is registered.
564 565
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
566
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
567 568
  :group 'vc
  :version "20.3")
569

570
(defcustom vc-command-messages nil
571
  "If non-nil, display run messages from back-end commands."
572 573 574 575
  :type 'boolean
  :group 'vc)

(defcustom vc-checkin-switches nil
576
  "A string or list of strings specifying extra switches for checkin.
577 578 579 580 581 582 583 584 585
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
586
  "A string or list of strings specifying extra switches for checkout.
587 588 589 590 591 592 593 594 595
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
596
  "A string or list of strings; extra switches for registering a file.
597 598 599 600 601 602 603 604
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)

605
(defcustom vc-dired-listing-switches "-al"
606
  "Switches passed to `ls' for vc-dired.  MUST contain the `l' option."
607 608
  :type 'string
  :group 'vc
609
  :version "21.1")
610

611
(defcustom vc-dired-recurse t
612
  "If non-nil, show directory trees recursively in VC Dired."
613 614 615 616 617
  :type 'boolean
  :group 'vc
  :version "20.3")

(defcustom vc-dired-terse-display t
618
  "If non-nil, show only locked or locally modified files in VC Dired."
619 620 621 622
  :type 'boolean
  :group 'vc
  :version "20.3")

623
(defcustom vc-diff-switches nil
624
  "A string or list of strings specifying switches for diff under VC.
625 626 627 628 629
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."
630 631 632 633 634 635 636 637
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc
  :version "21.1")

638 639 640 641 642 643 644
(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)

645
(defcustom vc-allow-async-revert nil
646
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
647 648 649 650 651
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
652
  :version "22.1")
653

André Spiegel's avatar
André Spiegel committed
654 655
;;;###autoload
(defcustom vc-checkout-hook nil
656
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
657 658 659 660 661
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

662
(defcustom vc-annotate-display-mode 'fullscale
André Spiegel's avatar
André Spiegel committed
663
  "Which mode to color the output of \\[vc-annotate] with by default."
664
  :type '(choice (const :tag "By Color Map Range" nil)
665 666 667 668 669 670
		 (const :tag "Scale to Oldest" scale)
		 (const :tag "Scale Oldest->Newest" fullscale)
		 (number :tag "Specify Fractional Number of Days"
			 :value "20.5"))
  :group 'vc)

671 672
;;;###autoload
(defcustom vc-checkin-hook nil
673
  "Normal hook (list of functions) run after commit or file checkin.
674
See also `log-edit-done-hook'."
675
  :type 'hook
676
  :options '(log-edit-comment-to-change-log)
677 678 679 680
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
681
  "Normal hook (list of functions) run before a commit or a file checkin.
682 683 684 685 686
See `run-hooks'."
  :type 'hook
  :group 'vc)

(defcustom vc-logentry-check-hook nil
687
  "Normal hook run by `vc-backend-logentry-check'.
688 689 690 691
Use this to impose your own rules on the entry in addition to any the
version control backend imposes itself."
  :type 'hook
  :group 'vc)
692

693
;; Annotate customization
694
(defcustom vc-annotate-color-map
695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743
  (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")))
744
  "Association list of age versus color, for \\[vc-annotate].
745 746 747 748
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)."
749
  :type 'alist
750 751
  :group 'vc)

752
(defcustom vc-annotate-very-old-color "#3F3FFF"
753
  "Color for lines older than the current color range in \\[vc-annotate]]."
754 755 756 757
  :type 'string
  :group 'vc)

(defcustom vc-annotate-background "black"
758
  "Background color for \\[vc-annotate].
759 760 761 762 763
Default color is used if nil."
  :type 'string
  :group 'vc)

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

769 770
(defvar vc-annotate-mode-map
  (let ((m (make-sparse-keymap)))
771 772 773 774
    (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)
Eric S. Raymond's avatar
Eric S. Raymond committed
775 776 777
    (define-key m "N" 'vc-annotate-next-revision)
    (define-key m "P" 'vc-annotate-prev-revision)
    (define-key m "W" 'vc-annotate-working-revision)
778
    (define-key m "V" 'vc-annotate-toggle-annotation-visibility)
779 780
    m)
  "Local keymap used for VC-Annotate mode.")
781

Eric S. Raymond's avatar
Eric S. Raymond committed
782 783
;; Header-insertion hair

784
(defcustom vc-static-header-alist
785
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
786
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
787 788
  "*Associate static header string templates with file types.
A \%s in the template is replaced with the first string associated with
789
the file's version control type in `vc-header-alist'."
790 791 792 793
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
794

795
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
796
  '((nroff-mode ".\\\"" ""))
André Spiegel's avatar
André Spiegel committed
797
  "*Special comment delimiters for generating VC headers.
798 799
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
800 801 802 803 804 805
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
806

807
(defcustom vc-checkout-carefully (= (user-uid) 0)
808
  "*Non-nil means be extra-careful in checkout.
809
Verify that the file really is not locked
810 811 812
and that its contents match what the master file says."
  :type 'boolean
  :group 'vc)
813 814 815
(make-obsolete-variable 'vc-checkout-carefully
                        "the corresponding checks are always done now."
                        "21.1")
816

817

Eric S. Raymond's avatar
Eric S. Raymond committed
818 819
;; Variables the user doesn't need to know about.
(defvar vc-log-operation nil)
820
(defvar vc-log-after-operation-hook nil)
821

Richard M. Stallman's avatar
Richard M. Stallman committed
822 823 824
;; 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).
825
(defvar vc-parent-buffer nil)
826
(put 'vc-parent-buffer 'permanent-local t)
827
(defvar vc-parent-buffer-name nil)
828
(put 'vc-parent-buffer-name 'permanent-local t)
Eric S. Raymond's avatar
Eric S. Raymond committed
829

830 831 832 833 834
(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.")

835
(defvar vc-log-fileset)
Eric S. Raymond's avatar
Eric S. Raymond committed
836
(defvar vc-log-revision)
837

838
(defvar vc-dired-mode nil)
839 840
(make-variable-buffer-local 'vc-dired-mode)

Eric S. Raymond's avatar
Eric S. Raymond committed
841 842
;; File property caching

843
(defun vc-clear-context ()
844
  "Clear all cached file properties."
845
  (interactive)
846
  (fillarray vc-file-prop-obarray 0))
847

848 849
(defmacro with-vc-properties (files form settings)
  "Execute FORM, then maybe set per-file properties for FILES.
André Spiegel's avatar
André Spiegel committed
850 851 852
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."
853
  (declare (debug t))
854
  `(let ((vc-touched-properties (list t)))
855
     ,form
856
     (dolist (file ,files)
857 858 859 860 861
       (dolist (setting ,settings)
         (let ((property (car setting)))
           (unless (memq property vc-touched-properties)
             (put (intern file vc-file-prop-obarray)
                  property (cdr setting))))))))
862

863
;; Two macros for elisp programming
864

865 866
;;;###autoload
(defmacro with-vc-file (file comment &rest body)
André Spiegel's avatar
André Spiegel committed
867
  "Check out a writable copy of FILE if necessary, then execute BODY.
868 869
Check in FILE with COMMENT (a string) after BODY has been executed.
FILE is passed through `expand-file-name'; BODY executed within
870
`save-excursion'.  If FILE is not under version control, or you are
871
using a locking version-control system and the file is locked by
872
somebody else, signal error."
873
  (declare (debug t) (indent 2))
874 875 876
  (let ((filevar (make-symbol "file")))
    `(let ((,filevar (expand-file-name ,file)))
       (or (vc-backend ,filevar)
877
           (error "File not under version control: `%s'" file))
878 879
       (unless (vc-editable-p ,filevar)
         (let ((state (vc-state ,filevar)))
880
           (if (stringp state)
881
               (error "`%s' is locking `%s'" state ,filevar)
882 883 884
             (vc-checkout ,filevar t))))
       (save-excursion
         ,@body)
885
       (vc-checkin (list ,filevar) nil ,comment))))
886

887 888
;;;###autoload
(defmacro edit-vc-file (file comment &rest body)
889 890
  "Edit FILE under version control, executing body.
Checkin with COMMENT after executing BODY.