vc.el 102 KB
Newer Older
1
;;; vc.el --- drive a version-control system from within Emacs
Eric S. Raymond's avatar
Eric S. Raymond committed
2

3
;; Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000,
Glenn Morris's avatar
Glenn Morris committed
4
;;   2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
5
;;   Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
6

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

;; This file is part of GNU Emacs.

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

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
24
;; along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
Eric S. Raymond's avatar
Eric S. Raymond committed
25

26 27 28
;;; Credits:

;; VC was initially designed and implemented by Eric S. Raymond
29
;; <esr@thyrsus.com> in 1992.  Over the years, many other people have
30
;; contributed substantial amounts of work to VC.  These include:
31
;;
32 33 34 35
;;   Per Cederqvist <ceder@lysator.liu.se>
;;   Paul Eggert <eggert@twinsun.com>
;;   Sebastian Kremer <sk@thp.uni-koeln.de>
;;   Martin Lorentzson <martinl@gnu.org>
Dave Love's avatar
Dave Love committed
36
;;   Dave Love <fx@gnu.org>
37
;;   Stefan Monnier <monnier@cs.yale.edu>
38 39
;;   Thien-Thi Nguyen <ttn@gnu.org>
;;   Dan Nicolaescu <dann@ics.uci.edu>
André Spiegel's avatar
André Spiegel committed
40
;;   J.D. Smith <jdsmith@alum.mit.edu>
41 42
;;   Andre Spiegel <spiegel@gnu.org>
;;   Richard Stallman <rms@gnu.org>
43 44 45 46 47
;;
;; In July 2007 ESR returned and redesigned the mode to cope better
;; with modern version-control systems that do commits by fileset
;; rather than per individual file.
;;
48 49
;; If you maintain a client of the mode or customize it in your .emacs,
;; note that some backend functions which formerly took single file arguments
50 51
;; now take a list of files.  These include: register, checkin, print-log,
;; rollback, and diff.
52

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

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

534 535
;;; Todo:

536 537
;; - Get rid of the "master file" terminology.

538 539
;; - Add key-binding for vc-delete-file.

Eric S. Raymond's avatar
Eric S. Raymond committed
540 541
;;;; New Primitives:
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
542 543
;; - deal with push/pull operations.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
544 545
;; - 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
546
;;
547 548 549 550 551 552
;;;; 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
553
;;   is updated after these operations.
554 555
;;   At least bzr, git and hg should benefit from this.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
556
;;;; Improved branch and tag handling:
557
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
558 559 560 561
;; - 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.
;;
562
;; - vc-create-tag and vc-retrieve-tag should update the
Eric S. Raymond's avatar
Eric S. Raymond committed
563 564 565 566 567 568 569 570 571 572 573 574 575
;;   buffers that might be visiting the affected files.
;;
;;;; Default Behavior:
;;
;; - do not default to RCS anymore when the current directory is not
;;   controlled by any VCS and the user does C-x v v
;;
;; - vc-responsible-backend should not return RCS if no backend
;;   declares itself responsible.
;;
;;;; Internal cleanups:
;;
;; - backends that care about vc-stay-local should try to take it into
576
;;   account for vc-dir.  Is this likely to be useful???  YES!
Eric S. Raymond's avatar
Eric S. Raymond committed
577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597
;;
;; - 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
598 599
;; - 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.
600
;;
601 602 603 604 605 606 607
;; - 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...
;;
608
;; - most vc-dir backends need more work.  They might need to
609 610 611
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
612
;; - add a function that calls vc-dir to `find-directory-functions'.
613
;;
614 615
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
;;   files. Now that unregistered and ignored files are shown in
616
;;   vc-dir, it is possible that these commands are called
617 618
;;   for unregistered/ignored files.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
619 620 621
;; - 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
622
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
623 624 625 626 627 628
;; - 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
629 630
;; - The backends should avoid using `vc-file-setprop' and `vc-file-getprop'.
;;
631
;;; Code:
632

