vc.el 158 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 163 164 165 166
;;
;;   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.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
167
;; * working-revision (file)
168
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
169
;;   Return the working revision of FILE.  This is the revision fetched
170
;;   by the last checkout or upate, not necessarily the same thing as the
171
;;   head or tip revision.  Should return "0" for a file added but not yet
172
;;   committed.
173 174 175
;;
;; - latest-on-branch-p (file)
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
176 177
;;   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).
178
;;   The default implementation always returns t, which means that
Eric S. Raymond's avatar
Eric S. Raymond committed
179
;;   working with non-current revisions is not supported by default.
180
;;
181
;; * checkout-model (file)
182 183 184 185
;;
;;   Indicate whether FILE needs to be "checked out" before it can be
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
186
;; - workfile-unchanged-p (file)
187
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
188 189 190 191 192 193 194
;;   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
195
;;   `vc-disable-async-diff'.)
196
;;
197
;; - mode-line-string (file)
198
;;
199
;;   If provided, this function should return the VC-specific mode
200
;;   line string for FILE.  The returned string should have a
201 202 203 204
;;   `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.
205
;;
206
;; - dired-state-info (file)
207 208 209 210 211 212 213
;;
;;   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
;;
214
;; * create-repo (backend)
215
;;
216 217
;;   Create an empty repository in the current directory and initialize
;;   it so VC mode can add files to it.  For file-oriented systems, this
218 219 220
;;   need do no more than create a subdirectory with the right name.
;;
;; * register (files &optional rev comment)
221
;;
222 223 224
;;   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.
225
;;   The implementation should pass the value of vc-register-switches
226
;;   to the backend command.  (Note: in older versions of VC, this
227
;;   command took a single file argument and not a list.)
228
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
229
;; - init-revision (file)
230
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
231
;;   The initial revision to use when registering FILE if one is not
232
;;   specified by the user.  If not provided, the variable
Eric S. Raymond's avatar
Eric S. Raymond committed
233
;;   vc-default-init-revision is used instead.
234
;;
235
;; - responsible-p (file)
236 237 238 239 240 241 242
;;
;;   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.
;;
243
;; - could-register (file)
244 245 246 247
;;
;;   Return non-nil if FILE could be registered under this backend.  The
;;   default implementation always returns t.
;;
248
;; - receive-file (file rev)
249 250 251 252 253 254 255 256 257 258 259 260
;;
;;   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.
;;
261
;; * checkin (files rev comment)
262
;;
263 264 265 266
;;   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
267
;;   the backend command.  (Note: in older versions of VC, this
268
;;   command took a single file argument and not a list.)
269
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
270
;; * find-revision (file rev buffer)
271 272 273 274 275 276
;;
;;   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
277
;; * checkout (file &optional editable rev)
278 279 280 281
;;
;;   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
282
;;   is the revision to check out (default is the working revision).
283 284 285
;;   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
286
;;   to the backend command.
287
;;
288
;; * revert (file &optional contents-done)
289
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
290
;;   Revert FILE back to the working revision.  If optional
291 292 293
;;   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.
294
;;
295
;; - rollback (files)
296
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
297 298
;;   Remove the tip revision of each of FILES from the repository.  If
;;   this function is not provided, trying to cancel a revision is
299 300 301 302
;;   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.)
303
;;
304
;; - merge (file rev1 rev2)
305 306 307
;;
;;   Merge the changes between REV1 and REV2 into the current working file.
;;
308
;; - merge-news (file)
309 310 311
;;
;;   Merge recent changes from the current branch into FILE.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
312
;; - steal-lock (file &optional revision)
313
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
314
;;   Steal any lock on the working revision of FILE, or on REVISION if
315 316 317
;;   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.
318 319 320
;;
;; HISTORY FUNCTIONS
;;
321
;; * print-log (files &optional buffer)
322
;;
323 324 325
;;   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.)
326
;;
327 328 329 330 331 332
;; - 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
333
;; - show-log-entry (revision)
334
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
335
;;   If provided, search the log entry for REVISION in the current buffer,
336 337 338
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
339
;; - wash-log (file)
340
;;
341
;;   Remove all non-comment information from the output of print-log.
342
;;
343
;; - logentry-check ()
344 345 346 347 348 349
;;
;;   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.
;;
350
;; - comment-history (file)
351
;;
352
;;   Return a string containing all log entries that were made for FILE.
353 354 355 356 357
;;   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.
;;
358
;; - update-changelog (files)
359 360 361 362 363 364
;;
;;   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.
;;
365
;; * diff (files &optional rev1 rev2 buffer)
366
;;
367 368
;;   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
369 370 371 372 373 374 375
;;   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).
376
;;
377
;; - revision-completion-table (files)
378
;;
379
;;   Return a completion table for existing revisions of FILES.
380 381
;;   The default is to not use any completion table.
;;
382
;; - annotate-command (file buf &optional rev)
383
;;
384
;;   If this function is provided, it should produce an annotated display
Eric S. Raymond's avatar
Eric S. Raymond committed
385
;;   of FILE in BUF, relative to revision REV.  Annotation means each line
386 387 388
;;   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.
389
;;
390
;; - annotate-time ()
391 392
;;
;;   Only required if `annotate-command' is defined for the backend.
393 394 395 396
;;   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
397
;;   to this format.  Return nil if no more lines of annotation appear
398 399 400
;;   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
401 402
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
403 404 405 406 407
;;
;; - 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
408
;;   (vc-annotate-convert-time (current-time)) -- i.e. the current
409 410
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
411
;;
412 413 414 415 416 417 418
;; - 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.
;;
419 420
;; SNAPSHOT SYSTEM
;;
421
;; - create-snapshot (dir name branchp)
422 423 424 425 426 427 428 429 430 431 432
;;
;;   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
433
;;   Give name NAME to the working revision of FILE, assuming it is
434 435
;;   up-to-date.  Only used by the default version of `create-snapshot'.
;;
436
;; - retrieve-snapshot (dir name update)
437 438 439 440 441 442
;;
;;   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
443
;;   function to retrieve the corresponding revisions.
444 445 446
;;
;; MISCELLANEOUS
;;
447
;; - make-version-backups-p (file)
448
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
449
;;   Return non-nil if unmodified repository revisions of FILE should be
450 451 452 453
;;   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.
;;
454 455 456 457
;; - 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
458
;;   is nil, it means that the repository is local.
459 460 461
;;   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
462
;; - previous-revision (file rev)
463
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
464 465
;;   Return the revision number that precedes REV for FILE, or nil if no such
;;   revision exists.
466
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
467
;; - next-revision (file rev)
468
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
469 470
;;   Return the revision number that follows REV for FILE, or nil if no such
;;   revision exists.
471
;;
472
;; - check-headers ()
473 474 475
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
476
;; - clear-headers ()
477 478 479 480 481 482 483 484
;;
;;   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.
;;
485 486 487 488 489 490
;; - 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.
;;
491
;; - rename-file (old new)
492 493
;;
;;   Rename file OLD to NEW, both in the working area and in the
494 495
;;   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
496
;;
497 498
;; - find-file-hook ()
;;
499
;;   Operation called in current buffer when opening a file.  This can
500
;;   be used by the backend to setup some local variables it might need.
501
;;
502 503 504 505
;; - 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.
506 507 508 509 510 511 512 513 514
;;
;; - 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.
515

