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 13 14

;; 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
15
;; the Free Software Foundation; either version 3, or (at your option)
Eric S. Raymond's avatar
Eric S. Raymond committed
16 17 18 19 20 21 22 23
;; 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
24
;; along with GNU Emacs; see the file COPYING.  If not, write to the
Lute Kamstra's avatar
Lute Kamstra committed
25 26
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
Eric S. Raymond's avatar
Eric S. Raymond committed
27

28 29 30
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
31
;; <esr@thyrsus.com> in 1992.  Over the years, many other people have
32
;; contributed substantial amounts of work to VC.  These include:
33
;;
34 35 36 37
;;   Per Cederqvist <ceder@lysator.liu.se>
;;   Paul Eggert <eggert@twinsun.com>
;;   Sebastian Kremer <sk@thp.uni-koeln.de>
;;   Martin Lorentzson <martinl@gnu.org>
Dave Love's avatar
Dave Love committed
38
;;   Dave Love <fx@gnu.org>
39
;;   Stefan Monnier <monnier@cs.yale.edu>
40 41
;;   Thien-Thi Nguyen <ttn@gnu.org>
;;   Dan Nicolaescu <dann@ics.uci.edu>
André Spiegel's avatar
André Spiegel committed
42
;;   J.D. Smith <jdsmith@alum.mit.edu>
43 44
;;   Andre Spiegel <spiegel@gnu.org>
;;   Richard Stallman <rms@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
;;
;;   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
151 152
;;   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.
153
;;
154
;; - state-heuristic (file)
155 156 157 158 159 160
;;
;;   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'.
;;
161
;; - dir-state (dir)
162
;;
163
;;   If provided, this function is used to find the version control
164
;;   state of as many files as possible in DIR, and all subdirectories
165 166
;;   of DIR, in a fast way; it is used to avoid expensive indivitual
;;   vc-state calls.  The function should not return anything, but
167 168 169 170
;;   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.)
171
;;
172
;; - dir-status (dir update-function)
173
;;
174 175 176 177 178 179
;;   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
180
;;   doing: (funcall UPDATE-FUNCTION RESULT nil).
181
;;   If the backend uses a process filter, hence it produces partial results,
182
;;   they can be passed back by doing:
183 184
;;      (funcall UPDATE-FUNCTION RESULT t)
;;   and then do a (funcall UPDATE-FUNCTION RESULT nil)
185
;;   when all the results have been computed.
186
;;   To provide more backend specific functionality for `vc-dir'
187
;;   the following functions might be needed: `status-extra-headers',
188
;;   `status-printer', `extra-status-menu' and `dir-status-files'.
189 190
;;   This function is used by `vc-dir', a replacement for
;;   `vc-dired'.  vc-dir is still under development, and is NOT
191 192
;;   feature complete.  As such, the requirements for this function
;;   might change.  This is a replacement for `dir-state'.
193
;;
194 195 196 197 198 199 200 201
;; - 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.
;;
202
;; - status-extra-headers (dir)
203
;;
204
;;   Return a string that will be added to the *vc-dir* buffer header.
205
;;
206 207
;; - status-printer (fileinfo)
;;
208
;;   Pretty print the `vc-dir-fileinfo' FILEINFO.
209
;;   If a backend needs to show more information than the default FILE
210 211 212
;;   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.
213
;;
214 215
;; - status-fileinfo-extra (file)
;;
216
;;   Compute `vc-dir-fileinfo->extra' for FILE.
217
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
218
;; * working-revision (file)
219
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
220
;;   Return the working revision of FILE.  This is the revision fetched
221
;;   by the last checkout or upate, not necessarily the same thing as the
222
;;   head or tip revision.  Should return "0" for a file added but not yet
223
;;   committed.
224 225 226
;;
;; - latest-on-branch-p (file)
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
227 228
;;   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).
229
;;   The default implementation always returns t, which means that
Eric S. Raymond's avatar
Eric S. Raymond committed
230
;;   working with non-current revisions is not supported by default.
231
;;
232
;; * checkout-model (files)
233
;;
234
;;   Indicate whether FILES need to be "checked out" before they can be
235 236
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
237
;; - workfile-unchanged-p (file)
238
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
239 240 241 242 243 244 245
;;   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
246
;;   `vc-disable-async-diff'.)
247
;;
248
;; - mode-line-string (file)
249
;;
250
;;   If provided, this function should return the VC-specific mode
251
;;   line string for FILE.  The returned string should have a
252 253 254 255
;;   `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.
256
;;
257
;; - prettify-state-info (file)
258 259
;;
;;   Translate the `vc-state' property of FILE into a string that can be
260
;;   used in a human-readable buffer.  The default implementation deals well
261 262 263 264
;;   with all states that `vc-state' can return.
;;
;; STATE-CHANGING FUNCTIONS
;;
265
;; * create-repo (backend)
266
;;
267 268
;;   Create an empty repository in the current directory and initialize
;;   it so VC mode can add files to it.  For file-oriented systems, this
269 270 271
;;   need do no more than create a subdirectory with the right name.
;;
;; * register (files &optional rev comment)
272
;;
273 274 275
;;   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.
276
;;   The implementation should pass the value of vc-register-switches
277
;;   to the backend command.  (Note: in older versions of VC, this
278
;;   command took a single file argument and not a list.)
279
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
280
;; - init-revision (file)
281
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
282
;;   The initial revision to use when registering FILE if one is not
283
;;   specified by the user.  If not provided, the variable
Eric S. Raymond's avatar
Eric S. Raymond committed
284
;;   vc-default-init-revision is used instead.
285
;;
286
;; - responsible-p (file)
287 288 289 290 291 292 293
;;
;;   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.
;;
294
;; - could-register (file)
295 296 297 298
;;
;;   Return non-nil if FILE could be registered under this backend.  The
;;   default implementation always returns t.
;;
299
;; - receive-file (file rev)
300 301 302 303 304 305 306 307 308 309 310 311
;;
;;   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.
;;
312
;; * checkin (files rev comment)
313
;;
314 315 316 317
;;   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
318
;;   the backend command.  (Note: in older versions of VC, this
319
;;   command took a single file argument and not a list.)
320
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
321
;; * find-revision (file rev buffer)
322 323 324 325 326 327
;;
;;   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
328
;; * checkout (file &optional editable rev)
329 330 331 332
;;
;;   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
333
;;   is the revision to check out (default is the working revision).
334 335 336
;;   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
337
;;   to the backend command.
338
;;
339
;; * revert (file &optional contents-done)
340
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
341
;;   Revert FILE back to the working revision.  If optional
342 343 344
;;   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.
345
;;
346
;; - rollback (files)
347
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
348 349
;;   Remove the tip revision of each of FILES from the repository.  If
;;   this function is not provided, trying to cancel a revision is
350 351 352 353
;;   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.)
354
;;
355
;; - merge (file rev1 rev2)
356 357 358
;;
;;   Merge the changes between REV1 and REV2 into the current working file.
;;
359
;; - merge-news (file)
360 361 362
;;
;;   Merge recent changes from the current branch into FILE.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
363
;; - steal-lock (file &optional revision)
364
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
365
;;   Steal any lock on the working revision of FILE, or on REVISION if
366 367 368
;;   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.
369
;;
370 371
;; - modify-change-comment (files rev comment)
;;
372
;;   Modify the change comments associated with the files at the
373 374
;;   given revision.  This is optional, many backends do not support it.
;;
375 376 377 378 379
;; - mark-resolved (files)
;;
;;   Mark conflicts as resolved.  Some VC systems need to run a
;;   command to mark conflicts as resolved.
;;
380 381
;; HISTORY FUNCTIONS
;;
382
;; * print-log (files &optional buffer)
383
;;
384 385 386
;;   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.)
387
;;
388 389 390 391 392 393
;; - 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
394
;; - show-log-entry (revision)
395
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
396
;;   If provided, search the log entry for REVISION in the current buffer,
397 398 399
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
400
;; - wash-log (file)
401
;;
402
;;   Remove all non-comment information from the output of print-log.
403
;;
404
;; - comment-history (file)
405
;;
406
;;   Return a string containing all log entries that were made for FILE.
407 408 409 410 411
;;   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.
;;
412
;; - update-changelog (files)
413 414 415 416 417 418
;;
;;   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.
;;
419
;; * diff (files &optional rev1 rev2 buffer)
420
;;
421 422
;;   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
423 424 425 426 427 428 429
;;   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).
430
;;
431
;; - revision-completion-table (files)
432
;;
433
;;   Return a completion table for existing revisions of FILES.
434 435
;;   The default is to not use any completion table.
;;
436
;; - annotate-command (file buf &optional rev)
437
;;
438
;;   If this function is provided, it should produce an annotated display
Eric S. Raymond's avatar
Eric S. Raymond committed
439
;;   of FILE in BUF, relative to revision REV.  Annotation means each line
440 441 442
;;   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.
443
;;
444
;; - annotate-time ()
445 446
;;
;;   Only required if `annotate-command' is defined for the backend.
447 448 449 450
;;   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
451
;;   to this format.  Return nil if no more lines of annotation appear
452 453 454
;;   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
455 456
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
457 458 459 460 461
;;
;; - 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
462
;;   (vc-annotate-convert-time (current-time)) -- i.e. the current
463 464
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
465
;;
466 467 468 469 470 471 472
;; - 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.
;;
473 474
;; SNAPSHOT SYSTEM
;;
475
;; - create-snapshot (dir name branchp)
476 477 478 479 480 481 482 483 484 485 486
;;
;;   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
487
;;   Give name NAME to the working revision of FILE, assuming it is
488 489
;;   up-to-date.  Only used by the default version of `create-snapshot'.
;;
490
;; - retrieve-snapshot (dir name update)
491 492 493 494 495 496
;;
;;   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
497
;;   function to retrieve the corresponding revisions.
498 499 500
;;
;; MISCELLANEOUS
;;
501 502 503 504 505 506
;; - 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.
;;
507
;; - make-version-backups-p (file)
508
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
509
;;   Return non-nil if unmodified repository revisions of FILE should be
510 511 512 513
;;   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.
;;
514 515 516 517
;; - 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
518
;;   is nil, it means that the repository is local.
519 520 521
;;   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
522
;; - previous-revision (file rev)
523
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
524 525
;;   Return the revision number that precedes REV for FILE, or nil if no such
;;   revision exists.
526
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
527
;; - next-revision (file rev)
528
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
529 530
;;   Return the revision number that follows REV for FILE, or nil if no such
;;   revision exists.
531
;;
532
;; - check-headers ()
533 534 535
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
536
;; - clear-headers ()
537 538 539 540 541 542 543 544
;;
;;   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.
;;
545 546 547 548 549 550
;; - 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.
;;
551
;; - rename-file (old new)
552 553
;;
;;   Rename file OLD to NEW, both in the working area and in the
554 555
;;   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
556
;;
557 558
;; - find-file-hook ()
;;
559
;;   Operation called in current buffer when opening a file.  This can
560
;;   be used by the backend to setup some local variables it might need.
561
;;
562 563 564 565
;; - 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.
566 567 568 569 570 571 572 573 574
;;
;; - 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.
575 576 577
;;
;; - extra-status-menu ()
;;
578 579 580 581 582 583
;;   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.
584

585 586 587 588 589
;;; 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
590 591 592 593
;; - deal with push/pull operations.
;;
;; - "snapshots" should be renamed to "branches", and thoroughly reworked.
;;
594 595 596
;; - 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
597 598 599 600
;;   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, ...
601
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
602 603 604 605
;; - 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
606 607 608 609
;; - 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.
;;
610
;; - vc-diff should be able to show the diff for all files in a
611 612
;;   changeset, especially for VC systems that have per repository
;;   version numbers.  log-view should take advantage of this.
613
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
614 615
;; - 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.
616
;;
617 618
;; - 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
619
;;
620 621 622 623 624 625 626 627 628
;; - 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...
629
;;
630
;; - most vc-dir backends need more work.  They might need to
631 632 633
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
634
;; - add function that calls vc-dir to `find-directory-functions'.
635
;;
636 637
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
;;   files. Now that unregistered and ignored files are shown in
638
;;   vc-dired/vc-dir, it is possible that these commands are called
639 640
;;   for unregistered/ignored files.
;;
641 642 643
;; - do not default to RCS anymore when the current directory is not
;;   controlled by any VCS and the user does C-x v v
;;
644 645
;; - vc-create-snapshot and vc-retrieve-snapshot should update the
;;   buffers that might be visiting the affected files.
646
;;
647 648 649
;; - 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
650 651 652 653
;;   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
654 655 656 657 658 659 660
;; - 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.
;;
661 662 663
;; - backends that care about vc-stay-local should try to take it into
;;   account for vc-dir.  Is this likely to be useful???
;;
664 665 666
;; - 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
667

