Homepage: https://www.gnu.org/software/emacs
Author: FSF (see below for full credits)
Drive a version-control system from within Emacs
This mode is fully documented in the Emacs user's manual.
Supported version-control systems presently include CVS, RCS, SRC,
GNU Subversion, Bzr, Git, Mercurial, Monotone and SCCS (or its free
replacement, CSSC).
If your site uses the ChangeLog convention supported by Emacs, the
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')
from the commit buffer instead or to set `log-edit-setup-invert'.
When using SCCS, RCS, CVS: be careful not to do repo surgery, or
operations like registrations and deletions and renames, outside VC
while VC is running. The support for these systems was designed
when disks were much slower, and the code maintains a lot of
internal state in order to reduce expensive operations to a
minimum. Thus, if you mess with the repo while VC's back is turned,
VC may get seriously confused.
When using Subversion or a later system, anything you do outside VC
*through the VCS tools* should safely interlock with VC
operations. Under these VC does little state caching, because local
operations are assumed to be fast.
The 'assumed to be fast' category includes SRC, even though it's
a wrapper around RCS.
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,
`vc-sys-working-revision' should compute the working revision and
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
value that the generic code might want to set (check for uses of
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 (`-').
BACKEND PROPERTIES
* revision-granularity
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
- update-on-retrieve-tag
Takes no arguments. Backends that return non-nil can update
buffers on `vc-retrieve-tag' based on user input. In this case
user will be prompted to update buffers on `vc-retrieve-tag'.
STATE-QUERYING FUNCTIONS
* registered (file)
Return non-nil if FILE is registered in this backend. Both this
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).
* state (file)
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.
- dir-status-files (dir files update-function)
Produce RESULT: a list of lists of the form (FILE VC-STATE EXTRA)
for FILES in DIR. If FILES is nil, report on all files in DIR.
(It is OK, though possibly inefficient, to ignore the FILES argument
and always report on all files in DIR.)
If FILES is non-nil, this function should report on all requested
files, including up-to-date or ignored files.
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 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.
To provide more backend specific functionality for `vc-dir'
the following functions might be needed: `dir-extra-headers',
`dir-printer', and `extra-dir-menu'.
- dir-extra-headers (dir)
Return a string that will be added to the *vc-dir* buffer header.
- dir-printer (fileinfo)
Pretty print the `vc-dir-fileinfo' FILEINFO.
If a backend needs to show more information than the default FILE
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.
- status-fileinfo-extra (file)
Compute `vc-dir-fileinfo->extra' for FILE.
* working-revision (file)
Return the working revision of FILE. This is the revision fetched
by the last checkout or update, not necessarily the same thing as the
head or tip revision. Should return "0" for a file added but not yet
committed.
* checkout-model (files)
Indicate whether FILES need to be "checked out" before they can be
edited. See `vc-checkout-model' for a list of possible values.
- mode-line-string (file)
If provided, this function should return the VC-specific mode
line string for FILE. The returned string should have a
`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.
STATE-CHANGING FUNCTIONS
* create-repo ()
Create an empty repository in the current directory and initialize
it so VC mode can add files to it. For file-oriented systems, this
need do no more than create a subdirectory with the right name.
* register (files &optional comment)
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.)
- responsible-p (file)
Return the directory 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.
- receive-file (file rev)
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.
* checkin (files comment &optional rev)
Commit changes in FILES to this backend. COMMENT is used as a
check-in comment. The implementation should pass the value of
vc-checkin-switches to the backend command. The optional REV
revision argument is only supported with some older VCSes, like
RCS and CVS, and is otherwise silently ignored.
- checkin-patch (patch-string comment)
Commit a single patch PATCH-STRING to this backend, bypassing
the changes in filesets. COMMENT is used as a check-in comment.
* find-revision (file rev buffer)
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.
* checkout (file &optional rev)
Check out revision REV of FILE into the working area. FILE
should be writable by the user and if locking is used for FILE, a
lock should also be set. If REV is non-nil, that is the revision
to check out (default is the working revision). If REV is t,
that means to check out the head of the current branch; if it is
the empty string, check out the head of the trunk. The
implementation should pass the value of vc-checkout-switches to
the backend command. The 'editable' argument of older VC versions
is gone; all files are checked out editable.
* revert (file &optional contents-done)
Revert FILE back to the working revision. If optional
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.
If FILE is in the `added' state it should be returned to the
`unregistered' state.
- merge-file (file &optional rev1 rev2)
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.
- merge-branch ()
Merge another branch into the current one, prompting for a
location to merge from.
- merge-news (file)
Merge recent changes from the current branch into FILE.
(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.
- steal-lock (file &optional revision)
Steal any lock on the working revision of FILE, or on REVISION if
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.
- modify-change-comment (files rev comment)
Modify the change comments associated with the files at the
given revision. This is optional, many backends do not support it.
- mark-resolved (files)
Mark conflicts as resolved. Some VC systems need to run a
command to mark conflicts as resolved.
- find-admin-dir (file)
Return the administrative directory of FILE.
HISTORY FUNCTIONS
* print-log (files buffer &optional shortlog start-revision limit)
Insert the revision log for FILES into BUFFER.
If SHORTLOG is true insert a short version of the log.
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'.
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).
* log-outgoing (buffer 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 (buffer remote-location)
Insert in BUFFER the revision log for the changes that will be
received when performing a pull operation from REMOTE-LOCATION.
- log-search (buffer pattern)
Search for PATTERN in the revision log and output results into BUFFER.
- 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'.
- show-log-entry (revision)
If provided, search the log entry for REVISION in the current buffer,
and make sure it is displayed in the buffer's window. The default
implementation of this function works for RCS-style logs.
- comment-history (file)
Return a string containing all log entries that were made for FILE.
This is used for transferring a file from one backend to another,
retaining comment information.
- update-changelog (files)
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.
* diff (files &optional rev1 rev2 buffer async)
Insert the diff for FILE into BUFFER, or the *vc-diff* buffer if
BUFFER is nil. If ASYNC is non-nil, run asynchronously. If REV1
and REV2 are non-nil, report differences 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 as well;
otherwise, diff against an empty tree. 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).
- revision-completion-table (files)
Return a completion table for existing revisions of FILES.
The default is to not use any completion table.
- annotate-command (file buf &optional rev)
If this function is provided, it should produce an annotated display
of FILE in BUF, relative to revision REV. Annotation means each line
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.
- annotate-time ()
Only required if `annotate-command' is defined for the backend.
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'
to this format. Return nil if no more lines of annotation appear
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
relevant backend. This function also affects how much of the line
is fontified; where it leaves point is where fontification begins.
- 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
(vc-annotate-convert-time (current-time)) -- i.e. the current
time with hours, minutes, and seconds included. Probably safe to
ignore. Return the current time, in units of fractional days.
- 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.
If the backend supports annotating through copies and renames,
and displays a file name and a revision, then return a cons
(REVISION . FILENAME).
- 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'.
- mergebase (rev1 &optional rev2)
Return the common ancestor between REV1 and REV2 revisions.
- last-change (file line)
Return the most recent revision of FILE that made a change
on LINE.
TAG/BRANCH SYSTEM
- create-tag (dir name branchp)
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.
- retrieve-tag (dir name update)
Retrieve the version tagged by NAME of all registered files at or below DIR.
If NAME is a branch name, switch to that branch.
If UPDATE is non-nil, then update buffers of any files in the
tag/branch that are currently visited. The default implementation
does a sanity check whether there aren't any uncommitted changes at
or below DIR, and then performs a tree walk, using the `checkout'
function to retrieve the corresponding revisions.
MISCELLANEOUS
- make-version-backups-p (file)
Return non-nil if unmodified repository revisions of FILE should be
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.
- root (file)
Return the root of the VC controlled hierarchy for file.
- ignore (file &optional directory remove)
Ignore FILE under DIRECTORY (default is 'default-directory').
FILE is a file wildcard relative to DIRECTORY.
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.
The default behavior is to add or remove a line from the file
returned by the `find-ignore-file' function.
- ignore-completion-table (directory)
Return the completion table for files ignored by the current
version control system, e.g., the entries in `.gitignore' and
`.bzrignore'. The default behavior is to read the contents of
the file returned by the `find-ignore-file' function.
- find-ignore-file (file)
Return the ignore file that controls FILE, e.g. `.gitignore' or
`.bzrignore'.
- previous-revision (file rev)
Return the revision number that precedes REV for FILE, or nil if no such
revision exists.
- file-name-changes (rev)
Return the list of pairs with changes in file names in REV. When
a file was added, it should be a cons with nil car. When
deleted, a cons with nil cdr. When copied or renamed, a cons
with the source name as car and destination name as cdr.
- next-revision (file rev)
Return the revision number that follows REV for FILE, or nil if no such
revision exists.
- 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'.
- check-headers ()
Return non-nil if the current buffer contains any version headers.
- 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.
- rename-file (old new)
Rename file OLD to NEW, both in the working area and in the
repository. If this function is not provided, the renaming
will be done by (vc-delete-file old) and (vc-register new).
- find-file-hook ()
Operation called in current buffer when opening a file. This can
be used by the backend to setup some local variables it might need.
- 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.
- extra-dir-menu ()
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.
- 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?
- repository-url (file-or-dir &optional remote-name)
Returns the URL of the repository of the current checkout
containing FILE-OR-DIR. The optional REMOTE-NAME specifies the
remote (in Git parlance) whose URL is to be returned. It has
only a meaning for distributed VCS and is ignored otherwise.
- prepare-patch (rev)
Prepare a patch and return a property list with the keys
`:subject' indicating the patch message as a string, `:buffer'
with a buffer object that contains the entire patch message and
`:body-start' and `:body-end' demarcating what part of said
buffer should be inserted into an inline patch. If the two last
properties are omitted, `point-min' and `point-max' will
respectively be used instead.
- clone (remote directory rev)
Attempt to clone a REMOTE repository, into a local DIRECTORY.
Returns a string with the directory with the contents of the
repository if successful, otherwise nil. With a non-nil value
for REV the backend will attempt to check out a specific
revision, if possible without first checking out the default
branch.