Miscellaneous Commands and Features of VC
-----------------------------------------

This section explains the less-frequently-used features of VC.

Change Logs and VC
..................

If you use RCS or CVS for a program with a ChangeLog file (see Change Log), you can generate change log entries from the version control log entries of previous commits.

Note that this only works with RCS or CVS.  This procedure would be particularly incorrect on a modern changeset-based version control system, where changes to the ChangeLog file would normally be committed as part of a changeset.  In that case, you should write the change log entries first, then pull them into the *vc-log* buffer when you commit (see Log Buffer).

C-x v a
     Visit the current directory's ChangeLog file and, for registered files in that directory, create new entries for versions committed since the most recent change log entry (vc-update-change-log).

C-u C-x v a
     As above, but only find entries for the current buffer's file.

For example, suppose the first line of ChangeLog is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to rcs2log on 1999-05-22 with log entry Ignore log messages that start with '#'..  Then C-x v a inserts this ChangeLog entry:

     1999-05-22  Nathaniel Bowditch  <nat@apn.org>

             * rcs2log: Ignore log messages that start with '#'.

If the version control log entry specifies a function name (in parenthesis at the beginning of a line), that is reflected in the ChangeLog entry.  For example, if a log entry for vc.el is (vc-do-command): Check call-process status., the ChangeLog entry is:

     1999-05-06  Nathaniel Bowditch  <nat@apn.org>

             * vc.el (vc-do-command): Check call-process status.

When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time.  If the log entries for several such files all have the same text, it coalesces them into a single entry.

Deleting and Renaming Version-Controlled Files
..............................................

C-x v x
     Prompt for a file name, delete the file from the working tree, and schedule the deletion for committing.

C-x v R
     Prompt for two file names, OLD and NEW, rename them in the working tree, and schedule the renaming for committing.  The OLD file defaults to the current buffer's file name if it is under VC.

If you wish to delete a version-controlled file, type C-x v x (vc-delete-file).  This prompts for the file name, and deletes it via the version control system.  The file is removed from the working tree, and in the VC Directory buffer (see VC Directory Mode), it is displayed with the removed status.  When you commit it, the deletion takes effect in the repository.

To rename a version-controlled file, type C-x v R (vc-rename-file).  This prompts for two arguments: the name of the file you wish to rename, and the new name; then it performs the renaming via the version control system.  The renaming takes effect immediately in the working tree, and takes effect in the repository when you commit the renamed file.

On modern version control systems that have built-in support for renaming, the renamed file retains the full change history of the original file.  On CVS and older version control systems, the vc-rename-file command actually works by creating a copy of the old file under the new name, registering it, and deleting the old file.  In this case, the change history is not preserved.

Revision Tags
.............

Most version control systems allow you to apply a revision tag to a specific version of a version-controlled tree.  On modern changeset-based version control systems, a revision tag is simply a symbolic name for a particular revision.  On older file-based systems like CVS, each tag is added to the entire set of version-controlled files, allowing them to be handled as a unit.  Revision tags are commonly used to identify releases that are distributed to users.

There are two basic commands for tags; one makes a tag with a given name, the other retrieves a named tag.

C-x v s NAME RET
     Define the working revision of every registered file in or under the current directory as a tag named NAME (vc-create-tag).

C-x v r NAME RET
     For all registered files at or below the current directory level, retrieve the tagged revision NAME.  This command will switch to a branch if NAME is a branch name and your VCS distinguishes branches from tags.  (vc-retrieve-tag).

     This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress.

You can give a tag or branch name as an argument to C-x v = or C-x v ~ (see Old Revisions). Thus, you can use it to compare a tagged version against the current files, or two tagged versions against each other.

On SCCS, VC implements tags itself; these tags are visible only through VC.  Most later systems (including CVS, Subversion, bzr, git, and hg) have a native tag facility, and VC uses it where available; those tags will be visible even when you bypass VC.

