vc.el 117 KB
Newer Older
Stefan Monnier's avatar
Stefan Monnier committed
1
;;; vc.el --- drive a version-control system from within Emacs  -*- lexical-binding: t -*-
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3
;; Copyright (C) 1992-1998, 2000-2013 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
4

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

;; This file is part of GNU Emacs.

11
;; GNU Emacs is free software: you can redistribute it and/or modify
Eric S. Raymond's avatar
Eric S. Raymond committed
12
;; it under the terms of the GNU General Public License as published by
13 14
;; 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
15 16 17 18 19 20 21

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

24 25 26
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
27
;; <esr@thyrsus.com> in 1992.  Over the years, many other people have
28
;; contributed substantial amounts of work to VC.  These include:
29
;;
30 31 32 33
;;   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
34
;;   Dave Love <fx@gnu.org>
35
;;   Stefan Monnier <monnier@cs.yale.edu>
36 37
;;   Thien-Thi Nguyen <ttn@gnu.org>
;;   Dan Nicolaescu <dann@ics.uci.edu>
André Spiegel's avatar
André Spiegel committed
38
;;   J.D. Smith <jdsmith@alum.mit.edu>
39 40
;;   Andre Spiegel <spiegel@gnu.org>
;;   Richard Stallman <rms@gnu.org>
41 42 43 44 45
;;
;; 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.
;;
46 47
;; 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
48 49
;; now take a list of files.  These include: register, checkin, print-log,
;; rollback, and diff.
50

Eric S. Raymond's avatar
Eric S. Raymond committed
51 52
;;; Commentary:

