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

Paul Eggert's avatar
Paul Eggert committed
3
;; Copyright (C) 1992-1998, 2000-2015 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
;; now take a list of files.  These include: register, checkin, print-log,
Eric S. Raymond's avatar
Eric S. Raymond committed
49
;; 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 56 57
;; Supported version-control systems presently include CVS, RCS, SRC,
;; GNU Subversion, Bzr, Git, Mercurial, Monotone and SCCS (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
;; 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
75
;; operations are assumed to be fast.
Eric S. Raymond's avatar
Eric S. Raymond committed
76
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
77 78 79
;; The 'assumed to be fast' category includes SRC, even though it's
;; a wrapper around RCS.
;;
80 81 82 83 84 85 86 87 88 89 90 91 92 93
;; 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
94
;; `vc-sys-working-revision' should compute the working revision and
95 96 97
;; 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
98
;; value that the generic code might want to set (check for uses of
99 100 101 102 103
;; 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 (`-').
104

105 106 107 108
;; BACKEND PROPERTIES
;;
;; * revision-granularity
;;
109 110 111 112
;;   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
113

114 115
;; STATE-QUERYING FUNCTIONS
;;
116
;; * registered (file)
117
;;
118
;;   Return non-nil if FILE is registered in this backend.  Both this
119 120
;;   function as well as `state' should be careful to fail gracefully
;;   in the event that the backend executable is absent.  It is
121
;;   preferable that this function's *body* is autoloaded, that way only
122 123
;;   calling vc-registered does not cause the backend to be loaded
;;   (all the vc-FOO-registered functions are called to try to find
124
;;   the controlling backend for FILE).
125
;;
126
;; * state (file)
127 128 129 130
;;
;;   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
131
;;   C-x v v.
132
;;
133
;; - dir-status-files (dir files update-function)
134
;;
135
;;   Produce RESULT: a list of lists of the form (FILE VC-STATE EXTRA)
136
;;   for FILES in DIR.  If FILES is nil, report on all files in DIR.
137 138 139
;;   (It is OK, though possibly inefficient, to ignore the FILES argument
;;   and always report on all files in DIR.)
;;
140 141 142
;;   If FILES is non-nil, this function should report on all requested
;;   files, including up-to-date or ignored files.
;;
143 144 145
;;   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
146 147 148 149 150 151 152 153 154
;;   command.
;;
;;   When RESULT is computed, it should be passed back by doing:
;;   (funcall UPDATE-FUNCTION RESULT nil).  If the backend uses a
;;   process filter, hence it produces partial results, they can be
;;   passed back by doing: (funcall UPDATE-FUNCTION RESULT t) and then
;;   do a (funcall UPDATE-FUNCTION RESULT nil) when all the results
;;   have been computed.
;;
155
;;   To provide more backend specific functionality for `vc-dir'
156
;;   the following functions might be needed: `dir-extra-headers',
157
;;   `dir-printer', and `extra-dir-menu'.
158
;;
159
;; - dir-extra-headers (dir)
160
;;
161
;;   Return a string that will be added to the *vc-dir* buffer header.
162
;;
163
;; - dir-printer (fileinfo)
164
;;
165
;;   Pretty print the `vc-dir-fileinfo' FILEINFO.
166
;;   If a backend needs to show more information than the default FILE
167 168 169
;;   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.
170
;;
171 172
;; - status-fileinfo-extra (file)
;;
173
;;   Compute `vc-dir-fileinfo->extra' for FILE.
174
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
175
;; * working-revision (file)
176
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
177
;;   Return the working revision of FILE.  This is the revision fetched
Paul Eggert's avatar
Paul Eggert committed
178
;;   by the last checkout or update, not necessarily the same thing as the
179
;;   head or tip revision.  Should return "0" for a file added but not yet
180
;;   committed.
181
;;
182
;; * checkout-model (files)
183
;;
184
;;   Indicate whether FILES need to be "checked out" before they can be
185 186
;;   edited.  See `vc-checkout-model' for a list of possible values.
;;
187
;; - mode-line-string (file)
188
;;
189
;;   If provided, this function should return the VC-specific mode
190
;;   line string for FILE.  The returned string should have a
191 192 193 194
;;   `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.
195 196 197
;;
;; STATE-CHANGING FUNCTIONS
;;
198
;; * create-repo (backend)
199
;;
200 201
;;   Create an empty repository in the current directory and initialize
;;   it so VC mode can add files to it.  For file-oriented systems, this
202 203
;;   need do no more than create a subdirectory with the right name.
;;
204
;; * register (files &optional comment)
205
;;
206 207 208 209 210 211 212 213
;;   Register FILES in this backend.  Optionally, an initial
;;   description of the file, COMMENT, may be specified, but it is not
;;   guaranteed that the backend will do anything with this.  The
;;   implementation should pass the value of vc-register-switches to
;;   the backend command.  (Note: in older versions of VC, this
;;   command had an optional revision first argument that was
;;   not used; in still older ones it took a single file argument and
;;   not a list.)
214
;;
215
;; - responsible-p (file)
216 217 218 219 220 221 222
;;
;;   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.
;;
223
;; - receive-file (file rev)
224 225 226 227 228 229 230 231 232 233 234 235
;;
;;   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.
;;
236
;; * checkin (files comment)
237
;;
238 239 240 241
;;   Commit changes in FILES to this backend. COMMENT is used as a
;;   check-in comment.  The implementation should pass the value of
;;   vc-checkin-switches to the backend command.  The revision argument
;;   of some older VC versions is no longer supported.
242
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
243
;; * find-revision (file rev buffer)
244 245 246 247 248 249
;;
;;   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.
;;
250 251 252 253 254 255 256 257 258 259 260
;; * checkout (file &optional rev)
;;
;;   Check out revision REV of FILE into the working area.  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 is the revision
;;   to check out (default is the working revision).  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 to
;;   the backend command. The 'editable' argument of older VC versions
;;   is gone; all files are checked out editable.
261
;;
262
;; * revert (file &optional contents-done)
263
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
264
;;   Revert FILE back to the working revision.  If optional
265 266 267
;;   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.
268 269
;;   If FILE is in the `added' state it should be returned to the
;;   `unregistered' state.
270
;;
271
;; - merge-file (file rev1 rev2)
272
;;
273 274 275
;;   Merge the changes between REV1 and REV2 into the current working
;;   file (for non-distributed VCS).  It is expected that with an
;;   empty first revision this will behave like the merge-news method.
276
;;
277
;; - merge-branch ()
278
;;
279 280
;;   Merge another branch into the current one, prompting for a
;;   location to merge from.
281
;;
282
;; - merge-news (file)
283 284
;;
;;   Merge recent changes from the current branch into FILE.
285 286 287 288 289 290 291
;;   (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.
292
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
293
;; - steal-lock (file &optional revision)
294
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
295
;;   Steal any lock on the working revision of FILE, or on REVISION if
296 297 298
;;   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.
299
;;
300 301
;; - modify-change-comment (files rev comment)
;;
302
;;   Modify the change comments associated with the files at the
303 304
;;   given revision.  This is optional, many backends do not support it.
;;
305 306 307 308
;; - mark-resolved (files)
;;
;;   Mark conflicts as resolved.  Some VC systems need to run a
;;   command to mark conflicts as resolved.
309 310 311 312
;;
;; - find-admin-dir (file)
;;
;;   Return the administrative directory of FILE.
313

314 315
;; HISTORY FUNCTIONS
;;
316
;; * print-log (files buffer &optional shortlog start-revision limit)
317
;;
318
;;   Insert the revision log for FILES into BUFFER.
319
;;   If SHORTLOG is true insert a short version of the log.
320 321 322
;;   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'.
323 324 325 326 327
;;   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).
328
;;
329 330 331 332 333 334 335 336 337 338
;; * 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.
;;
339 340 341 342 343 344
;; - 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
345
;; - show-log-entry (revision)
346
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
347
;;   If provided, search the log entry for REVISION in the current buffer,
348 349 350
;;   and make sure it is displayed in the buffer's window.  The default
;;   implementation of this function works for RCS-style logs.
;;
351
;; - comment-history (file)
352
;;
353
;;   Return a string containing all log entries that were made for FILE.
354
;;   This is used for transferring a file from one backend to another,
355
;;   retaining comment information.
356
;;
357
;; - update-changelog (files)
358 359 360 361 362 363
;;
;;   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.
;;
364
;; * diff (files &optional rev1 rev2 buffer async)
365
;;
366
;;   Insert the diff for FILE into BUFFER, or the *vc-diff* buffer if
367
;;   BUFFER is nil.  If ASYNC is non-nil, run asynchronously.  If REV1
368 369
;;   and REV2 are non-nil, report differences from REV1 to REV2.  If
;;   REV1 is nil, use the working revision (as found in the
370 371
;;   repository) as the older revision if REV2 is nil as well;
;;   otherwise, diff against an empty tree.  If REV2 is nil, use the
372
;;   current working-copy contents as the newer revision.  This
Eric S. Raymond's avatar
Eric S. Raymond committed
373 374 375 376
;;   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).
377
;;
378
;; - revision-completion-table (files)
379
;;
380
;;   Return a completion table for existing revisions of FILES.
381 382
;;   The default is to not use any completion table.
;;
383
;; - annotate-command (file buf &optional rev)
384
;;
385
;;   If this function is provided, it should produce an annotated display
Eric S. Raymond's avatar
Eric S. Raymond committed
386
;;   of FILE in BUF, relative to revision REV.  Annotation means each line
387 388 389
;;   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.
390
;;
391
;; - annotate-time ()
392 393
;;
;;   Only required if `annotate-command' is defined for the backend.
394 395 396 397
;;   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
398
;;   to this format.  Return nil if no more lines of annotation appear
399 400 401
;;   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
402 403
;;   relevant backend.  This function also affects how much of the line
;;   is fontified; where it leaves point is where fontification begins.
404 405 406 407 408
;;
;; - 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
409
;;   (vc-annotate-convert-time (current-time)) -- i.e. the current
410 411
;;   time with hours, minutes, and seconds included.  Probably safe to
;;   ignore.  Return the current-time, in units of fractional days.
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 421
;;   If the backend supports annotating through copies and renames,
;;   and displays a file name and a revision, then return a cons
;;   (REVISION . FILENAME).
422 423 424 425 426 427 428 429 430
;;
;; - region-history (FILE BUFFER LFROM LTO)
;;
;;   Insert into BUFFER the history (log comments and diffs) of the content of
;;   FILE between lines LFROM and LTO.  This is typically done asynchronously.
;;
;; - region-history-mode ()
;;
;;   Major mode to use for the output of `region-history'.
431

