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.

Renaming VC Work Files and Master Files
.......................................

M-x vc-rename-file
     Prompt for two file names, VAR and OLD, and rename them in the version-controlled working tree.

If you wish to rename a registered file in a version-controlled working tree, use the command M-x vc-rename-file.  This prompts for two arguments: the file you wish to rename, followed by the new name; then it performs the renaming through the version control system.

On modern version control systems that have built-in support for renaming, the renaming operation takes effect immediately in the working tree, and takes effect in the repository when you commit the renamed file.  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 a file-oriented VCS, when you rename a registered file you need to rename its master along with it; the command vc-rename-file will do this automatically.  If you are using SCCS, you must also update the records of the tag, to mention the file by its new name (vc-rename-file 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 vc-rename-file 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.

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

Sometimes it is convenient to put version identification strings directly into working files.  Certain special strings called version headers are replaced in each successive version by the number of that version, the name of the user who created it, and other relevant information.  All of the back ends that VC supports have such a mechanism, except GNU Arch.

VC does not normally use the information contained in these headers. The exception is RCS---with RCS, version headers are sometimes more reliable than the master file to determine which version of the file you are editing.

Searching for RCS version headers is controlled by the variable vc-consult-headers.  If it is non-nil (the default), Emacs searches for headers to determine the version number you are editing.  Setting it to nil disables this feature.

Note that although CVS uses the same kind of version headers as RCS does, VC never searches for these headers if you are using CVS, regardless of the above setting.

You can use the C-x v h command (vc-insert-headers) to insert a suitable header string.

C-x v h
     Insert headers in a file for use with your version-control system.

The default header string is $Id$ for RCS and %W% for SCCS.  You can specify other headers to insert by setting the variables vc-BACKEND-header where BACKEND is rcs or sccs.

Instead of a single string, you can specify a list of strings; then each string in the list is inserted as a separate header on a line of its own.

It may be necessary to use apparently-superfluous backslashes when writing the strings that you put in this variable.  For instance, you might write "$Id\$" rather than "$Id$".  The extra backslash prevents the string constant from being interpreted as a header, if the Emacs Lisp file containing it is maintained with version control.

Each header is inserted surrounded by tabs, inside comment delimiters, on a new line at point.  Normally the ordinary comment start and comment end strings of the current mode are used, but for certain modes, there are special comment delimiters for this purpose; the variable vc-comment-alist specifies them.  Each element of this list has the form (MODE STARTER ENDER).

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 inserted as part of the header.  A header line is inserted for each element that matches the buffer name, and for each string specified by vc-BACKEND-header.  The header line is made by processing the string from vc-BACKEND-header with the format taken from the element.  The default value for vc-static-header-alist is as follows:

     (("\\.c$" .
       "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
     #endif /* lint */\n"))

It specifies insertion of text of this form:

     #ifndef lint
     static char vcid[] = "STRING";
     #endif /* lint */

Note that the text above starts with a blank line.

If you use more than one version header in a file, put them close together in the file.  The mechanism in revert-buffer that preserves markers may not handle markers positioned between two version headers.

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

The variable vc-handled-backends determines which version control systems VC should handle.  The default value is (RCS CVS SVN SCCS Bzr Git Hg Mtn Arch), 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, for details.

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.

Normally the work file exists all the time, whether it is locked or not.  If you set vc-keep-workfiles to nil, then checking in a new version with C-x v v deletes the work file; but any attempt to visit the file with Emacs creates it again.  (With CVS, work files are always kept.)

Editing a version-controlled file through a symbolic link can be dangerous.  It bypasses the version control system---you can edit the file without locking it, and fail to check your changes in.  Also, your changes might overwrite those of another user.  To protect against this, VC checks each symbolic link that you visit, to see if it points to a file under version control.

The variable vc-follow-symlinks controls what to do when a symbolic link points to a version-controlled file.  If it is nil, VC only displays a warning message.  If it is t, VC automatically follows the link, and visits the real file instead, telling you about this in the echo area.  If the value is ask (the default), VC asks you each time whether to follow the link.

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.  (This variable does not affect C-x v c; that operation is so drastic that it should always ask for confirmation.)

VC mode does much of its work by running the shell commands for the appropriate backend.  If vc-command-messages is non-nil, VC displays messages to indicate which shell commands it runs, and additional messages when the commands finish.

You can specify additional directories to search for version control programs by setting the variable vc-path.  These directories are searched before the usual search path.  It is rarely necessary to set this variable, because VC normally finds the proper files automatically.

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.

You can specify the criterion for whether to trust the file permissions by setting the variable vc-mistrust-permissions. Its value can be t (always mistrust the file permissions and check the master file), nil (always trust the file permissions), or a function of one argument which makes the decision. The argument is the directory name of the RCS subdirectory.  A non-nil value from the function says to mistrust the file permissions.  If you find that the file permissions of work files are changed erroneously, set vc-mistrust-permissions to t. Then VC always checks the master file to determine the file's status.

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-mistrust-permissions affects SCCS use, but vc-consult-headers does not.

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.  There is another variable, vc-stay-local, which enables the feature also for other back ends that support it, including CVS.  In the following, we will talk only about vc-cvs-stay-local, but everything applies to vc-stay-local as well.

If vc-cvs-stay-local is t (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).