53 54
;; This mode is fully documented in the Emacs user's manual.
;;
55
;; Supported version-control systems presently include CVS, RCS, GNU
56
;; Arch, Subversion, Bzr, Git, Mercurial, Monotone and SCCS
57
;; (or its free replacement, CSSC).
58
;;
59
;; If your site uses the ChangeLog convention supported by Emacs, the
60 61
;; 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')
62
;; from the commit buffer instead or to set `log-edit-setup-invert'.
63
;;
64 65 66 67 68 69 70 71 72 73 74 75
;; When using SCCS, RCS, CVS: be careful not to do repo surgery, or
;; operations like registrations and deletions and renames, outside VC
;; while VC is running. The support for these systems was designed
;; when disks were much slower, and the code maintains a lot of
;; internal state in order to reduce expensive operations to a
;; minimum. Thus, if you mess with the repo while VC's back is turned,
;; VC may get seriously confused.
;;
;; When using Subversion or a later system, anything you do outside VC
;; *through the VCS tools* should safely interlock with VC
;; operations. Under these VC does little state caching, because local
;; operations are assumed to be fast.  The dividing line is
Eric S. Raymond's avatar
Eric S. Raymond committed
76
;;
77 78 79 80 81 82 83 84 85 86 87 88 89 90
;; 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
91
;; `vc-sys-working-revision' should compute the working revision and
92 93 94
;; 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
95
;; value that the generic code might want to set (check for uses of
96 97 98 99 100
;; 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 (`-').
101

102 103 104 105
;; BACKEND PROPERTIES
;;
;; * revision-granularity
;;
106 107 108 109
;;   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
110

111 112
;; STATE-QUERYING FUNCTIONS
;;
113
;; * registered (file)
114
;;
115
;;   Return non-nil if FILE is registered in this backend.  Both this
116 117
;;   function as well as `state' should be careful to fail gracefully
;;   in the event that the backend executable is absent.  It is
118
;;   preferable that this function's *body* is autoloaded, that way only
119 120
;;   calling vc-registered does not cause the backend to be loaded
;;   (all the vc-FOO-registered functions are called to try to find
121
;;   the controlling backend for FILE).
122
;;
123
;; * state (file)
124 125 126 127 128
;;
;;   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
129
;;   file, put that into `state-heuristic' below.  Note that under most
130
;;   VCSes this won't be called at all, dir-status is used instead.
131
;;
132
;; - state-heuristic (file)
133 134 135 136 137 138
;;
;;   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'.
;;
139
;; - dir-status (dir update-function)
140
;;
141 142 143 144 145 146
;;   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
147
;;   doing: (funcall UPDATE-FUNCTION RESULT nil).
148
;;   If the backend uses a process filter, hence it produces partial results,
149
;;   they can be passed back by doing:
150 151
;;      (funcall UPDATE-FUNCTION RESULT t)
;;   and then do a (funcall UPDATE-FUNCTION RESULT nil)
152
;;   when all the results have been computed.
153
;;   To provide more backend specific functionality for `vc-dir'
154 155
;;   the following functions might be needed: `dir-extra-headers',
;;   `dir-printer', `extra-dir-menu' and `dir-status-files'.
156
;;
157 158 159 160 161 162 163 164
;; - 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.
;;
165
;; - dir-extra-headers (dir)
166
;;
167
;;   Return a string that will be added to the *vc-dir* buffer header.
168
;;
169
;; - dir-printer (fileinfo)
170
;;
171
;;   Pretty print the `vc-dir-fileinfo' FILEINFO.
172
;;   If a backend needs to show more information than the default FILE
173 174 175
;;   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.
176
;;
177 178
;; - status-fileinfo-extra (file)
;;
179
;;   Compute `vc-dir-fileinfo->extra' for FILE.
180
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
181
;; * working-revision (file)
182
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
183
;;   Return the working revision of FILE.  This is the revision fetched
Paul Eggert's avatar
Paul Eggert committed
184
;;   by the last checkout or update, not necessarily the same thing as the
185
;;   head or tip revision.  Should return "0" for a file added but not yet
186
;;   committed.
187 188 189
;;
;; - latest-on-branch-p (file)
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
190 191
;;   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).
192
;;   The default implementation always returns t, which means that
Eric S. Raymond's avatar
Eric S. Raymond committed
193
;;   working with non-current revisions is not supported by default.
194
;;
195
;; * checkout-model (files)
196
;;
197
;;   Indicate whether FILES need to be "checked out" before they can be
198 199
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
200
;; - workfile-unchanged-p (file)
201
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
202 203
;;   Return non-nil if FILE is unchanged from the working revision.
;;   This function should do a brief comparison of FILE's contents
204
;;   with those of the repository copy of the working revision.  If
Eric S. Raymond's avatar
Eric S. Raymond committed
205 206 207 208
;;   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
209
;;   `vc-disable-async-diff'.)
210
;;
211
;; - mode-line-string (file)
212
;;
213
;;   If provided, this function should return the VC-specific mode
214
;;   line string for FILE.  The returned string should have a
215 216 217 218
;;   `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.
219 220 221
;;
;; STATE-CHANGING FUNCTIONS
;;
222
;; * create-repo (backend)
223
;;
224 225
;;   Create an empty repository in the current directory and initialize
;;   it so VC mode can add files to it.  For file-oriented systems, this
226 227 228
;;   need do no more than create a subdirectory with the right name.
;;
;; * register (files &optional rev comment)
229
;;
230 231 232
;;   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.
233
;;   The implementation should pass the value of vc-register-switches
234
;;   to the backend command.  (Note: in older versions of VC, this
235
;;   command took a single file argument and not a list.)
236
;;   The REV argument is a historical leftover and is never used.
237
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
238
;; - init-revision (file)
239
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
240
;;   The initial revision to use when registering FILE if one is not
241
;;   specified by the user.  If not provided, the variable
Eric S. Raymond's avatar
Eric S. Raymond committed
242
;;   vc-default-init-revision is used instead.
243
;;
244
;; - responsible-p (file)
245 246 247 248 249 250 251
;;
;;   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.
;;
252
;; - could-register (file)
253 254 255 256
;;
;;   Return non-nil if FILE could be registered under this backend.  The
;;   default implementation always returns t.
;;
257
;; - receive-file (file rev)
258 259 260 261 262 263 264 265 266 267 268 269
;;
;;   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.
;;
270
;; * checkin (files rev comment)
271
;;
272 273 274 275
;;   Commit changes in FILES to this backend.  REV is a historical artifact
;;   and should be ignored.  COMMENT is used as a check-in comment.
;;   The implementation should pass the value of vc-checkin-switches to
;;   the backend command.
276
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
277
;; * find-revision (file rev buffer)
278 279 280 281 282 283
;;
;;   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
284
;; * checkout (file &optional editable rev)
285 286 287 288
;;
;;   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
289
;;   is the revision to check out (default is the working revision).
290 291 292
;;   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
293
;;   to the backend command.
294
;;
295
;; * revert (file &optional contents-done)
296
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
297
;;   Revert FILE back to the working revision.  If optional
298 299 300
;;   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.
301 302
;;   If FILE is in the `added' state it should be returned to the
;;   `unregistered' state.
303
;;
304
;; - rollback (files)
305
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
306 307
;;   Remove the tip revision of each of FILES from the repository.  If
;;   this function is not provided, trying to cancel a revision is
308 309 310 311
;;   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.)
312
;;
313
;; - merge (file rev1 rev2)
314
;;
315 316 317
;;   Merge the changes between REV1 and REV2 into the current working file
;;   (for non-distributed VCS).
;;
318
;; - merge-branch ()
319
;;
320 321
;;   Merge another branch into the current one, prompting for a
;;   location to merge from.
322
;;
323
;; - merge-news (file)
324 325
;;
;;   Merge recent changes from the current branch into FILE.
326 327 328 329 330 331 332
;;   (for non-distributed VCS).
;;
;; - pull (prompt)
;;
;;   Pull "upstream" changes into the current branch (for distributed
;;   VCS).  If PROMPT is non-nil, or if necessary, prompt for a
;;   location to pull from.
333
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
334
;; - steal-lock (file &optional revision)
335
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
336
;;   Steal any lock on the working revision of FILE, or on REVISION if
337 338 339
;;   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.
340
;;
341 342
;; - modify-change-comment (files rev comment)
;;
343
;;   Modify the change comments associated with the files at the
344 345
;;   given revision.  This is optional, many backends do not support it.
;;
346 347 348 349
;; - mark-resolved (files)
;;
;;   Mark conflicts as resolved.  Some VC systems need to run a
;;   command to mark conflicts as resolved.
350

351 352
;; HISTORY FUNCTIONS
;;
353
;; * print-log (files buffer &optional shortlog start-revision limit)
354
;;
355
;;   Insert the revision log for FILES into BUFFER.
356
;;   If SHORTLOG is true insert a short version of the log.
357 358 359
;;   If LIMIT is true insert only insert LIMIT log entries.  If the
;;   backend does not support limiting the number of entries to show
;;   it should return `limit-unsupported'.
360 361 362 363 364
;;   If START-REVISION is given, then show the log starting from that
;;   revision ("starting" in the sense of it being the _newest_
;;   revision shown, rather than the working revision, which is normally
;;   the case).  Not all backends support this.  At present, this is
;;   only ever used with LIMIT = 1 (by vc-annotate-show-log-revision-at-line).
365
;;
366 367 368 369 370 371 372 373 374 375
;; * log-outgoing (backend remote-location)
;;
;;   Insert in BUFFER the revision log for the changes that will be
;;   sent when performing a push operation to REMOTE-LOCATION.
;;
;; * log-incoming (backend remote-location)
;;
;;   Insert in BUFFER the revision log for the changes that will be
;;   received when performing a pull operation from REMOTE-LOCATION.
;;
376 377 378 379 380 381
;; - 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
382
;; - show-log-entry (revision)
383
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
384
;;   If provided, search the log entry for REVISION in the current buffer,
385 386 387
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
388
;; - comment-history (file)
389
;;
390
;;   Return a string containing all log entries that were made for FILE.
391
;;   This is used for transferring a file from one backend to another,
392
;;   retaining comment information.
393
;;
394
;; - update-changelog (files)
395 396 397 398 399 400
;;
;;   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.
;;
401
;; * diff (files &optional rev1 rev2 buffer)
402
;;
403 404
;;   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
405 406 407 408 409 410 411
;;   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).
412
;;
413
;; - revision-completion-table (files)
414
;;
415
;;   Return a completion table for existing revisions of FILES.
416 417
;;   The default is to not use any completion table.
;;
418
;; - annotate-command (file buf &optional rev)
419
;;
420
;;   If this function is provided, it should produce an annotated display
Eric S. Raymond's avatar
Eric S. Raymond committed
421
;;   of FILE in BUF, relative to revision REV.  Annotation means each line
422 423 424
;;   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.
425
;;
426
;; - annotate-time ()
427 428
;;
;;   Only required if `annotate-command' is defined for the backend.
429 430 431 432
;;   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
433
;;   to this format.  Return nil if no more lines of annotation appear
434 435 436
;;   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
437 438
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
439 440 441 442 443
;;
;; - 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
444
;;   (vc-annotate-convert-time (current-time)) -- i.e. the current
445 446
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
447
;;
448 449 450 451 452 453
;; - 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.
454 455 456
;;   If the backend supports annotating through copies and renames,
;;   and displays a file name and a revision, then return a cons
;;   (REVISION . FILENAME).
457

458
;; TAG SYSTEM
459
;;
460
;; - create-tag (dir name branchp)
461
;;
462 463 464 465 466 467 468
;;   Attach the tag NAME to the state of the working copy.  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
;;   assigns the tag to each file.
469
;;
470
;; - retrieve-tag (dir name update)
471
;;
472
;;   Retrieve the version tagged by NAME of all registered files at or below DIR.
473
;;   If UPDATE is non-nil, then update buffers of any files in the
474
;;   tag that are currently visited.  The default implementation
475 476
;;   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
477
;;   function to retrieve the corresponding revisions.
478

479 480
;; MISCELLANEOUS
;;
481
;; - make-version-backups-p (file)
482
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
483
;;   Return non-nil if unmodified repository revisions of FILE should be
484 485 486 487
;;   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.
;;
488
;; - root (file)
Xue Fuqiao's avatar
Xue Fuqiao committed
489
;; 
490 491
;;   Return the root of the VC controlled hierarchy for file.
;;
492 493 494 495
;; - 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
496
;;   is nil, it means that the repository is local.
497 498 499
;;   This function is used in `vc-stay-local-p' which backends can use
;;   for their convenience.
;;
Xue Fuqiao's avatar
Xue Fuqiao committed
500 501 502 503 504 505 506 507 508 509 510 511
;; - ignore (file &optional remove)
;;
;;   Ignore FILE under the current VCS.  When called interactively and
;;   with a prefix argument, remove an ignored file.  When called from
;;   Lisp code, if REMOVE is non-nil, remove FILE from ignored files."
;; 
;; - ignore-completion-table
;; 
;;   Return the completion table for files ignored by the current
;;   version control system, e.g., the entries in `.gitignore' and
;;   `.bzrignore'.
;; 
Eric S. Raymond's avatar
Eric S. Raymond committed
512
;; - previous-revision (file rev)
513
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
514 515
;;   Return the revision number that precedes REV for FILE, or nil if no such
;;   revision exists.
516
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
517
;; - next-revision (file rev)
518
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
519 520
;;   Return the revision number that follows REV for FILE, or nil if no such
;;   revision exists.
521
;;
522 523 524 525 526 527
;; - log-edit-mode ()
;;
;;   Turn on the mode used for editing the check in log.  This
;;   defaults to `log-edit-mode'.  If changed, it should use a mode
;;   derived from`log-edit-mode'.
;;
528
;; - check-headers ()
529 530 531
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
532
;; - clear-headers ()
533 534 535 536 537 538 539 540
;;
;;   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.
;;
541 542 543 544 545 546
;; - 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.
;;
547
;; - rename-file (old new)
548 549
;;
;;   Rename file OLD to NEW, both in the working area and in the
550 551
;;   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
552
;;
553 554
;; - find-file-hook ()
;;
555
;;   Operation called in current buffer when opening a file.  This can
556
;;   be used by the backend to setup some local variables it might need.
557 558 559 560 561 562 563 564 565
;;
;; - 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.
566
;;
567
;; - extra-dir-menu ()
568
;;
569 570 571 572 573 574
;;   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.
575 576 577 578 579 580
;;
;; - conflicted-files (dir)
;;
;;   Return the list of files where conflict resolution is needed in
;;   the project that contains DIR.
;;   FIXME: what should it do with non-text conflicts?
581

582 583
;;; Todo:

584 585
;; - Get rid of the "master file" terminology.

586 587
;; - Add key-binding for vc-delete-file.

Eric S. Raymond's avatar
Eric S. Raymond committed
588 589
;;;; New Primitives:
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
590 591
;; - deal with push/pull operations.
;;
592 593 594 595 596 597
;;;; Primitives that need changing:
;;
;; - vc-update/vc-merge should deal with VC systems that don't
;;   update/merge on a file basis, but on a whole repository basis.
;;   vc-update and vc-merge assume the arguments are always files,
;;   they don't deal with directories.  Make sure the *vc-dir* buffer
598
;;   is updated after these operations.
599 600
;;   At least bzr, git and hg should benefit from this.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
601
;;;; Improved branch and tag handling:
602
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
603 604 605 606
;; - 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
607 608 609
;;;; Internal cleanups:
;;
;; - backends that care about vc-stay-local should try to take it into
610
;;   account for vc-dir.  Is this likely to be useful???  YES!
Eric S. Raymond's avatar
Eric S. Raymond committed
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631
;;
;; - vc-expand-dirs should take a backend parameter and only look for
;;   files managed by that backend.
;;
;; - Another important thing: merge all the status-like backend operations.
;;   We should remove dir-status, 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.
;;
;;;; Other
;;
;; - when a file is in `conflict' state, turn on smerge-mode.
;;
;; - figure out what to do with conflicts that are not caused by the
;;   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, ...
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
632 633
;; - 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.
634
;;
635
;; - When vc-next-action calls vc-checkin it could pre-fill the
636
;;   *vc-log* buffer with some obvious items: the list of files that
637 638 639 640 641
;;   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...
;;
642
;; - most vc-dir backends need more work.  They might need to
643 644 645
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
646
;; - add a function that calls vc-dir to `find-directory-functions'.
647
;;
648 649
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
;;   files. Now that unregistered and ignored files are shown in
650
;;   vc-dir, it is possible that these commands are called
651 652
;;   for unregistered/ignored files.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
653 654 655
;; - vc-next-action needs work in order to work with multiple
;;   backends: `vc-state' returns the state for the default backend,
;;   not for the backend in the current *vc-dir* buffer.
Eric S. Raymond's avatar
Eric S. Raymond committed
656
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
657 658 659 660 661 662
;; - vc-dir-kill-dir-status-process should not be specific to dir-status,
;;   it should work for other async commands done through vc-do-command
;;   as well,
;;
;; - vc-dir toolbar needs more icons.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
663 664
;; - The backends should avoid using `vc-file-setprop' and `vc-file-getprop'.
;;
665
;;; Code:
666

Eric S. Raymond's avatar
Eric S. Raymond committed
667
(require 'vc-hooks)
668
(require 'vc-dispatcher)
669

670 671
(declare-function diff-setup-whitespace "diff-mode" ())

672
(eval-when-compile
673
  (require 'dired))
674

675 676 677 678
(declare-function dired-get-filename "dired" (&optional localp noerror))
(declare-function dired-move-to-filename "dired" (&optional err eol))
(declare-function dired-marker-regexp "dired" ())

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

;; General customization

686
(defgroup vc nil
687
  "Emacs interface to version control systems."
688 689 690
  :group 'tools)

(defcustom vc-initial-comment nil
691
  "If non-nil, prompt for initial comment when a file is registered."
692 693 694
  :type 'boolean
  :group 'vc)

695 696
(make-obsolete-variable 'vc-initial-comment "it has no effect." "23.2")

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

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

735
(defcustom vc-diff-switches nil
736
  "A string or list of strings specifying switches for diff under VC.
Glenn Morris's avatar
Glenn Morris committed
737 738 739 740 741 742 743 744 745
When running diff under a given BACKEND, VC uses the first
non-nil value of `vc-BACKEND-diff-switches', `vc-diff-switches',
and `diff-switches', in that order.  Since nil means to check the
next variable in the sequence, either of the first two may use
the value t to mean no switches at all.  `vc-diff-switches'
should contain switches that are specific to version control, but
not specific to any particular backend."
  :type '(choice (const :tag "Unspecified" nil)
		 (const :tag "None" t)
746
		 (string :tag "Argument String")
Glenn Morris's avatar
Glenn Morris committed
747
		 (repeat :tag "Argument List" :value ("") string))
748 749 750
  :group 'vc
  :version "21.1")

751
(defcustom vc-diff-knows-L nil
Lute Kamstra's avatar
Lute Kamstra committed
752
  "Indicates whether diff understands the -L option.
753 754 755 756 757
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)

758
(defcustom vc-log-show-limit 2000
759 760 761 762 763 764
  "Limit the number of items shown by the VC log commands.
Zero means unlimited.
Not all VC backends are able to support this feature."
  :type 'integer
  :group 'vc)

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

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

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

;;;###autoload
(defcustom vc-before-checkin-hook nil
792
  "Normal hook (list of functions) run before a commit or a file checkin.
793 794 795 796
See `run-hooks'."
  :type 'hook
  :group 'vc)

797
(defcustom vc-revert-show-diff t
798 799 800 801 802
  "If non-nil, `vc-revert' shows a `vc-diff' buffer before querying."
  :type 'boolean
  :group 'vc
  :version "24.1")

Eric S. Raymond's avatar
Eric S. Raymond committed
803 804
;; Header-insertion hair

805
(defcustom vc-static-header-alist
806
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
807
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
Lute Kamstra's avatar
Lute Kamstra committed
808
  "Associate static header string templates with file types.
809
A \%s in the template is replaced with the first string associated with
810
the file's version control type in `vc-BACKEND-header'."
811 812 813 814
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
815

816
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
817
  '((nroff-mode ".\\\"" ""))
Lute Kamstra's avatar
Lute Kamstra committed
818
  "Special comment delimiters for generating VC headers.
819 820
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
821 822 823 824 825 826
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
827

828

829
;; Variables users don't need to see
Eric S. Raymond's avatar
Eric S. Raymond committed
830

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

Eric S. Raymond's avatar
Eric S. Raymond committed
836 837
;; File property caching

838
(defun vc-clear-context ()
839
  "Clear all cached file properties."
840
  (interactive)
841
  (fillarray vc-file-prop-obarray 0))
842

843 844
(defmacro with-vc-properties (files form settings)
  "Execute FORM, then maybe set per-file properties for FILES.
845 846
If any of FILES is actually a directory, then do the same for all
buffers for files in that directory.
André Spiegel's avatar
André Spiegel committed
847 848 849
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."
850
  (declare (debug t))
851 852
  `(let ((vc-touched-properties (list t))
	 (flist nil))
853
     (dolist (file ,files)
854 855 856
       (if (file-directory-p file)
	   (dolist (buffer (buffer-list))
	     (let ((fname (buffer-file-name buffer)))
857
	       (when (and fname (string-prefix-p file fname))
858 859 860 861
		 (push fname flist))))
	 (push file flist)))
     ,form
     (dolist (file flist)
862 863 864 865 866
       (dolist (setting ,settings)
         (let ((property (car setting)))
           (unless (memq property vc-touched-properties)
             (put (intern file vc-file-prop-obarray)
                  property (cdr setting))))))))
867

868 869
;;; Code for deducing what fileset and backend to assume

870
(defun vc-backend-for-registration (file)
871 872 873 874 875 876 877 878 879 880 881 882 883 884 885