vc.el 149 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,
4 5
;;   2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008
;;   Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
6

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

;; This file is part of GNU Emacs.

13
;; GNU Emacs is free software: you can redistribute it and/or modify
Eric S. Raymond's avatar
Eric S. Raymond committed
14
;; it under the terms of the GNU General Public License as published by
15 16
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
Eric S. Raymond's avatar
Eric S. Raymond committed
17 18 19 20 21 22 23

;; 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
24
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Eric S. Raymond's avatar
Eric S. Raymond committed
25

26 27 28
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
29
;; <esr@thyrsus.com> in 1992.  Over the years, many other people have
30
;; contributed substantial amounts of work to VC.  These include:
31
;;
32 33 34 35
;;   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
36
;;   Dave Love <fx@gnu.org>
37
;;   Stefan Monnier <monnier@cs.yale.edu>
38 39
;;   Thien-Thi Nguyen <ttn@gnu.org>
;;   Dan Nicolaescu <dann@ics.uci.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>
43 44 45 46 47
;;
;; 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.
;;
48 49
;; 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
50 51
;; now take a list of files.  These include: register, checkin, print-log,
;; rollback, and diff.
52

Eric S. Raymond's avatar
Eric S. Raymond committed
53 54
;;; Commentary:

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

570 571 572 573 574
;;; Todo:

;; - vc-update/vc-merge should deal with VC systems that don't
;;   update/merge on a file basis, but on a whole repository basis.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
575 576 577 578
;; - deal with push/pull operations.
;;
;; - "snapshots" should be renamed to "branches", and thoroughly reworked.
;;
579 580 581
;; - when a file is in `conflict' state, turn on smerge-mode.
;;
;; - figure out what to do with conflicts that are not caused by the
Eric S. Raymond's avatar
Eric S. Raymond committed
582 583 584 585
;;   file contents, but by metadata or other causes.  Example: File A
;;   gets renamed to B in one branch and to C in another and you merge
;;   the two branches.  Or you locally add file FOO and then pull a
;;   change that also adds a new file FOO, ...
586
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
587 588 589 590
;; - add a generic mechanism for remembering the current branch names,
;;   display the branch name in the mode-line. Replace
;;   vc-cvs-sticky-tag with that.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
591 592 593 594
;; - C-x v b does switch to a different backend, but the mode line is not 
;;   adapted accordingly.  Also, it considers RCS and CVS to be the same, 
;;   which is pretty confusing.
;;
595
;; - vc-diff should be able to show the diff for all files in a
596 597
;;   changeset, especially for VC systems that have per repository
;;   version numbers.  log-view should take advantage of this.
598
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
599 600
;; - make it easier to write logs.  Maybe C-x 4 a should add to the log
;;   buffer, if one is present, instead of adding to the ChangeLog.
601
;;
602 603
;; - add a mechanism for editing the underlying VCS's list of files
;;   to be ignored, when that's possible.
Dan Nicolaescu's avatar
Dan Nicolaescu committed
604
;;
605 606 607 608 609 610 611 612 613
;; - When vc-next-action calls vc-checkin it could pre-fill the
;;   *VC-log* buffer with some obvious items: the list of files that
;;   were added, the list of files that were removed.  If the diff is
;;   available, maybe it could even call something like
;;   `diff-add-change-log-entries-other-window' to create a detailed
;;   skeleton for the log...
;;
;; - a way to do repository wide log (instead of just per
;;   file/fileset) is needed.  Doing it per directory might be enough...
614
;;
615
;; - most vc-dir backends need more work.  They might need to
616 617 618
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
619
;; - add function that calls vc-dir to `find-directory-functions'.
620
;;
621 622
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
;;   files. Now that unregistered and ignored files are shown in
623
;;   vc-dired/vc-dir, it is possible that these commands are called
624 625
;;   for unregistered/ignored files.
;;
626 627 628
;; - do not default to RCS anymore when the current directory is not
;;   controlled by any VCS and the user does C-x v v
;;
629 630
;; - vc-create-snapshot and vc-retrieve-snapshot should update the
;;   buffers that might be visiting the affected files.
631
;;
632 633 634
;; - Using multiple backends needs work.  Given a CVS directory with some
;;   files checked into git (but not all), using C-x v l to get a log file
;;   from a file only present in git, and then typing RET on some log entry,
Eric S. Raymond's avatar
Eric S. Raymond committed
635 636 637 638
;;   vc will bombs out because it wants to see the file being in CVS.
;;   Those logs should likely use a local variable to hardware the VC they
;;   are supposed to work with.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
639 640 641 642 643 644 645
;; - Another important thing: merge all the status-like backend operations.
;;   We should remove dir-status, state, dir-state, and dir-status-files, and
;;   replace them with just `status' which takes a fileset and a continuation
;;   (like dir-status) and returns a buffer in which the process(es) are run
;;   (or nil if it worked synchronously).  Hopefully we can define the old
;;   4 operations in term of this one.
;;
646 647 648
;; - backends that care about vc-stay-local should try to take it into
;;   account for vc-dir.  Is this likely to be useful???
;;
649 650 651
;; - vc-dir listing needs a footer generated when it's done to make it obvious
;; that it has finished.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
652

