File: vc.el.html

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.

- async-checkins

  Takes no arguments. Backends that return non-nil can (and do)
  perform async checkins when vc-async-checkin is non-nil.

- working-revision-symbol

  Symbolic name for the/a working revision, a constant string. If
  defined, backend API functions that take revision numbers, revision
  hashes or branch names can also take this string in place of those.
  Emacs passes this name without first having to look up the working
  revision, which is a small performance improvement.
  In addition, using a name instead of a number or hash makes it
  easier to edit backend commands with vc-edit-next-command.

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.

- known-other-working-trees ()

  Return a list of all other working trees known to use the same
  backing repository as this working tree. The members of the list
  are the abbreviated (with abbreviate-file-name) absolute file
  names of the root directories of the other working trees.
  For some VCS, the known working trees will not be all the other
  working trees, because other working trees can share the same
  backing repository in a way that's transparent to the original
  working tree (Mercurial is like this).

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 any
  changes to the fileset. COMMENT is used as a check-in comment.
  If PATCH-STRING contains authorship and date information in a
  format commonly used with the backend, it should be used as the
  commit authorship identity and date; in particular, this should
  always occur if PATCH-STRING was generated by the backend's
  prepare-patch function (see below). Similarly, if COMMENT is nil
  and PATCH-STRING contains a log message, that log message should be
  used as the 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.

- revert-files (files)

  As revert, except that the first argument is a list of files, all
  of which require reversion, and reversion from version backups is
  not done. Backends can implement this for faster mass reverts.

- 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.

- get-change-comment (files rev)

  Return the change comments associated with the files at the given
  revision. The FILES argument it for forward-compatibility;
  existing implementations care only about REV.

- 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.

- add-working-tree (directory)

  Create a new working tree at DIRECTORY that uses the same backing
  repository as this working tree.
  What gets checked out in DIRECTORY is left to the backend because
  while some VCS can check out the same branch in multiple working
  trees (e.g. Mercurial), others allow each branch to be checked out
  in only one working tree (e.g. Git).
  If a new branch should be created then the backend should handle
  prompting for this, including prompting for a branch or tag from
  which to start/fork the new branch, like vc-create-branch.

- delete-working-tree (directory)

  Remove the working tree, assumed to be one that uses the same
  backing repository as this working tree, at DIRECTORY.
  Callers must ensure that DIRECTORY is not the current working tree.
  This removal should be unconditional with respect to the state of
  the working tree: the caller is responsible for checking for
  uncommitted work in DIRECTORY.

- move-working-tree (from to)

  Relocate the working tree, assumed to be one that uses the same
  backing repository as this working tree, at FROM to TO.
  Callers must ensure that FROM is not the current working tree.

- delete-revision (rev)

  Remove REV from the revision history of the current branch.
  For a distributed VCS, this means a rebase operation to rewrite the
  history of the current branch so that it no longer contains REV (or
  its changes). For a centralized VCS this may mean something
  different; for example CVS has true undos (not yet implemented in
  Emacs). A distributed VCS that implements this must also implement
  revision-published-p.

- delete-revisions-from-end (rev)

  Delete revisions from the revision history, from the end of the
  branch up to but not including REV, including removing the changes
  made by those revisions to the working tree. If there are
  uncommitted changes the implementation should discard them.

- uncommit-revisions-from-end (rev)

  Delete revisions from the revision history, from the end of the
  branch up to but not including REV, but without removing the
  changes made by those revisions from the working tree.
  I.e., the working tree contents should not change.

HISTORY FUNCTIONS

* print-log (files buffer &optional shortlog start-revision limit)

  Insert the revision log for FILES into BUFFER.
  If SHORTLOG is non-nil insert a short version of the log.
  If LIMIT is non-nil insert only insert LIMIT log entries.
  When LIMIT is a string it means stop right before that revision
  (i.e., revision LIMIT itself should not be included in the log).
  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.

- log-outgoing (buffer upstream-location) (DEPRECATED)

  Insert in BUFFER the revision log for the changes that will be
  sent when performing a push operation to UPSTREAM-LOCATION.
  Deprecated: implement incoming-revision and mergebase instead.

- log-incoming (buffer upstream-location) (DEPRECATED)

  Insert in BUFFER the revision log for the changes that will be
  received when performing a pull operation from UPSTREAM-LOCATION.
  Deprecated: implement incoming-revision and mergebase instead.

* incoming-revision (&optional upstream-location refresh)

  Return revision at the head of the branch at UPSTREAM-LOCATION.
  UPSTREAM-LOCATION defaults to where vc-update would pull from.
  If there is no such branch there, return nil. (Should signal an
  error, not return nil, in the case that fetching data fails.)
  For a distributed VCS, should also fetch that revision into local
  storage for operating on by subsequent calls into the backend.
  The backend may rely on cached information from a previous fetch
  from UPSTREAM-LOCATION unless REFRESH is non-nil, which means that
  the most up-to-date information possible is required.

- 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.

- revision-published-p (rev)

  For a distributed VCS, return whether REV is part of the public
  history of this branch, or only local history. I.e., whether REV
  has been pushed. Implementations should not consider whether REV
  is part of the public history of any other branches.
  It is an error if REV is not present on the current branch.
  Centralized VCS *must not* implement this, and there is no default
  implementation.

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 non-nil,
  NAME should be created as a branch and DIR should be checked out
  under this new branch. Where it makes sense with the underlying
  VCS, should prompt for a branch or tag from which to start/fork the
  new branch, with completion candidates including all the known
  branches and tags of the repository. 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/hash that precedes REV for FILE, or nil
  if no such revision exists. If the working-revision-symbol
  function is defined for this backend and that symbol, or a symbolic
  name involving that symbol, is passed to this function as REV, this
  function may return a symbolic name.
  The implementation should respect the value of vc-use-short-revision.

  Possible future extension: make REV an optional argument, and if
  nil, default it to FILE's working revision.

- 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.
  The implementation should respect the value of vc-use-short-revision.

- 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
  with the summary line (first line) of the patch message as a
  string; :buffer with a buffer object that contains the entire
  patch message; :body-start and :body-end demarcating the part
  of that buffer which should be inserted inline into a mail message
  body; and :patch-start and :patch-end demarcating the part of
  the buffer that is purely the patch, excluding any log message.
  If any of these *-start and *-end properties are omitted, they
  default to (point-min) and (point-max), respectively.
  If supported by the backend, the patch should contain authorship
  identity and date information, and REV's log message.

- 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.

- cherry-pick-comment (files rev reverse)

  Return a suitable log message for cherry-picking REV onto another
  branch. Typically this will be REV's original log message with
  something appended (e.g. Git's "(cherry picked from commit ...)").
  If REVERSE, return a suitable log message for a commit that undoes
  the effects of REV. FILES is for forward-compatibility; existing
  implementations ignore it.

Defined variables (35)

Defined functions (151)

Defined faces (0)