516
;;; Code:
517

Eric S. Raymond's avatar
Eric S. Raymond committed
518
(require 'vc-hooks)
519
(require 'ring)
520
(eval-when-compile
521
  (require 'cl)
522 523 524
  (require 'compile)
  (require 'dired)      ; for dired-map-over-marks macro
  (require 'dired-aux))	; for dired-kill-{line,tree}
525 526 527 528 529

(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
530 531 532

;; General customization

533 534 535 536 537
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-suppress-confirm nil
538
  "If non-nil, treat user as expert; suppress yes-no prompts on some things."
539 540 541
  :type 'boolean
  :group 'vc)

542
(defcustom vc-delete-logbuf-window t
543
  "If non-nil, delete the *VC-log* buffer and window after each logical action.
544 545 546 547 548 549
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)

550
(defcustom vc-initial-comment nil
551
  "If non-nil, prompt for initial comment when a file is registered."
552 553 554
  :type 'boolean
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
555 556
(defcustom vc-default-init-revision "1.1"
  "A string used as the default revision number when a new file is registered.
557 558
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
559
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
560 561
  :group 'vc
  :version "20.3")
562

563
(defcustom vc-command-messages nil
564
  "If non-nil, display run messages from back-end commands."
565 566 567 568
  :type 'boolean
  :group 'vc)

(defcustom vc-checkin-switches nil
569
  "A string or list of strings specifying extra switches for checkin.
570 571 572 573 574 575 576 577 578
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
579
  "A string or list of strings specifying extra switches for checkout.
580 581 582 583 584 585 586 587 588
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
589
  "A string or list of strings; extra switches for registering a file.
590 591 592 593 594 595 596 597
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)

598
(defcustom vc-dired-listing-switches "-al"
599
  "Switches passed to `ls' for vc-dired.  MUST contain the `l' option."
600 601
  :type 'string
  :group 'vc
602
  :version "21.1")
603

604
(defcustom vc-dired-recurse t
605
  "If non-nil, show directory trees recursively in VC Dired."
606 607 608 609 610
  :type 'boolean
  :group 'vc
  :version "20.3")

(defcustom vc-dired-terse-display t
611
  "If non-nil, show only locked or locally modified files in VC Dired."
612 613 614 615
  :type 'boolean
  :group 'vc
  :version "20.3")

616
(defcustom vc-directory-exclusion-list '("SCCS" "RCS" "CVS" "MCVS" ".svn"
617
					 ".git" ".hg" ".bzr" "{arch}")
618
  "List of directory names to be ignored when walking directory trees."
619 620
  :type '(repeat string)
  :group 'vc)
621

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

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

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

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

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

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

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

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

692
;; Annotate customization
693
(defcustom vc-annotate-color-map
694 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
  (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")))
743
  "Association list of age versus color, for \\[vc-annotate].
744 745 746 747
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)."
748
  :type 'alist
749 750
  :group 'vc)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

862
;; Two macros for elisp programming
863

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

886 887
;;;###autoload
(defmacro edit-vc-file (file comment &rest body)
888 889
  "Edit FILE under version control, executing body.
Checkin with COMMENT after executing BODY.
890 891
This macro uses `with-vc-file', passing args to it.
However, before executing BODY, find FILE, and after BODY, save buffer."
892
  (declare (debug t) (indent 2))
893 894 895 896 897 898 899 900
  (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)))))

901 902
;; Common command execution logic to be used by backends

903
(defun vc-process-filter (p s)
904
  "An alternative output filter for async process P.
905 906
One difference with the default filter is that this inserts S after markers.
Another is that undo information is not kept."
907 908
  (with-current-buffer (process-buffer p)
    (save-excursion
909 910
      (let ((buffer-undo-list t)
            (inhibit-read-only t))
911 912 913 914 915
	(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
916
  "Prepare BUF for executing a VC command and make it current.
917 918 919 920 921 922 923 924 925 926
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)
927 928
    (let ((buffer-undo-list t)
          (inhibit-read-only t))
929 930
      (erase-buffer))))

931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957
(defvar vc-sentinel-movepoint)          ;Dynamically scoped.

(defun vc-process-sentinel (p s)
  (let ((previous (process-get p 'vc-previous-sentinel)))
    (if previous (funcall previous p s))
    (with-current-buffer (process-buffer p)
      (let (vc-sentinel-movepoint)
        ;; Normally, we want async code such as sentinels to not move point.
        (save-excursion
          (goto-char (process-mark p))
          (let ((cmds (process-get p 'vc-sentinel-commands)))
            (process-put p 'vc-postprocess nil)
            (dolist (cmd cmds)
              ;; Each sentinel may move point and the next one should be run
              ;; at that new point.  We could get the same result by having
              ;; each sentinel read&set process-mark, but since `cmd' needs
              ;; to work both for async and sync processes, this would be
              ;; difficult to achieve.
              (vc-exec-after cmd))))
        ;; But sometimes the sentinels really want to move point.
        (if vc-sentinel-movepoint
            (let ((win (get-buffer-window (current-buffer) 0)))
              (if (not win)
                  (goto-char vc-sentinel-movepoint)
                (with-selected-window win
                  (goto-char vc-sentinel-movepoint)))))))))

958 959 960 961 962 963 964
(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))))