vc.el 118 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-2019 Free Software Foundation, Inc.
Eric S. Raymond's avatar
Eric S. Raymond committed
4

5
;; Author:     FSF (see below for full credits)
6
;; Maintainer: emacs-devel@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 <https://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
;; When using SCCS, RCS, CVS: be careful not to do repo surgery, or
;; operations like registrations and deletions and renames, outside VC
66
;; while VC is running.  The support for these systems was designed
67 68
;; when disks were much slower, and the code maintains a lot of
;; internal state in order to reduce expensive operations to a
69
;; minimum.  Thus, if you mess with the repo while VC's back is turned,
70 71 72 73
;; 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
74
;; 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
;;
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 &optional rev)
237
;;
238
;;   Commit changes in FILES to this backend.  COMMENT is used as a
239
;;   check-in comment.  The implementation should pass the value of
240 241 242
;;   vc-checkin-switches to the backend command.  The optional REV
;;   revision argument is only supported with some older VCSes, like
;;   RCS and CVS, and is otherwise silently ignored.
243
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
244
;; * find-revision (file rev buffer)
245 246 247 248 249 250
;;
;;   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.
;;
251 252 253 254 255 256 257 258 259
;; * 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
260
;;   the backend command.  The 'editable' argument of older VC versions
261
;;   is gone; all files are checked out editable.
262
;;
263
;; * revert (file &optional contents-done)
264
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
265
;;   Revert FILE back to the working revision.  If optional
266 267 268
;;   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.
269 270
;;   If FILE is in the `added' state it should be returned to the
;;   `unregistered' state.
271
;;
272
;; - merge-file (file rev1 rev2)
273
;;
274 275 276
;;   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.
277
;;
278
;; - merge-branch ()
279
;;
280 281
;;   Merge another branch into the current one, prompting for a
;;   location to merge from.
282
;;
283
;; - merge-news (file)
284 285
;;
;;   Merge recent changes from the current branch into FILE.
286 287 288 289 290 291 292
;;   (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.
293
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
294
;; - steal-lock (file &optional revision)
295
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
296
;;   Steal any lock on the working revision of FILE, or on REVISION if
297 298 299
;;   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.
300
;;
301 302
;; - modify-change-comment (files rev comment)
;;
303
;;   Modify the change comments associated with the files at the
304 305
;;   given revision.  This is optional, many backends do not support it.
;;
306 307 308 309
;; - mark-resolved (files)
;;
;;   Mark conflicts as resolved.  Some VC systems need to run a
;;   command to mark conflicts as resolved.
310 311 312 313
;;
;; - find-admin-dir (file)
;;
;;   Return the administrative directory of FILE.
314

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

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

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

543 544
;;; Changes from the pre-25.1 API:
;;
545
;; - INCOMPATIBLE CHANGE: The 'editable' optional argument of
546 547
;;   vc-checkout is gone.  The upper level assumes that all files are
;;   checked out editable.  This moves closer to emulating modern
548 549 550 551 552 553 554
;;   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.
;;
555
;; - INCOMPATIBLE CHANGE: In older versions of the API, vc-diff did
556
;;   not take an async-mode flag as a fourth optional argument.  (This
557 558 559 560 561 562 563
;;   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.)
564
;;
565
;; - INCOMPATIBLE CHANGE: The old fourth 'default-state' argument of
566
;;   dir-status-files is gone; none of the back ends actually used it.
567
;;
568 569
;; - dir-status is no longer a public method; it has been replaced by
;;   dir-status-files.
570
;;
571
;; - state-heuristic is no longer a public method (the CVS backend
572 573
;;   retains it as a private one).
;;
574 575 576 577 578
;; - 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.
;;
579
;; - vc-stay-local-p and repository-hostname are no longer part
580
;;   of the public API.  The vc-cvs-stay-local configuration variable
581
;;   remains and only affects the CVS back end.
582
;;
583
;; - The init-revision function and the default-initial-revision
584
;;   variable are gone.  These haven't made sense on anything shipped
585 586
;;   since RCS, and using them was a dumb stunt even on RCS.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
587
;; - workfile-unchanged-p is no longer a public back-end method.  It
588 589 590
;;   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.
591
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
592 593 594 595
;; - 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
596
;;   when set to the (non-default) value nil.  The original justification
Eric S. Raymond's avatar
Eric S. Raymond committed
597 598
;;   for it (saving disk space) is long obsolete.
;;
599
;; - The rollback method (implemented by RCS and SCCS only) is gone.  See
Eric S. Raymond's avatar
Eric S. Raymond committed
600
;;   the to-do note on uncommit.
601
;;
602 603
;; - 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)
604 605
;;   for internal use.

606

607 608
;;; Todo:

Eric S. Raymond's avatar
Eric S. Raymond committed
609 610
;;;; New Primitives:
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
611 612 613
;; - uncommit: undo last checkin, leave changes in place in the workfile,
;;   stash the commit comment for re-use.
;;
614
;; - deal with push operations.
Dan Nicolaescu's avatar
Dan Nicolaescu committed
615
;;
616 617
;;;; Primitives that need changing:
;;
618
;; - vc-update/vc-merge should deal with VC systems that don't do
619 620 621
;;   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
622
;;   is updated after these operations.
623 624
;;   At least bzr, git and hg should benefit from this.
;;
Eric S. Raymond's avatar
Eric S. Raymond committed
625
;;;; Improved branch and tag handling:
626
;;
627 628
;; - Make sure the *vc-dir* buffer is updated after merge-branch operations.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
629
;; - add a generic mechanism for remembering the current branch names,
630
;;   display the branch name in the mode-line.  Replace
Dan Nicolaescu's avatar
Dan Nicolaescu committed
631 632
;;   vc-cvs-sticky-tag with that.
;;
633 634 635 636 637 638 639 640 641 642 643 644 645 646
;; - 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'
647
;;   unconditionally calls `log-view-current-file'.  This should be easy to
648 649 650 651 652 653 654 655 656 657
;;   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
658 659
;;;; Other
;;
660 661 662 663 664
;; - 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
665 666 667 668 669 670 671 672
;; - 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
673 674
;; - 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.
675
;;
676
;; - When vc-next-action calls vc-checkin it could pre-fill the
677
;;   *vc-log* buffer with some obvious items: the list of files that
678 679 680 681 682
;;   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...
;;
683
;; - most vc-dir backends need more work.  They might need to
684 685 686
;;   provide custom headers, use the `extra' field and deal with all
;;   possible VC states.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
687
;; - add a function that calls vc-dir to `find-directory-functions'.
688
;;
689
;; - vc-diff, vc-annotate, etc. need to deal better with unregistered
690
;;   files.  Now that unregistered and ignored files are shown in
691
;;   vc-dir, it is possible that these commands are called
692 693
;;   for unregistered/ignored files.
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
694 695 696
;; - 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
697
;;
Dan Nicolaescu's avatar
Dan Nicolaescu committed
698 699 700 701 702 703
;; - 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
704 705
;; - The backends should avoid using `vc-file-setprop' and `vc-file-getprop'.
;;
706
;;; Code:
707

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

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

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

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

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

;; General customization

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

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

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

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

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