In file-based version control systems, when you rename a registered file you need to rename its master along with it; the command C-x v R (vc-rename-file) will do this automatically (see VC Delete/Rename). If you are using SCCS, you must also update the records of the tag, to mention the file by its new name (C-x v R does this, too).  An old tag that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it.  It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the tags by hand.  Using C-x v R makes the tag remain valid for retrieval, but it does not solve all problems.  For example, some of the files in your program probably refer to others by name.  At the very least, the makefile probably mentions the file that you renamed.  If you retrieve an old tag, the renamed file is retrieved under its new name, which is not the name that the makefile expects.  So the program won't really work as retrieved.

Merge Bases
...........

C-x v M D
     Report diffs of changes on a branch since it diverged from another (vc-diff-mergebase).

C-x v M L
     Display log messages for revisions on a branch since it diverged from another (vc-log-mergebase).

The merge base of two branches is the most recent revision that exists on both branches.  If neither of the branches was ever merged into the other (see Merging), then the merge base is the revision that the older of the two branches was at when the newer branch was created from it (see Creating Branches).  If one of the branches was ever merged into the other, then the merge base is the most recent merge point.

The commands described in this section are currently implemented only for decentralized version control systems (see VCS Repositories).

Merge bases are useful to make certain comparisons between branches, and Emacs provides two commands for doing so.  Each of C-x v M D (vc-diff-mergebase) and C-x v M L (vc-log-mergebase) prompts for two branches, finds their merge base, and then compares that merge base with the second of the two branches.  The commands report diffs and display change history, respectively.

The typical use case for these commands is when one of the branches was originally created from the other and you or a collaborator have made merges of one of the branches into the other at least once.  Then you can use these commands to see what changes on one branch have not yet been merged into the other.