653
;;; Code:
654

Eric S. Raymond's avatar
Eric S. Raymond committed
655
(require 'vc-hooks)
656
(require 'vc-dispatcher)
657
(require 'tool-bar)
658
(require 'ewoc)
659

660
(eval-when-compile
Andreas Schwab's avatar
Andreas Schwab committed
661
  (require 'dired)
Eric S. Raymond's avatar
Eric S. Raymond committed
662
  (require 'dired-aux)
663
  (require 'cl))
664

665 666 667 668
(unless (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
669 670 671

;; General customization

672 673 674 675 676
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-initial-comment nil
677
  "If non-nil, prompt for initial comment when a file is registered."
678 679 680
  :type 'boolean
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
681 682
(defcustom vc-default-init-revision "1.1"
  "A string used as the default revision number when a new file is registered.
683 684
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
685
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
686 687
  :group 'vc
  :version "20.3")
688

689
(defcustom vc-checkin-switches nil
690
  "A string or list of strings specifying extra switches for checkin.
691 692 693 694 695 696 697 698 699
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
700
  "A string or list of strings specifying extra switches for checkout.
701 702 703 704 705 706 707 708 709
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
710
  "A string or list of strings; extra switches for registering a file.
711 712 713 714 715 716 717 718
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)

719
(defcustom vc-diff-switches nil
720
  "A string or list of strings specifying switches for diff under VC.
721 722 723 724 725
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."
726 727 728 729 730 731 732 733
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc
  :version "21.1")

734 735 736 737 738 739 740
(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)

741
(defcustom vc-allow-async-revert nil
742
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
743 744 745 746 747
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
748
  :version "22.1")
749

André Spiegel's avatar
André Spiegel committed
750 751
;;;###autoload
(defcustom vc-checkout-hook nil
752
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
753 754 755 756 757
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

758
(defcustom vc-annotate-display-mode 'fullscale
André Spiegel's avatar
André Spiegel committed
759
  "Which mode to color the output of \\[vc-annotate] with by default."
760
  :type '(choice (const :tag "By Color Map Range" nil)
761 762 763 764 765 766
		 (const :tag "Scale to Oldest" scale)
		 (const :tag "Scale Oldest->Newest" fullscale)
		 (number :tag "Specify Fractional Number of Days"
			 :value "20.5"))
  :group 'vc)

767 768
;;;###autoload
(defcustom vc-checkin-hook nil
769
  "Normal hook (list of functions) run after commit or file checkin.
770
See also `log-edit-done-hook'."
771
  :type 'hook
772
  :options '(log-edit-comment-to-change-log)
773 774 775 776
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
777
  "Normal hook (list of functions) run before a commit or a file checkin.
778 779 780 781 782
See `run-hooks'."
  :type 'hook
  :group 'vc)

;; Annotate customization
783
(defcustom vc-annotate-color-map
784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832
  (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")))
833
  "Association list of age versus color, for \\[vc-annotate].
834 835 836 837
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)."
838
  :type 'alist
839 840
  :group 'vc)

841
(defcustom vc-annotate-very-old-color "#3F3FFF"
842
  "Color for lines older than the current color range in \\[vc-annotate]]."
843 844 845 846
  :type 'string
  :group 'vc)

(defcustom vc-annotate-background "black"
847
  "Background color for \\[vc-annotate].
848
Default color is used if nil."
849
  :type '(choice (const :tag "Default background" nil) (color))
850 851 852
  :group 'vc)

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

858 859
(defvar vc-annotate-mode-map
  (let ((m (make-sparse-keymap)))
860 861
    (define-key m "A" 'vc-annotate-revision-previous-to-line)
    (define-key m "D" 'vc-annotate-show-diff-revision-at-line)
862
    (define-key m "f" 'vc-annotate-find-revision-at-line)
863 864
    (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
865 866 867
    (define-key m "N" 'vc-annotate-next-revision)
    (define-key m "P" 'vc-annotate-prev-revision)
    (define-key m "W" 'vc-annotate-working-revision)
868
    (define-key m "V" 'vc-annotate-toggle-annotation-visibility)
869 870
    m)
  "Local keymap used for VC-Annotate mode.")
871

Eric S. Raymond's avatar
Eric S. Raymond committed
872 873
;; Header-insertion hair

874
(defcustom vc-static-header-alist
875
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
876
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
877 878
  "*Associate static header string templates with file types.
A \%s in the template is replaced with the first string associated with
879
the file's version control type in `vc-header-alist'."
880 881 882 883
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
884

885
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
886
  '((nroff-mode ".\\\"" ""))
André Spiegel's avatar
André Spiegel committed
887
  "*Special comment delimiters for generating VC headers.
888 889
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
890 891 892 893 894 895
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
896

897
(defcustom vc-checkout-carefully (= (user-uid) 0)
898
  "*Non-nil means be extra-careful in checkout.
899
Verify that the file really is not locked
900 901 902
and that its contents match what the master file says."
  :type 'boolean
  :group 'vc)