668
;;; Code:
669

Eric S. Raymond's avatar
Eric S. Raymond committed
670
(require 'vc-hooks)
671
(require 'vc-dispatcher)
672
(require 'tool-bar)
673
(require 'ewoc)
674

675
(eval-when-compile
Andreas Schwab's avatar
Andreas Schwab committed
676
  (require 'dired)
Eric S. Raymond's avatar
Eric S. Raymond committed
677
  (require 'dired-aux)
678
  (require 'cl))
679

680 681 682 683
(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
684 685 686

;; General customization

687 688 689 690 691
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-suppress-confirm nil
692
  "If non-nil, treat user as expert; suppress yes-no prompts on some things."
693 694 695 696
  :type 'boolean
  :group 'vc)

(defcustom vc-initial-comment nil
697
  "If non-nil, prompt for initial comment when a file is registered."
698 699 700
  :type 'boolean
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
701 702
(defcustom vc-default-init-revision "1.1"
  "A string used as the default revision number when a new file is registered.
703 704
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
705
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
706 707
  :group 'vc
  :version "20.3")
708

709
(defcustom vc-checkin-switches nil
710
  "A string or list of strings specifying extra switches for checkin.
711 712 713 714 715 716 717 718 719
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
720
  "A string or list of strings specifying extra switches for checkout.
721 722 723 724 725 726 727 728 729
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
730
  "A string or list of strings; extra switches for registering a file.
731 732 733 734 735 736 737 738
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)

739
(defcustom vc-diff-switches nil
740
  "A string or list of strings specifying switches for diff under VC.
741 742 743 744 745
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."
746 747 748 749 750 751 752 753
  :type '(choice (const :tag "None" nil)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List"
			 :value ("")
			 string))
  :group 'vc
  :version "21.1")

754 755 756 757 758 759 760
(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)

761
(defcustom vc-allow-async-revert nil
762
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
763 764 765 766 767
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
768
  :version "22.1")
769

André Spiegel's avatar
André Spiegel committed
770 771
;;;###autoload
(defcustom vc-checkout-hook nil
772
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
773 774 775 776 777
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

778
(defcustom vc-annotate-display-mode 'fullscale
André Spiegel's avatar
André Spiegel committed
779
  "Which mode to color the output of \\[vc-annotate] with by default."
780
  :type '(choice (const :tag "By Color Map Range" nil)
781 782 783 784 785 786
		 (const :tag "Scale to Oldest" scale)
		 (const :tag "Scale Oldest->Newest" fullscale)
		 (number :tag "Specify Fractional Number of Days"
			 :value "20.5"))
  :group 'vc)

787 788
;;;###autoload
(defcustom vc-checkin-hook nil
789
  "Normal hook (list of functions) run after commit or file checkin.
790
See also `log-edit-done-hook'."
791
  :type 'hook
792
  :options '(log-edit-comment-to-change-log)
793 794 795 796
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
797
  "Normal hook (list of functions) run before a commit or a file checkin.
798 799 800 801 802
See `run-hooks'."
  :type 'hook
  :group 'vc)

;; Annotate customization
803
(defcustom vc-annotate-color-map
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 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852
  (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")))
853
  "Association list of age versus color, for \\[vc-annotate].
854 855 856 857
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)."
858
  :type 'alist
859 860
  :group 'vc)

861
(defcustom vc-annotate-very-old-color "#3F3FFF"
862
  "Color for lines older than the current color range in \\[vc-annotate]]."
863 864 865 866
  :type 'string
  :group 'vc)

(defcustom vc-annotate-background "black"
867
  "Background color for \\[vc-annotate].
868
Default color is used if nil."
869
  :type '(choice (const :tag "Default background" nil) (color))
870 871 872
  :group 'vc)

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

878 879
(defvar vc-annotate-mode-map
  (let ((m (make-sparse-keymap)))
880 881
    (define-key m "A" 'vc-annotate-revision-previous-to-line)
    (define-key m "D" 'vc-annotate-show-diff-revision-at-line)
882
    (define-key m "f" 'vc-annotate-find-revision-at-line)
883 884
    (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
885 886 887
    (define-key m "N" 'vc-annotate-next-revision)
    (define-key m "P" 'vc-annotate-prev-revision)
    (define-key m "W" 'vc-annotate-working-revision)
888
    (define-key m "V" 'vc-annotate-toggle-annotation-visibility)
889 890
    m)
  "Local keymap used for VC-Annotate mode.")
891

Eric S. Raymond's avatar
Eric S. Raymond committed
892 893
;; Header-insertion hair

894
(defcustom vc-static-header-alist
895
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
896
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
897 898
  "*Associate static header string templates with file types.
A \%s in the template is replaced with the first string associated with
899
the file's version control type in `vc-header-alist'."
900 901 902 903
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
904

905
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
906
  '((nroff-mode ".\\\"" ""))