432
;; TAG SYSTEM
433
;;
434
;; - create-tag (dir name branchp)
435
;;
436 437 438 439 440 441 442
;;   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.
443
;;
444
;; - retrieve-tag (dir name update)
445
;;
446
;;   Retrieve the version tagged by NAME of all registered files at or below DIR.
447
;;   If UPDATE is non-nil, then update buffers of any files in the
448
;;   tag that are currently visited.  The default implementation
449 450
;;   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
451
;;   function to retrieve the corresponding revisions.
452

453 454
;; MISCELLANEOUS
;;
455
;; - make-version-backups-p (file)
456
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
457
;;   Return non-nil if unmodified repository revisions of FILE should be
458 459 460 461
;;   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.
;;
462
;; - root (file)
463
;;
464 465
;;   Return the root of the VC controlled hierarchy for file.
;;
Xue Fuqiao's avatar
Xue Fuqiao committed
466 467 468 469 470 471 472 473
;; - ignore (file &optional directory)
;;
;;   Ignore FILE under the VCS of DIRECTORY (default is `default-directory').
;;   FILE is a file wildcard.
;;   When called interactively and with a prefix argument, remove FILE
;;   from ignored files.
;;   When called from Lisp code, if DIRECTORY is non-nil, the
;;   repository to use will be deduced by DIRECTORY.
474
;;
Xue Fuqiao's avatar
Xue Fuqiao committed
475
;; - ignore-completion-table
476
;;
Xue Fuqiao's avatar
Xue Fuqiao committed
477 478 479
;;   Return the completion table for files ignored by the current
;;   version control system, e.g., the entries in `.gitignore' and
;;   `.bzrignore'.
480
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
481
;; - previous-revision (file rev)
482
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
483 484
;;   Return the revision number that precedes REV for FILE, or nil if no such
;;   revision exists.
485
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
486
;; - next-revision (file rev)
487
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
488 489
;;   Return the revision number that follows REV for FILE, or nil if no such
;;   revision exists.
490
;;
491 492 493 494 495 496
;; - 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'.
;;
497
;; - check-headers ()
498 499 500
;;
;;   Return non-nil if the current buffer contains any version headers.
;;
501 502 503 504 505 506
;; - 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.
;;
507
;; - rename-file (old new)
508 509
;;
;;   Rename file OLD to NEW, both in the working area and in the
510 511
;;   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
512
;;
513 514
;; - find-file-hook ()
;;
515
;;   Operation called in current buffer when opening a file.  This can
516
;;   be used by the backend to setup some local variables it might need.
517 518 519 520 521 522 523 524 525
;;
;; - 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.
526
;;
527
;; - extra-dir-menu ()
528
;;
529 530 531 532 533 534
;;   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.
535 536 537 538 539 540
;;
;; - 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?
541

542 543
;;; Changes from the pre-25.1 API:
;;
544 545 546 547 548 549 550 551 552 553 554
;; - INCOMPATIBLE CHANGE: The 'editable' optional argument of
;;   vc-checkout is gone. The upper level assumes that all files are
;;   checked out editable. This moves closer to emulating modern
;;   non-locking behavior even on very old VCSes.
;;
;; - INCOMPATIBLE CHANGE: The vc-register function and its backend
;;   implementations no longer take a first optional revision
;;   argument, since on no system since RCS has setting the initial
;;   revision been even possible, let alone sane.
;;
;;   INCOMPATIBLE CHANGE: In older versions of the API, vc-diff did
555
;;   not take an async-mode flag as a fourth optional argument.  (This
556 557 558 559 560 561 562
;;   change eliminated a particularly ugly global.)
;;
;; - INCOMPATIBLE CHANGE: The backend operation for non-distributed
;;   VCSes formerly called "merge" is now "merge-file" (to contrast
;;   with merge-branch), and does its own prompting for revisions.
;;   (This fixes a layer violation that produced bad behavior under
;;   SVN.)
563
;;
564 565 566
;; - INCOMPATIBLE CHANGE: The old fourth 'default-state' argument of
;;   vc-dir-status-files is gone; none of the back ends actually used it.
;;
567 568 569
;; - vc-dir-status is no longer a public method; it has been replaced
;;   by vc-dir-status-files.
;;
570 571 572
;; - vc-state-heuristic is no longer a public method (the CVS backend
;;   retains it as a private one).
;;
573 574 575 576 577
;; - the vc-mistrust-permissions configuration variable is gone; the
;;   code no longer relies on permissions except in one corner case where
;;   CVS leaves no alternative (which was not gated by this variable).  The
;;   only affected back ends were SCCS and RCS.
;;
578 579 580 581
;; - vc-stay-local-p and repository-hostname are no longer part
;;   of the public API. The vc-stay-local configuration variable
;;   remains but only affects the CVS back end.
;;
582 583 584 585
;; - The init-revision function and the default-initial-revision
;;   variable are gone.  These have't made sense on anything shipped
;;   since RCS, and using them was a dumb stunt even on RCS.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
586
;; - workfile-unchanged-p is no longer a public back-end method.  It
587 588 589
;;   was redundant with vc-state and usually implemented with a trivial
;;   call to it.  A few older back ends retain versions for internal use in
;;   their vc-state functions.
590
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
591 592 593 594
;; - could-register is no longer a public method.  Only vc-cvs ever used it
;;
;;   The vc-keep-workfiles configuration variable is gone.  Used only by
;;   the RCS and SCCS backends, it was an invitation to shoot self in foot
Paul Eggert's avatar
Paul Eggert committed
595
;;   when set to the (non-default) value nil.  The original justification
Eric S. Raymond's avatar
Eric S. Raymond committed
596 597 598 599
;;   for it (saving disk space) is long obsolete.
;;
;; - The rollback method (implemented by RCS and SCCS only) is gone. See
;;   the to-do note on uncommit.
600 601 602 603 604
;;
;; - latest-on-branch-p is no longer a public method. It was to be used
;;   for implementing rollback. RCS keeps its implementation (the only one)
;;   for internal use.

605

606 607
;;; Todo:

Eric S. Raymond's avatar
Eric S. Raymond committed
608 609
;;;; New Primitives:
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
610 611 612
;; - uncommit: undo last checkin, leave changes in place in the workfile,
;;   stash the commit comment for re-use.
;;
613
;; - deal with push operations.
Dan Nicolaescu's avatar
Dan Nicolaescu committed
614
;;
615 616
;;;; Primitives that need changing:
;;
617
;; - vc-update/vc-merge should deal with VC systems that don't do
618 619 620
;;   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
621
;;   is updated after these operations.
622 623
;;   At least bzr, git and hg should benefit from this.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
624
;;;; Improved branch and tag handling:
625
;;
626 627
;; - Make sure the *vc-dir* buffer is updated after merge-branch operations.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
628 629 630 631
;; - 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.
;;
632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656
;; - Add a primitives for switching to a branch (creating it if required.
;;
;; - Add the ability to list tags and branches.
;;
;;;; Unify two different versions of the amend capability
;;
;; - Some back ends (SCCS/RCS/SVN/SRC), have an amend capability that can
;;   be invoked from log-view.
;;
;; - The git backend supports amending, but in a different
;;   way (press `C-c C-e' in log-edit buffer, when making a new commit).
;;
;; - Second, `log-view-modify-change-comment' doesn't seem to support
;;   modern backends at all because `log-view-extract-comment'
;;   unconditionally calls `log-view-current-file'. This should be easy to
;;   fix.
;;
;; - Third, doing message editing in log-view might be a natural way to go
;;   about it, but editing any but the last commit (and even it, if it's
;;   been pushed) is a dangerous operation in Git, which we shouldn't make
;;   too easy for users to perform.
;;
;;   There should be a check that the given comment is not reachable
;;   from any of the "remote" refs?
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
657 658
;;;; Other
;;
659 660 661 662 663
;; - asynchronous checkin and commit, so you can keep working in other
;;   buffers while the repo operation happens.
;;
;; - Direct support for stash/shelve.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
664 665 666 667 668 669 670 671
;; - 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
672 673
;; - 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.
674
;;
675
;; - When vc-next-action calls vc-checkin it could pre-fill the
676
;;   *vc-log* buffer with some obvious items: the list of files that
677 678 679 680 681
;;   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...
;;
682
;; - most vc-dir backends need more work.  They might need to
683 684 685
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
686
;; - add a function that calls vc-dir to `find-directory-functions'.
687
;;
688 689
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
;;   files. Now that unregistered and ignored files are shown in
690
;;   vc-dir, it is possible that these commands are called
691 692
;;   for unregistered/ignored files.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
693 694 695
;; - 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
696
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
697 698 699 700 701 702
;; - 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
703 704
;; - The backends should avoid using `vc-file-setprop' and `vc-file-getprop'.
;;
705
;;; Code:
706

Eric S. Raymond's avatar
Eric S. Raymond committed
707
(require 'vc-hooks)
708
(require 'vc-dispatcher)
709
(require 'cl-lib)
710

711 712
(declare-function diff-setup-whitespace "diff-mode" ())

713
(eval-when-compile
714
  (require 'dired))
715

716 717 718 719
(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" ())

720 721 722 723
(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
724 725 726

;; General customization

727
(defgroup vc nil
728
  "Emacs interface to version control systems."
729 730 731
  :group 'tools)

(defcustom vc-initial-comment nil
732
  "If non-nil, prompt for initial comment when a file is registered."
733 734 735
  :type 'boolean
  :group 'vc)

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

738
(defcustom vc-checkin-switches nil
739
  "A string or list of strings specifying extra switches for checkin.
740 741 742 743 744 745 746 747 748
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
749
  "A string or list of strings specifying extra switches for checkout.
750 751 752 753 754 755 756 757 758
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
759
  "A string or list of strings; extra switches for registering a file.
760 761 762 763 764 765 766 767
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)

768
(defcustom vc-diff-switches nil
769
  "A string or list of strings specifying switches for diff under VC.
Glenn Morris's avatar
Glenn Morris committed
770 771 772 773 774 775 776 777 778
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)
779
		 (string :tag "Argument String")
Glenn Morris's avatar
Glenn Morris committed
780
		 (repeat :tag "Argument List" :value ("") string))
781 782 783
  :group 'vc
  :version "21.1")

784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803
(defcustom vc-annotate-switches nil
  "A string or list of strings specifying switches for annotate under VC.
When running annotate under a given BACKEND, VC uses the first
non-nil value of `vc-BACKEND-annotate-switches', `vc-annotate-switches',
and `annotate-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-annotate-switches'
should contain switches that are specific to version control, but
not specific to any particular backend.

As very few switches (if any) are used across different VC tools,
please consider using the specific `vc-BACKEND-annotate-switches'
for the backend you use."
  :type '(choice (const :tag "Unspecified" nil)
		 (const :tag "None" t)
		 (string :tag "Argument String")
		 (repeat :tag "Argument List" :value ("") string))
  :group 'vc
  :version "25.1")

804
(defcustom vc-log-show-limit 2000
805 806 807 808 809 810
  "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)

811
(defcustom vc-allow-async-revert nil
812
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
813 814 815 816 817
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
818
  :version "22.1")
819

André Spiegel's avatar
André Spiegel committed
820 821
;;;###autoload
(defcustom vc-checkout-hook nil
822
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
823 824 825 826 827
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

828 829
;;;###autoload
(defcustom vc-checkin-hook nil
830
  "Normal hook (list of functions) run after commit or file checkin.
831
See also `log-edit-done-hook'."
832
  :type 'hook
833
  :options '(log-edit-comment-to-change-log)
834 835 836 837
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
838
  "Normal hook (list of functions) run before a commit or a file checkin.
839 840 841 842
See `run-hooks'."
  :type 'hook
  :group 'vc)

843
(defcustom vc-revert-show-diff t
844 845 846 847 848
  "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
849 850
;; Header-insertion hair

851
(defcustom vc-static-header-alist
852
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
853
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
Lute Kamstra's avatar
Lute Kamstra committed
854
  "Associate static header string templates with file types.
855
A \%s in the template is replaced with the first string associated with
856
the file's version control type in `vc-BACKEND-header'."
857 858 859 860
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
861

862
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
863
  '((nroff-mode ".\\\"" ""))
Lute Kamstra's avatar
Lute Kamstra committed
864
  "Special comment delimiters for generating VC headers.
865 866
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
867 868 869 870 871 872
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
873

874

Eric S. Raymond's avatar
Eric S. Raymond committed
875 876
;; File property caching

877
(defun vc-clear-context ()
878
  "Clear all cached file properties."
879
  (interactive)
880
  (fillarray vc-file-prop-obarray 0))
881

882 883
(defmacro with-vc-properties (files form settings)
  "Execute FORM, then maybe set per-file properties for FILES.
884 885
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
886 887 888
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."
889
  (declare (debug t))
890 891
  `(let ((vc-touched-properties (list t))
	 (flist nil))
892
     (dolist (file ,files)
893 894 895
       (if (file-directory-p file)
	   (dolist (buffer (buffer-list))
	     (let ((fname (buffer-file-name buffer)))
896
	       (when (and fname (string-prefix-p file fname))
897 898 899 900
		 (push fname flist))))
	 (push file flist)))
     ,form
     (dolist (file flist)
901 902 903 904 905
       (dolist (setting ,settings)
         (let ((property (car setting)))
           (unless (memq property vc-touched-properties)
             (put (intern file vc-file-prop-obarray)
                  property (cdr setting))))))))
906

907 908
;;; Code for deducing what fileset and backend to assume

909
(defun vc-backend-for-registration (file)
910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931