785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804
(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")

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

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

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

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

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

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

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

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

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

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

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

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

910
(defun vc-backend-for-registration (file)
911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949
  "Return a backend that can be used for registering FILE.

If no backend declares itself responsible for FILE, then FILE
must not be in a version controlled directory, so try to create a
repository, prompting for the directory and the VC backend to
use."
  (catch 'found
    ;; First try: find a responsible backend, it must be a backend
    ;; under which FILE is not yet registered.
    (dolist (backend vc-handled-backends)
      (and (not (vc-call-backend backend 'registered file))
	   (vc-call-backend backend 'responsible-p file)
	   (throw 'found backend)))
    ;; no responsible backend
    (let* ((possible-backends
	    (let (pos)
	      (dolist (crt vc-handled-backends)
		(when (vc-find-backend-function crt 'create-repo)
		  (push crt pos)))
	      pos))
	   (bk
	    (intern
	     ;; Read the VC backend from the user, only
	     ;; complete with the backends that have the
	     ;; 'create-repo method.
	     (completing-read
	      (format "%s is not in a version controlled directory.\nUse VC backend: " file)
	      (mapcar 'symbol-name possible-backends) nil t)))
	   (repo-dir
	    (let ((def-dir (file-name-directory file)))
	      ;; read the directory where to create the
	      ;; repository, make sure it's a parent of
	      ;; file.
	      (read-file-name
	       (format "create %s repository in: " bk)
	       default-directory def-dir t nil
	       (lambda (arg)
		 (message "arg %s" arg)
		 (and (file-directory-p arg)
950
		      (string-prefix-p (expand-file-name arg) def-dir)))))))
951 952 953 954
	   (let ((default-directory repo-dir))
	(vc-call-backend bk 'create-repo))
      (throw 'found bk))))

955
;;;###autoload
956
(defun vc-responsible-backend (file)
957 958
  "Return the name of a backend system that is responsible for FILE.

959
If FILE is already registered, return the
960
backend of FILE.  If FILE is not registered, then the
961
first backend in `vc-handled-backends' that declares itself
962 963 964 965 966
responsible for FILE is returned.

Note that if FILE is a symbolic link, it will not be resolved --
the responsible backend system for the symbolic link itself will
be reported."
967
  (or (and (not (file-directory-p file)) (vc-backend file))
968 969 970 971
      (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)
972 973 974
	  (and (vc-call-backend backend 'responsible-p file)
	       (throw 'found backend))))
      (error "No VC backend is responsible for %s" file)))
975

976
(defun vc-expand-dirs (file-or-dir-list backend)
977
  "Expands directories in a file list specification.
978
Within directories, only files already under version control are noticed."
979 980
  (let ((flattened '()))
    (dolist (node file-or-dir-list)
981 982
      (when (file-directory-p node)
	(vc-file-tree-walk
983
	 node (lambda (f) (when (eq (vc-backend f) backend) (push f flattened)))))
984
      (unless (file-directory-p node) (push node flattened)))
985 986
    (nreverse flattened)))

Dan Nicolaescu's avatar
Dan Nicolaescu committed
987
(defvar vc-dir-backend)
988
(defvar log-view-vc-backend)
989
(defvar log-edit-vc-backend)
990 991 992 993 994
(defvar diff-vc-backend)

(defun vc-deduce-backend ()
  (cond ((derived-mode-p 'vc-dir-mode)   vc-dir-backend)
	((derived-mode-p 'log-view-mode) log-view-vc-backend)
995
	((derived-mode-p 'log-edit-mode) log-edit-vc-backend)
996
	((derived-mode-p 'diff-mode)     diff-vc-backend)
997 998
        ;; Maybe we could even use comint-mode rather than shell-mode?
	((derived-mode-p 'dired-mode 'shell-mode 'compilation-mode)
999
	 (ignore-errors (vc-responsible-backend default-directory)))
1000
	(vc-mode (vc-backend buffer-file-name))))
1001

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

1005 1006
(defun vc-deduce-fileset (&optional observer allow-unregistered
				    state-model-only-files)
1007
  "Deduce a set of files and a backend to which to apply an operation.
1008
Return (BACKEND FILESET FILESET-ONLY-FILES STATE CHECKOUT-MODEL).
1009

1010 1011
If we're in VC-dir mode, FILESET is the list of marked files,
or the directory if no files are marked.
1012 1013 1014 1015
Otherwise, if in a buffer visiting a version-controlled file,
FILESET is a single-file fileset containing that file.
Otherwise, if ALLOW-UNREGISTERED is non-nil and the visited file
is unregistered, FILESET is a single-file fileset containing it.
1016
Otherwise, throw an error.
1017 1018 1019 1020

STATE-MODEL-ONLY-FILES if non-nil, means that the caller needs
the FILESET-ONLY-FILES STATE and MODEL info.  Otherwise, that
part may be skipped.
1021 1022

BEWARE: this function may change the current buffer."
1023
  ;; FIXME: OBSERVER is unused.  The name is not intuitive and is not
1024
  ;; documented.  It's set to t when called from diff and print-log.
1025 1026 1027
  (let (backend)
    (cond
     ((derived-mode-p 'vc-dir-mode)
1028
      (vc-dir-deduce-fileset state-model-only-files))
1029 1030 1031 1032
     ((derived-mode-p 'dired-mode)
      (if observer
	  (vc-dired-deduce-fileset)
	(error "State changing VC operations not supported in `dired-mode'")))
1033
     ((setq backend (vc-backend buffer-file-name))
1034 1035 1036 1037 1038 1039
      (if state-model-only-files
	(list backend (list buffer-file-name)
	      (list buffer-file-name)
	      (vc-state buffer-file-name)
	      (vc-checkout-model backend buffer-file-name))
	(list backend (list buffer-file-name))))
1040 1041 1042
     ((and (buffer-live-p vc-parent-buffer)
           ;; FIXME: Why this test?  --Stef
           (or (buffer-file-name vc-parent-buffer)
1043
				(with-current-buffer vc-parent-buffer
1044
				  (derived-mode-p 'vc-dir-mode))))
1045
      (progn                  ;FIXME: Why not `with-current-buffer'? --Stef.
1046
	(set-buffer vc-parent-buffer)
1047
	(vc-deduce-fileset observer allow-unregistered state-model-only-files)))
1048 1049 1050
     ((and (derived-mode-p 'log-view-mode)
	   (setq backend (vc-responsible-backend default-directory)))
      (list backend nil))
1051 1052
     ((not buffer-file-name)
       (error "Buffer %s is not associated with a file" (buffer-name)))
1053
     ((and allow-unregistered (not (vc-registered buffer-file-name)))
1054
      (if state-model-only-files
1055
	  (list (vc-backend-for-registration (buffer-file-name))
1056 1057 1058 1059
		(list buffer-file-name)
		(list buffer-file-name)
		(when state-model-only-files 'unregistered