Eric S. Raymond's avatar
Eric S. Raymond committed
633
(require 'vc-hooks)
634
(require 'vc-dispatcher)
635

636
(eval-when-compile
637
  (require 'cl))
638

639 640 641 642
(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
643 644 645

;; General customization

646 647 648 649 650
(defgroup vc nil
  "Version-control system in Emacs."
  :group 'tools)

(defcustom vc-initial-comment nil
651
  "If non-nil, prompt for initial comment when a file is registered."
652 653 654
  :type 'boolean
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
655 656
(defcustom vc-default-init-revision "1.1"
  "A string used as the default revision number when a new file is registered.
657 658
This can be overridden by giving a prefix argument to \\[vc-register].  This
can also be overridden by a particular VC backend."
659
  :type 'string
Dan Nicolaescu's avatar
Dan Nicolaescu committed
660 661
  :group 'vc
  :version "20.3")
662

663
(defcustom vc-checkin-switches nil
664
  "A string or list of strings specifying extra switches for checkin.
665 666 667 668 669 670 671 672 673
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
674
  "A string or list of strings specifying extra switches for checkout.
675 676 677 678 679 680 681 682 683
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
684
  "A string or list of strings; extra switches for registering a file.
685 686 687 688 689 690 691 692
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)

693
(defcustom vc-diff-switches nil
694
  "A string or list of strings specifying switches for diff under VC.
Glenn Morris's avatar
Glenn Morris committed
695 696 697 698 699 700 701 702 703
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)
704
		 (string :tag "Argument String")
Glenn Morris's avatar
Glenn Morris committed
705
		 (repeat :tag "Argument List" :value ("") string))
706 707 708
  :group 'vc
  :version "21.1")

709
(defcustom vc-diff-knows-L nil
Lute Kamstra's avatar
Lute Kamstra committed
710
  "Indicates whether diff understands the -L option.
711 712 713 714 715
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)

716
(defcustom vc-allow-async-revert nil
717
  "Specifies whether the diff during \\[vc-revert] may be asynchronous.
718 719 720 721 722
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
723
  :version "22.1")
724

André Spiegel's avatar
André Spiegel committed
725 726
;;;###autoload
(defcustom vc-checkout-hook nil
727
  "Normal hook (list of functions) run after checking out a file.
André Spiegel's avatar
André Spiegel committed
728 729 730 731 732
See `run-hooks'."
  :type 'hook
  :group 'vc
  :version "21.1")

733 734
;;;###autoload
(defcustom vc-checkin-hook nil
735
  "Normal hook (list of functions) run after commit or file checkin.
736
See also `log-edit-done-hook'."
737
  :type 'hook
738
  :options '(log-edit-comment-to-change-log)
739 740 741 742
  :group 'vc)

;;;###autoload
(defcustom vc-before-checkin-hook nil
743
  "Normal hook (list of functions) run before a commit or a file checkin.
744 745 746 747
See `run-hooks'."
  :type 'hook
  :group 'vc)

Eric S. Raymond's avatar
Eric S. Raymond committed
748 749
;; Header-insertion hair

750
(defcustom vc-static-header-alist
751
  '(("\\.c\\'" .
Eric S. Raymond's avatar
Eric S. Raymond committed
752
     "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n#endif /* lint */\n"))
Lute Kamstra's avatar
Lute Kamstra committed
753
  "Associate static header string templates with file types.
754
A \%s in the template is replaced with the first string associated with
755
the file's version control type in `vc-header-alist'."
756 757 758 759
  :type '(repeat (cons :format "%v"
		       (regexp :tag "File Type")
		       (string :tag "Header String")))
  :group 'vc)
760

761
(defcustom vc-comment-alist
Eric S. Raymond's avatar
Eric S. Raymond committed
762
  '((nroff-mode ".\\\"" ""))
Lute Kamstra's avatar
Lute Kamstra committed
763
  "Special comment delimiters for generating VC headers.
764 765
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
766 767 768 769 770 771
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
772

773
(defcustom vc-checkout-carefully (= (user-uid) 0)
Lute Kamstra's avatar
Lute Kamstra committed
774
  "Non-nil means be extra-careful in checkout.
775
Verify that the file really is not locked
776 777 778
and that its contents match what the master file says."
  :type 'boolean
  :group 'vc)
779 780 781
(make-obsolete-variable 'vc-checkout-carefully
                        "the corresponding checks are always done now."
                        "21.1")
782

783

784
;; Variables users don't need to see
Eric S. Raymond's avatar
Eric S. Raymond committed
785

786 787 788 789 790
(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
791 792
;; File property caching

793
(defun vc-clear-context ()
794
  "Clear all cached file properties."
795
  (interactive)
796
  (fillarray vc-file-prop-obarray 0))
797

798 799
(defmacro with-vc-properties (files form settings)
  "Execute FORM, then maybe set per-file properties for FILES.
André Spiegel's avatar
André Spiegel committed
800 801 802
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."
803
  (declare (debug t))
804
  `(let ((vc-touched-properties (list t)))
805
     ,form
806
     (dolist (file ,files)
807 808 809 810 811
       (dolist (setting ,settings)
         (let ((property (car setting)))
           (unless (memq property vc-touched-properties)
             (put (intern file vc-file-prop-obarray)
                  property (cdr setting))))))))
812

813 814
;;; Code for deducing what fileset and backend to assume

815 816 817 818 819 820 821 822 823 824 825 826 827 828 829
(defun vc-responsible-backend (file &optional register)
  "Return the name of a backend system that is responsible for FILE.
The optional argument REGISTER means that a backend suitable for
registration should be found.

If REGISTER is nil, then if FILE is already registered, return the
backend of FILE.  If FILE is not registered, or a directory, then the
first backend in `vc-handled-backends' that declares itself
responsible for FILE is returned.  If no backend declares itself
responsible, return the first backend.

If REGISTER is non-nil, return the first responsible backend under
which FILE is not yet registered.  If there is no such backend, return
the first backend under which FILE is not yet registered, but could
be registered."
830 831
  (when (not vc-handled-backends)
    (error "No handled backends"))
832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854
  (or (and (not (file-directory-p file)) (not register) (vc-backend file))
      (catch 'found
	;; First try: find a responsible backend.  If this is for registration,
	;; it must be a backend under which FILE is not yet registered.
	(dolist (backend vc-handled-backends)
	  (and (or (not register)
		   (not (vc-call-backend backend 'registered file)))
	       (vc-call-backend backend 'responsible-p file)
	       (throw 'found backend)))
	;; no responsible backend
	(if (not register)
	    ;; if this is not for registration, the first backend must do
	    (car vc-handled-backends)
	  ;; for registration, we need to find a new backend that
	  ;; could register FILE
	  (dolist (backend vc-handled-backends)
	    (and (not (vc-call-backend backend 'registered file))
		 (vc-call-backend backend 'could-register file)
		 (throw 'found backend)))
	  (error "No backend that could register")))))

(defun vc-expand-dirs (file-or-dir-list)
  "Expands directories in a file list specification.
855
Within directories, only files already under version control are noticed."
856 857
  (let ((flattened '()))
    (dolist (node file-or-dir-list)
858 859 860 861
      (when (file-directory-p node)
	(vc-file-tree-walk
	 node (lambda (f) (when (vc-backend f) (push f flattened)))))
      (unless (file-directory-p node) (push node flattened)))
862 863
    (nreverse flattened)))

864 865 866 867 868 869 870
(defun vc-derived-from-dir-mode (&optional buffer)
  "Are we in a VC-directory buffer, or do we have one as an ancestor?"
  (let ((buffer (or buffer (current-buffer))))
    (cond ((derived-mode-p 'vc-dir-mode) t)
	  (vc-parent-buffer (vc-derived-from-dir-mode vc-parent-buffer))
	  (t nil))))

Dan Nicolaescu's avatar
Dan Nicolaescu committed
871
(defvar vc-dir-backend)
872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889

;; FIXME: this is not functional, commented out.
;; (defun vc-deduce-fileset (&optional observer)
;;   "Deduce a set of files and a backend to which to apply an operation and
;; the common state of the fileset.  Return (BACKEND . FILESET)."
;;   (let* ((selection (vc-dispatcher-selection-set observer))
;; 	 (raw (car selection))		;; Selection as user made it
;; 	 (cooked (cdr selection))	;; Files only
;;          ;; FIXME: Store the backend in a buffer-local variable.
;;          (backend (if (vc-derived-from-dir-mode (current-buffer))
;; 		      ;; FIXME: this should use vc-dir-backend from
;; 		      ;; the *vc-dir* buffer.
;;                       (vc-responsible-backend default-directory)
;;                     (assert (and (= 1 (length raw))
;;                                  (not (file-directory-p (car raw)))))
;;                     (vc-backend (car cooked)))))
;; 	(cons backend selection)))

Dan Nicolaescu's avatar
Dan Nicolaescu committed
890
(declare-function vc-dir-current-file "vc-dir" ())
891
(declare-function vc-dir-deduce-fileset "vc-dir" (&optional state-model-only-files))
Dan Nicolaescu's avatar
Dan Nicolaescu committed
892

893 894
(defun vc-deduce-fileset (&optional observer allow-unregistered
				    state-model-only-files)