Call the branch which has the changes you are interested in the ``source branch'' and the branch into which these changes have not yet been merged the ``target branch''.  Specify the target branch when prompted for the ``older revision'' and the source branch when prompted for the ``newer revision''. (The concept of merge bases generalizes from branches to any two revisions.  The merge base of two revisions is the most recent revision that can be found in the revision history of both of the two revisions.  C-x v M D and C-x v M L accept any two revisions, not just branches.  Comparing two branches is the same as comparing the revisions at the ends of the branches.

(In fact the concept generalizes to any number of revisions, but Emacs's commands for merge bases work with only two, so we limit ourselves to that.))  Then C-x v M D shows you a preview of what would change on the target branch if you were to merge the source branch into it, and C-x v M L shows you a log of the changes on the source branch not yet merged into the target branch.

Commands to see all unintegrated changes
........................................

C-x v T =
     Display diffs of changes to the VC fileset since the merge base of this branch and its upstream counterpart (vc-diff-unintegrated).

C-x v T D
     Display a diff of all changes since the merge base of this branch and its upstream counterpart (vc-root-diff-unintegrated).

C-x v T l
     Display log messages for changes to the VC fileset since the merge base of this branch and its upstream counterpart (vc-log-unintegrated).

C-x v T L
     Display log messages for all changes since the merge base of this branch and its upstream counterpart (vc-root-log-unintegrated).

C-x v T R =
     Display diffs of remote changes to the VC fileset since the merge base of this topic branch and its upstream counterpart (vc-diff-remote-unintegrated).

C-x v T R D
     Display a diff of all remote changes since the merge base of this topic branch and its upstream counterpart (vc-root-diff-remote-unintegrated).

C-x v T R l
     Display log messages for remote changes to the VC fileset since the merge base of this topic branch and its upstream counterpart (vc-log-remote-unintegrated).

C-x v T R L
     Display log messages for all remote changes since the merge base of this topic branch and its upstream counterpart (vc-root-log-remote-unintegrated).

For decentralized version control systems (see VCS Repositories), these commands provide specialized versions of C-x v M L and C-x v M D (see Merge Bases) which also take into account the state of upstream repositories.  These commands are useful both when working on a single branch and when developing features on a separate branch (see Branches).  These two cases are conceptually distinct, and so we will introduce them separately.

First, consider working on a single branch.  Unintegrated changes are those which you haven't yet pushed upstream.  This includes both unpushed commits and uncommitted changes in your working tree.  In many cases the reason these changes are not pushed yet is that they are not finished: the changes committed so far don't make sense in isolation.

Type C-x v T D (vc-root-diff-unintegrated) to display a summary of all these changes, committed and uncommitted.  This summary is in the form of a diff of what committing and pushing (see Pulling / Pushing) all these changes would do to the upstream repository.  You can use C-x v T = (vc-diff-unintegrated) instead to limit the display of changes to the current VC fileset.  (The difference between C-x v T D and C-x v T = is like the difference between C-x v D and C-x v = (see Old Revisions).) (Another point of comparison is that these commands are like C-x v O = (vc-fileset-diff-outgoing) and C-x v O D (vc-root-diff-outgoing) except that they include uncommitted changes in the reported diffs.  Like those other commands, you can use a prefix argument to specify a particular upstream location.)

Type C-x v T L (vc-root-log-unintegrated) to display a summary of the same changes in the form of a revision log; this does not include uncommitted changes.  You can use C-x v T l (vc-log-unintegrated) instead to limit the display of changes to the current VC fileset.

Second, consider developing a feature on a separate branch.  Call this the topic branch, (What we mean by a topic branch is any shorter-lived branch used for work which will later be merged into a longer-lived branch.  Topic branches are sometimes called ``feature branches''.  It is also common for the term ``feature branch'' to be reserved for a particular kind of topic branch, one that another branch or other branches are repeatedly merged into.) and call the branch from which the topic branch was originally created the trunk or development trunk.

In this case, unintegrated changes is a more specific notion than just unpushed and uncommitted changes on the topic branch.  You're not finished sharing changes with your collaborators until they have been merged into the trunk, and pushed.  Therefore, in this example, unintegrated changes are those which haven't yet been included in the upstream repository's development trunk.  That means committed changes on the topic branch that haven't yet been merged into the trunk, plus uncommitted changes.

When the current branch is a topic branch and you type C-x v T D, Emacs displays a summary of all the changes that are outstanding against the trunk to which the current branch will be merged.  This summary is in the form of a diff of what committing and pushing all the changes, and subsequently merging the topic branch, would do to the trunk. As above, you can use C-x v T = instead to limit the display of changes to the current VC fileset.  C-x v T L and C-x v T l show the corresponding revision logs, excluding uncommitted changes as above.

On topic branches, it is sometimes also useful to see the same information but for the remote repository's version of the topic branch. This is the outstanding work on the topic branch that has been pushed, but not yet merged.  It is visible to your collaborators but is otherwise still unintegrated.  We call such work remote unintegrated changes.  There is a command corresponding to each of the four commands discussed so far but which operates on the remote repository's version of the current topic branch: C-x v R T = (vc-diff-remote-unintegrated), C-x v R T D (vc-root-diff-remote-unintegrated), C-x v R T l (vc-log-remote-unintegrated), and C-x v R T L (vc-root-log-remote-unintegrated).

All this functionality relies on Emacs correctly detecting whether the current branch is a trunk or a topic branch, and in the latter case, correctly determining the branch to which the topic branch will eventually be merged.  If the autodetection doesn't produce the right results, there are several options to tweak and override it.

The variables vc-trunk-branch-regexps and vc-topic-branch-regexps contain lists of regular expressions matching the names of branches that should always be considered trunk and topic branches, respectively.  You can also specify prefix arguments to C-x v T ....  Here is a summary of how to use these controls:

 1. If the problem is that Emacs thinks your topic branch is a trunk, you can add either its name, or a regular expression matching its name (see Regexps), to the vc-topic-branch-regexps variable. There are a few special kinds of value to simplify common use cases:

       * If an element contains no characters that are special in regular expressions, then the regular expression is implictly anchored at both ends, i.e., it matches only a branch with exactly that name.

       * If the first element of vc-topic-branch-regexps is the symbol not, then the meaning of vc-topic-branch-regexps is inverted, in that Emacs treats all branches whose names don't match any element of vc-topic-branch-regexps to be topic branches.

       * If instead of a list of regular expressions the vc-topic-branch-regexps variable has the special value t, then Emacs treats as a topic branch any branch that the vc-trunk-branch-regexps variable doesn't positively identify as a trunk.

     See Directory Variables, regarding how to specify values of vc-topic-branch-regexps and vc-trunk-branch-regexps for a single VC repository.

 2. If the problem is that Emacs thinks your trunk is a topic branch, you can add either its name, or a regular expression matching its name, to the vc-trunk-branch-regexps variable.  This works just like vc-topic-branch-regexps with the same special values we just described.  E.g., if the value of vc-trunk-branch-regexps is t, Emacs treats as a trunk any branch that the vc-topic-branch-regexps variable doesn't identify as a topic branch.

 3. Supply a double prefix argument, i.e. C-u C-u C-x v T ..., and Emacs will treat the current branch as a trunk, no matter what. This is useful when you simply want to obtain a diff of all outgoing changes (see VC Change Log) plus uncommitted changes.

 4. Finally, you can take full manual control by supplying a single prefix argument, i.e. C-u C-x v T ....  Emacs will prompt you for the outgoing base, which is the upstream location for which the changes are destined once they are no longer outstanding.

     To treat the current branch as a trunk specify a reference to the upstream version of the current branch, to which you and your collaborators push finished work.  To treat the current branch as a topic branch specify a reference to the upstream version of the trunk to which the topic branch will later be merged.

     Exactly how to specify a reference to the upstream version of a branch depends on the version control system in use.  For example, with Git, to refer to the upstream version of a branch FOO, you would supply origin/FOO.  So if FOO is the current branch then you would enter an outgoing base of origin/FOO to treat FOO as a trunk, or an outgoing base of origin/BAR to treat FOO as a topic branch which will later be merged into a trunk named BAR.

     If there is a default option, it is what Emacs thinks you need to enter in order to treat the current branch as a topic branch.  If there is no default, then entering nothing at the prompt means to treat the current branch as a trunk.

Multiple Working Trees for One Repository
.........................................

Some VCS support more than one working tree with the same backing repository or revisions store.  This means that you can have different revisions or branches (see Branches) checked out simultaneously, in different working trees, but with all revision history, branches, tags and other metadata shared.

Suppose your project has a trunk where you're developing the new version 3 of your software, and a stable release branch from which you make point releases of version 2.  Someone sends you a patch fixing a bug that's present in version 2.  Your main working tree has version 3 checked out, and you're in the middle of a big refactor that you don't want to disturb.  So you type C-x v w c (see below) and create a new working tree, following the prompts to check out the version 2 branch there.

You apply the patch to that working tree using C-x v w a (see below), build and test it.  Satisfied, you use C-x v P (see Pulling / Pushing) in the other working tree.  In the course of testing the patch, you've realized that the bug exists in version 3 of the software, too.  So you switch back to your first working tree, and use C-x v m (see Merging) to merge the branch you have checked out in the other working tree.  Now your version of the trunk has all of version 2's fixes merged into it, but you haven't pushed it yet because you're still refactoring.  You'll use C-x v P later.

Ordinary VC commands like C-x v v (see Basic VC Editing) and C-x v d (see VC Directory Mode) don't work any differently when there exist other working trees, except that the commits, branches and other VC artifacts they create will be visible from all working trees.  Another way to put this is that any action taken in any working tree which creates new artifacts in the VCS backing store will be visible from other working trees, but actions which only affect workfiles won't be.  So if you apply a patch to some workfiles in one working tree, that only affects that working tree.  But if you commit the changes made by applying the patch, then that creates a new revision in the backing store, and so this action affects other working trees in the sense that their view of the repository's history will now have an additional commit in it.

The following special commands let you switch between and modify different working trees.  It is an error to use them other than from within a VC working tree; that is, from a buffer visiting a VCS-controlled file, or otherwise from a buffer whose default-directory (see File Names) is within a VC working tree.

C-x v w c
     Add a new working tree.

C-x v w w
     Visit this file or directory in another working tree.

C-x v w k
     Kill buffers visiting this file in other working trees.

C-x v w s
     Invoke C-x p p (project-switch-project) but limited to other working trees.

C-x v w a
     Copy or move fileset changes to another working tree.

C-x v w A
     Copy or move all changes to another working tree.

C-x v w x
     Delete a working tree you no longer need.

C-x v w R
     Relocate a working tree to another file name.

You can start using multiple working trees by using the command C-x v w c (vc-add-working-tree) to create a new working tree.  This prompts you to specify a destination directory, which identifies the working tree, and which will hold the new set of workfiles.

Different VCS have different rules about what may and must be checked out in other working trees, so there may be additional prompts depending on the VCS in use.  For example, Git requires that each branch be checked out in only one working tree at a time, so when using Git, Emacs will also prompt you for the name of the branch to be checked out in the new working tree.

Once your repository has other working trees, you can use the command C-x v w w (vc-switch-working-tree) to switch between them. It tries to find the analogue of the current buffer's file or directory under another working tree.  Typically the sets of workfiles under different working trees differ more in file contents than in which files do and do not exist.  In other words, the file or directory the current buffer visits probably exists in other working trees too, and this command lets you switch to those versions of the file.

C-x v w w also works in Diff mode (see Diff Mode) and Log View mode (see VC Change Log).  Instead of switching to a different buffer, the command changes the default directory of the buffer to the corresponding directory under another working tree.  This is particularly useful from Log View mode buffers generated by commands like C-x v L (see VC Change Log).  After using C-x v w w to change the default directory of the Log View buffer, you can move point to a revision of interest and type = (log-view-diff) to open a Diff mode buffer with that revision's changes.  Then you can use standard Diff mode commands like C-c C-a (diff-apply-hunk) to apply hunks to the other working tree.

After using C-x v w w in file-visiting buffers you will have multiple buffers visiting identically named files (see Uniquify). You can kill all but one of these buffers by typing C-x v w k (vc-kill-other-working-tree-buffers).  This command kills buffers visiting versions of the current buffer's file in other working trees, preserving the current buffer.  It does not work in non-file-visiting buffers.

An alternative way to switch between working trees is C-x v w s (vc-working-tree-switch-project).  This prompts you to select a working tree, and then displays a menu of commands to operate on it. This is in fact just C-x p p (project-switch-project) (see Switching Projects) but with the selection of projects limited to other working trees.  The main difference between C-x v w w and C-x v w s is that the former looks for an analogue of the current buffer in the other working tree while the latter considers the other working tree as a whole, independent project.

The command C-x v w a (vc-apply-to-other-working-tree) prompts you to select another working tree, then copies changes from the current working tree to that other working tree.  With a prefix argument, it moves changes instead of just copying them.  Usually the command operates on local (uncommitted) changes to the current VC fileset.  When invoked in a buffer under Diff mode (see Diff Mode), it operates on the changes specified by the contents of that buffer.  The command stops and does nothing if any of the changes don't apply to the target working tree.

C-x v w a is useful to copy changes to a temporary working tree in order to test them.  It is also useful to copy fixes back to your main working tree for checking in.  For example, you might hack away at a bug in a temporary working tree, and fix it.  You'd then want to copy or move the fix back to your main working tree to check it in and push it.

The command C-x v w A works similarly, except that it always copies or moves all local changes to the whole working tree, not just changes to the current VC fileset or changes represented by the contents of a Diff mode buffer.  With two prefix arguments, this command shows a preview of changes to be copied, leaving you to apply them using standard Diff mode commands like C-c C-a and C-c <RET> a (see Diff Mode).  (C-u C-u C-x v w A is roughly equivalent to typing C-x v D followed by C-x v w w.)

The commands C-x v w x (vc-delete-working-tree) and C-x v w R (vc-move-working-tree) are for performing maintenance tasks on other working trees, letting you delete, move and rename them.  Deleting other working trees is particular useful because a common use for multiple working trees is to create throwaway copies of the repository to quickly test changes, without interfering with any work-in-progress you may have in your primary working trees.

Inserting Version Control Headers
.................................

On Subversion, CVS, RCS, and SCCS, you can put certain special strings called version headers into a work file.  When the file is committed, the version control system automatically puts the revision number, the name of the user who made the commit, and other relevant information into the version header.

VC does not normally use the information in the version headers.  As an exception, when using RCS, Emacs uses the version header, if there is one, to determine the file version, since it is often more reliable than the RCS master file.  To inhibit using the version header this way, change the variable vc-consult-headers to nil.  VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

To insert a suitable header string into the current buffer, use the command M-x vc-insert-headers.  This command works only on Subversion, CVS, RCS, and SCCS.  The variable vc-BACKEND-header contains the list of keywords to insert into the version header; for instance, CVS uses vc-cvs-header, whose default value is '("\$Id\$") (see Keyword substitution (CVS--Concurrent Versions System)).  (The extra backslashes prevent the string constant from being interpreted as a header, if the Emacs Lisp file defining it is maintained with version control.)  The vc-insert-headers command inserts each keyword in the list on a new line at point, surrounded by tabs, and inside comment delimiters if necessary.

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer.  Its value should be a list of elements of the form (REGEXP . FORMAT).  Whenever REGEXP matches the buffer name, FORMAT is also inserted as part of the version header.  A %s in FORMAT is replaced with the file's version control type.

Editing VC Commands
...................

You can use the C-x v ! (vc-edit-next-command) prefix command to edit the shell command line that VC is about to run.  This is primarily intended to make it possible to add optional command-line arguments to VCS commands without unnecessary complications of the VC command set and its interfaces with the backend.

For example, Git can produce logs of more than one branch, but C-x v b L (vc-print-root-branch-log) prompts for the name of just one branch.  To obtain a log of more than one branch, you can type C-x v ! C-x v b L and then append the names of additional branches to the end of the git log command that VC is about to run.

Preparing Patches
.................

When collaborating on projects it is common to send patches via email, to share changes.  You can do this using VC with the vc-prepare-patch command.  This will prompt you for the revisions you wish to share, and which destination email address(es) to use.  Separate the revisions using the value of CRM-SEPARATOR, commas by default.  The command will then prepare those revisions using your MUA (Mail User Agent) for you to review and send.

When invoked interactively in a Log View buffer with marked revisions, those marked revisions will be used.

Depending on the value of the user option vc-prepare-patches-separately, vc-prepare-patch will generate one or more messages.  The default value t means prepare and display a message for each revision, one after another.  A value of nil means to generate a single message with all patches attached in the body.

If you expect to contribute patches on a regular basis, you can set the user option vc-default-patch-addressee to the address(es) you wish to use.  This will be used as the default value when invoking vc-prepare-patch.  Project maintainers may consider setting this as a directory local variable (see Directory Variables).

Auto-Reverting Buffers That Visit Tracked Files
...............................................

When Emacs executes VCS operations that it knows may change the contents of tracked files, it reverts buffers visiting those files (see Reverting).  It does this in a VCS-aware fashion that retains the positions of point and the mark even when the VCS operation causes VCS keywords to be expanded (see Version Headers).

An important limitation of this feature is that Emacs won't know to revert buffers when you execute additional VCS operations outside of Emacs, such as at a shell prompt, or by means of scripts.  If you regularly do this, and you don't use a VCS with keyword expansion (all modern VCS, absent special configuration), you may wish to enable vc-auto-revert-mode instead, by customizing that variable to a non-nil value.

This mode is just like global-auto-revert-mode (see Auto Revert) except limited to files visiting VCS-tracked files.  It ensures that Emacs will always revert buffers when VCS operations change their contents, regardless of whether Emacs initiated those operations.

See VC Mode Line, for details regarding Auto Revert mode in buffers visiting tracked files (which is what vc-auto-revert-mode enables).

Rewinding Branches
..................

M-x vc-delete-revisions-from-end
     Delete revisions from the end of the current branch.

M-x vc-uncommit-revisions-from-end
     Delete revisions from the end of the current branch without touching the working tree.

For decentralized version control systems (see VCS Repositories), these commands provide ways to move the current branch back to an earlier revision.  vc-delete-revisions-from-end prompts for a revision, then removes all revisions from the end of the branch up to but not including the specified revision.  We say that the branch is rewound back to the specified revision.

This command removes the changes made by the revisions from the working tree.  Therefore, if there are any uncommitted changes, they must be reverted, first (see VC Undo).  This command will prompt you to do that if necessary.  If you supply a prefix argument, Emacs will delete uncommitted changes without prompting.

To ``uncommit'' a revision means to remove it from the revision history without removing its changes from the working tree.  It is as though you had made the changes but had not yet checked them in.  The command vc-uncommit-revisions-from-end prompts for a revision, and then uncommits all revisions from the end of the branch up to but not including the specified revision.  The branch is rewound back to the specified revision but the changes are left behind in the working tree.

When rewinding the current branch, if all the revisions deleted from the revision history are among those you have pulled or pushed, then these operations do not permanently delete anything: a simple C-x v + (see Pulling / Pushing) will bring the revisions back.  On the other hand, if there are new revisions on the end of the branch that have not yet been pushed, then these commands will delete them permanently.  Emacs tries to detect this situation and ask you if you are sure you want to delete them.

Alternative ways to access this functionality are the log-view-uncommit-revisions-from-end and log-view-delete-revisions-from-end commands, bound to x and X, respectively, in Log View mode buffers (see VC Change Log). Compared to using the commands described here directly, the Log View mode commands can make it easier to be sure you are rewinding back to the revision you intend.

Customizing VC
--------------

The variable vc-handled-backends determines which version control systems VC should handle.  The default value is (RCS CVS SVN SCCS SRC Bzr Git Hg), so it contains all the version systems that are currently supported.  If you want VC to ignore one or more of these systems, exclude its name from the list.  To disable VC entirely, set this variable to nil.

The order of systems in the list is significant: when you visit a file registered in more than one system, VC uses the system that comes first in vc-handled-backends by default.  The order is also significant when you register a file for the first time (see Registering).

General Options
...............

Emacs normally does not save backup files for source files that are maintained with version control.  If you want to make backup files even for files that use version control, set the variable vc-make-backup-files to a non-nil value.

Editing a version-controlled file through a symbolic link may cause unexpected results, if you are unaware that the underlying file is version-controlled.  The variable vc-follow-symlinks controls what Emacs does if you try to visit a symbolic link pointing to a version-controlled file.  If the value is ask (the default), Emacs asks for confirmation.  If it is nil, Emacs just displays a warning message.  If it is t, Emacs automatically follows the link and visits the real file instead.

If vc-suppress-confirm is non-nil, then C-x v v and C-x v i can save the current buffer without asking, and C-x v u also operates without asking for confirmation.

VC mode does much of its work by running the shell commands for the appropriate version control system.  If vc-command-messages has the value log, VC logs messages to the *Messages* buffer to indicate which shell commands it runs, and logs additional messages when the commands finish.  If the variable has any other non-nil value, Emacs both logs and displays these messages.

VC mode runs certain shell commands asynchronously, allowing you to continue to use Emacs for other purposes while the command completes. This is mostly used for commands which access the network, such as pulling and pushing for distributed VCS (see Pulling / Pushing). When the command starts, VC displays a buffer into which the commands output will be written.  If vc-display-failed-async-commands is non-nil, VC will additionally ensure that this buffer is displayed when the command finishes running but failed.  This means you can freely close the window displaying the command's buffer and know that it'll pop up again in the case that running the command failed.

Normally checkin operations are done synchronously; that is, Emacs waits until the checkin has completed before doing anything else.  This can be inconvenient for repositories in which the checkin operation is slow, such as Git repositories where you check in changes to very large files, or Mercurial repositories with a very large number of files.

For those backends which support it, setting vc-async-checkin to non-nil switches to doing checkin operations asynchronously. This is particularly useful as a directory local variable in repositories where checkin operations are slow (see Directory Local Variables (GNU Emacs Lisp Reference Manual)).

While an asynchronous checkin operation is in progress, if you use C-x C-s to save a buffer visiting any file within the current VC tree, then the operation reverts to a synchronous checkin and Emacs waits for it to complete before saving the buffer.  This is to avoid nondeterminism regarding exactly what changes get checked in.

Options for RCS and SCCS
........................

By default, RCS uses locking to coordinate the activities of several users, but there is a mode called non-strict locking in which you can check-in changes without locking the file first.  Use rcs -U to switch to non-strict locking for a particular file, see the rcs manual page for details.

When deducing the version control state of an RCS file, VC first looks for an RCS version header string in the file (see Version Headers).  If there is no header string, VC normally looks at the file permissions of the work file; this is fast.  But there might be situations when the file permissions cannot be trusted.  In this case the master file has to be consulted, which is rather expensive.  Also the master file can only tell you if there's any lock on the file, but not whether your work file really contains that locked version.

You can tell VC not to use version headers to determine the file status by setting vc-consult-headers to nil.  VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

VC determines the version control state of files under SCCS much as with RCS.  It does not consider SCCS version headers, though.  Thus, the variable vc-consult-headers does not affect SCCS use.

Options specific for CVS
........................

You can specify additional command line options to pass to all CVS operations in the variable vc-cvs-global-switches.  These switches are inserted immediately after the cvs command, before the name of the operation to invoke.

When using a CVS repository on a remote machine, VC can try keeping network interactions to a minimum.  This is controlled by the variable vc-cvs-stay-local.  If vc-cvs-stay-local is only-file (the default), VC determines the version control status of each file using only the entry in the local CVS subdirectory and the information returned by previous CVS commands.  As a consequence, if you have modified a file and somebody else has checked in other changes, you will not be notified of the conflict until you try to commit.

If you change vc-cvs-stay-local to nil, VC queries the remote repository before it decides what to do in vc-next-action (C-x v v), just as it does for local repositories.

You can also set vc-cvs-stay-local to a regular expression that is matched against the repository host name; VC then stays local only for repositories from hosts that match the pattern.

When using a remote repository, Emacs normally makes automatic version backups of the original versions of each edited file.  These local backups are made whenever you save the first changes to a file, and they are removed after you commit your changes to the repository. (Note that these are not the same as ordinary Emacs backup files; see Backup.) Commands like C-x v = and C-x v u make use of automatic version backups, if possible, to avoid having to access the network.

Setting vc-cvs-stay-local to nil disables the making of automatic version backups.

Automatic version backups have names of the form FILE.~VERSION.~.  This is similar to the name that C-x v ~ saves old versions to (see Old Revisions), except for the additional dot (.) after the version.  The relevant VC commands can use both kinds of version backups.  The main difference is that the manual version backups made by C-x v ~ are not deleted automatically when you commit.

CVS does not use locking by default, but there are ways to enable locking-like behavior using its CVSREAD or watch feature; see the CVS documentation for details.  If that case, you can use C-x v v in Emacs to toggle locking, as you would for a locking-based version control system (see VC With A Locking VCS).