emacs-gpu/doc/emacs/vc1-xtra.texi

@c This is part of the Emacs manual.
@c Copyright (C) 2004--2026 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@c
@c This file is included either in vc-xtra.texi (when producing the
@c printed version) or in the main Emacs manual (for the on-line version).

@node Miscellaneous VC
@subsection Miscellaneous Commands and Features of VC

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

@menu
* Change Logs and VC::   Generating a change log file from log entries.
* VC Delete/Rename::     Deleting and renaming version-controlled files.
* Revision Tags::        Symbolic names for revisions.
* Merge Bases::          The most recent revision existing on both branches.
* Unintegrated Changes:: Diffs including all unintegrated changes on a branch.
* Other Working Trees::  Multiple sets of workfiles.
* Version Headers::      Inserting version control headers into working files.
* Editing VC Commands::  Editing the VC shell commands that Emacs will run.
* Preparing Patches::    Preparing and composing patches from within VC.
* VC Auto-Reverting::    Updating buffer contents after VCS operations.
* Rewinding Branches::   Commands to delete revisions from ends of branches.
@end menu

@node Change Logs and VC
@subsubsection Change Logs and VC

  If you use RCS or CVS for a program with a @file{ChangeLog} file
@iftex
(@pxref{Change Log,,,emacs, the Emacs Manual}),
@end iftex
@ifnottex
(@pxref{Change Log}),
@end ifnottex
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 @file{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 @samp{*vc-log*}
buffer when you commit
@iftex
(@pxref{Log Buffer,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{Log Buffer}).
@end ifnottex

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

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

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

@iftex
@medbreak
@end iftex
@smallexample
@group
1999-05-22  Nathaniel Bowditch  <nat@@apn.org>

        * rcs2log: Ignore log messages that start with '#'.
@end group
@end smallexample
@iftex
@medbreak
@end iftex

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

@iftex
@medbreak
@end iftex
@smallexample
@group
1999-05-06  Nathaniel Bowditch  <nat@@apn.org>

        * vc.el (vc-do-command): Check call-process status.
@end group
@end smallexample
@iftex
@medbreak
@end iftex

  When @kbd{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.

@node VC Delete/Rename
@subsubsection Deleting and Renaming Version-Controlled Files
@cindex renaming version-controlled files

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

@item C-x v R
Prompt for two file names, @var{old} and @var{new}, rename them in the
working tree, and schedule the renaming for committing.  The @var{old}
file defaults to the current buffer's file name if it is under VC.
@end table

@findex vc-delete-file
  If you wish to delete a version-controlled file, type @kbd{C-x v x}
(@code{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
@iftex
(@pxref{VC Directory Mode,,, emacs, the Emacs Manual}),
@end iftex
@ifnottex
(@pxref{VC Directory Mode}),
@end ifnottex
it is displayed with the @samp{removed} status.  When you commit it,
the deletion takes effect in the repository.

@findex vc-rename-file
  To rename a version-controlled file, type @kbd{C-x v R}
(@code{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
@code{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.

@node Revision Tags
@subsubsection Revision Tags
@cindex revision tag
@cindex tags for version control

  Most version control systems allow you to apply a @dfn{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.

@table @code
@kindex C-x v s
@findex vc-create-tag
@item C-x v s @var{name} @key{RET}
Define the working revision of every registered file in or under the
current directory as a tag named @var{name}
(@code{vc-create-tag}).

@kindex C-x v r
@findex vc-retrieve-tag
@item C-x v r @var{name} @key{RET}
For all registered files at or below the current directory level,
retrieve the tagged revision @var{name}.  This command will switch to a
branch if @var{name} is a branch name and your VCS distinguishes
branches from tags.  (@code{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.
@end table

  You can give a tag or branch name as an argument to @kbd{C-x v =} or
@kbd{C-x v ~}
@iftex
(@pxref{Old Revisions,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{Old Revisions}).
@end ifnottex
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
@kbd{C-x v R} (@code{vc-rename-file}) will do this automatically
@iftex
(@pxref{VC Delete/Rename,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{VC Delete/Rename}).
@end ifnottex
If you are using SCCS, you must also update the records of the tag, to
mention the file by its new name (@kbd{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
@kbd{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.

@node Merge Bases
@subsubsection Merge Bases
@cindex merge bases

@table @kbd
@item C-x v M D
Report diffs of changes on a branch since it diverged from another
(@code{vc-diff-mergebase}).

@item C-x v M L
Display log messages for revisions on a branch since it diverged from
another (@code{vc-log-mergebase}).
@end table

@c This definition is possibly dVCS-specific -- can revisions exist on
@c more than one branch for older VCS?  This needs thinking through if
@c any of our centralized VCS gain support for these commands.
The @dfn{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 (@pxref{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 (@pxref{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 (@pxref{VCS Repositories}).

@kindex C-x v M D
@findex vc-diff-mergebase
@kindex C-x v M L
@findex vc-log-mergebase
Merge bases are useful to make certain comparisons between branches, and
Emacs provides two commands for doing so.  Each of @kbd{C-x v M D}
(@code{vc-diff-mergebase}) and @kbd{C-x v M L} (@code{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''.@footnote{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.  @kbd{C-x v M D} and @kbd{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 @kbd{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
@kbd{C-x v M L} shows you a log of the changes on the source branch not
yet merged into the target branch.

@node Unintegrated Changes
@subsubsection Commands to see all unintegrated changes
@cindex unintegrated changes
@cindex remote unintegrated changes

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

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

@item 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
(@code{vc-log-unintegrated}).

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

@item 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
(@code{vc-diff-remote-unintegrated}).

@item 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
(@code{vc-root-diff-remote-unintegrated}).

@item 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
(@code{vc-log-remote-unintegrated}).

@item 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
(@code{vc-root-log-remote-unintegrated}).
@end table

For decentralized version control systems (@pxref{VCS Repositories}),
these commands provide specialized versions of @kbd{C-x v M L} and
@w{@kbd{C-x v M D}} (see @pxref{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 (@pxref{Branches}).  These two cases are conceptually
distinct, and so we will introduce them separately.

First, consider working on a single branch.  @dfn{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.

@kindex C-x v T =
@findex vc-diff-unintegrated
@kindex C-x v T D
@findex vc-root-diff-unintegrated
Type @kbd{C-x v T D} (@code{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 (@pxref{Pulling
/ Pushing}) all these changes would do to the upstream repository.  You
can use @kbd{C-x v T =} (@code{vc-diff-unintegrated}) instead to limit
the display of changes to the current VC fileset.  (The difference
between @w{@kbd{C-x v T D}} and @w{@kbd{C-x v T =}} is like the
difference between @kbd{C-x v D} and @kbd{C-x v =} (@pxref{Old
Revisions}).)@footnote{Another point of comparison is that these
commands are like @w{@kbd{C-x v O =}} (@code{vc-fileset-diff-outgoing})
and @kbd{C-x v O D} (@code{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.}

@kindex C-x v T l
@findex vc-log-unintegrated
@kindex C-x v T L
@findex vc-root-log-unintegrated
Type @kbd{C-x v T L} (@code{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 @kbd{C-x v T l}
(@code{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 @dfn{topic branch},@footnote{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 @dfn{trunk} or
@dfn{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 @kbd{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,
@emph{and} subsequently merging the topic branch, would do to the trunk.
As above, you can use @kbd{C-x v T =} instead to limit the display of
changes to the current VC fileset.  @kbd{C-x v T L} and @kbd{C-x v T l}
show the corresponding revision logs, excluding uncommitted changes as
above.

@findex vc-diff-remote-unintegrated
@findex vc-root-diff-remote-unintegrated
@findex vc-log-remote-unintegrated
@findex vc-root-log-remote-unintegrated
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 @dfn{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: @w{@kbd{C-x v R T =}}
(@code{vc-diff-remote-unintegrated}), @w{@kbd{C-x v R T D}}
(@code{vc-root-diff-remote-unintegrated}), @w{@kbd{C-x v R T l}}
(@code{vc-log-remote-unintegrated}), and @w{@kbd{C-x v R T L}}
(@code{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.

@vindex vc-trunk-branch-regexps
@vindex vc-topic-branch-regexps
The variables @code{vc-trunk-branch-regexps} and
@code{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 @kbd{C-x v T @dots{}}.  Here is a summary of how to use these
controls:

@enumerate
@item
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
(@pxref{Regexps}), to the @code{vc-topic-branch-regexps} variable.
There are a few special kinds of value to simplify common use cases:

@itemize
@item
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.

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

@item
If instead of a list of regular expressions the
@code{vc-topic-branch-regexps} variable has the special value @code{t},
then Emacs treats as a topic branch any branch that the
@code{vc-trunk-branch-regexps} variable doesn't positively identify as a
trunk.
@end itemize

@xref{Directory Variables}, regarding how to specify values of
@code{vc-topic-branch-regexps} and @code{vc-trunk-branch-regexps} for a
single VC repository.

@item
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 @code{vc-trunk-branch-regexps} variable.  This works just like
@code{vc-topic-branch-regexps} with the same special values we just
described.  E.g., if the value of @code{vc-trunk-branch-regexps} is
@code{t}, Emacs treats as a trunk any branch that the
@code{vc-topic-branch-regexps} variable doesn't identify as a topic
branch.

@item
Supply a double prefix argument, i.e. @w{@kbd{C-u C-u C-x v T @dots{}}},
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 (@pxref{VC Change Log}) plus uncommitted changes.

@item
@cindex outgoing base, version control
Finally, you can take full manual control by supplying a single prefix
argument, i.e. @w{@kbd{C-u C-x v T @dots{}}}.  Emacs will prompt you for
the @dfn{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 @var{foo}, you would supply
@kbd{origin/@var{foo}}.  So if @var{foo} is the current branch then you
would enter an outgoing base of @kbd{origin/@var{foo}} to treat
@var{foo} as a trunk, or an outgoing base of @kbd{origin/@var{bar}} to
treat @var{foo} as a topic branch which will later be merged into a
trunk named @var{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.
@end enumerate

@node Other Working Trees
@subsubsection Multiple Working Trees for One Repository

@cindex other working trees
@cindex multiple working trees
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 (@pxref{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 @kbd{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 @w{@kbd{C-x v w a}} (see
below), build and test it.  Satisfied, you use @w{@kbd{C-x v P}}
(@pxref{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 @kbd{C-x v m} (@pxref{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 @kbd{C-x v P} later.

Ordinary VC commands like @kbd{C-x v v} (@pxref{Basic VC Editing}) and
@kbd{C-x v d} (@pxref{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
@code{default-directory} (@pxref{File Names}) is within a VC working
tree.

@table @kbd
@item C-x v w c
Add a new working tree.

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

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

@item C-x v w s
Invoke @kbd{C-x p p} (@code{project-switch-project}) but limited to
other working trees.

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

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

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

@item C-x v w R
Relocate a working tree to another file name.
@end table

@kindex C-x v w c
@findex vc-add-working-tree
You can start using multiple working trees by using the command
@w{@kbd{C-x v w c}} (@code{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.

@kindex C-x v w w
@findex vc-switch-working-tree
Once your repository has other working trees, you can use the command
@kbd{C-x v w w} (@code{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.

@kbd{C-x v w w} also works in Diff mode (@pxref{Diff Mode}) and Log View
mode (@pxref{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 @kbd{C-x v L} (@pxref{VC Change Log}).  After using @kbd{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 @kbd{=} (@code{log-view-diff})
to open a Diff mode buffer with that revision's changes.  Then you can
use standard Diff mode commands like @w{@kbd{C-c C-a}}
(@code{diff-apply-hunk}) to apply hunks to the other working tree.

@kindex C-x v w k
@findex vc-kill-other-working-tree-buffers
After using @kbd{C-x v w w} in file-visiting buffers you will have
multiple buffers visiting identically named files (@pxref{Uniquify}).
You can kill all but one of these buffers by typing @kbd{C-x v w k}
(@code{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.

@kindex C-x v w s
@findex vc-working-tree-switch-project
An alternative way to switch between working trees is @kbd{C-x v w s}
(@code{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 @kbd{C-x p p} (@code{project-switch-project})
(@pxref{Switching Projects}) but with the selection of projects limited
to other working trees.  The main difference between @kbd{C-x v w w} and
@kbd{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.

@kindex C-x v w a
@findex vc-apply-to-other-working-tree
The command @kbd{C-x v w a} (@code{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 (@pxref{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.

@kbd{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.

@kindex C-x v w A
@findex vc-apply-root-to-other-working-tree
The command @kbd{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 @kbd{C-c C-a} and @w{@kbd{C-c <RET> a}}
(@pxref{Diff Mode}).  (@w{@kbd{C-u C-u C-x v w A}} is roughly equivalent
to typing @w{@kbd{C-x v D}} followed by @w{@kbd{C-x v w w}}.)

@kindex C-x v w x
@kindex C-x v w R
@findex vc-delete-working-tree
@findex vc-move-working-tree
The commands @kbd{C-x v w x} (@code{vc-delete-working-tree}) and
@kbd{C-x v w R} (@code{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.

@node Version Headers
@subsubsection Inserting Version Control Headers

  On Subversion, CVS, RCS, and SCCS, you can put certain special
strings called @dfn{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.

@vindex vc-consult-headers
  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 @code{vc-consult-headers} to @code{nil}.  VC
then always uses the file permissions (if it is supposed to trust
them), or else checks the master file.

@findex vc-insert-headers
@vindex vc-@var{backend}-header
  To insert a suitable header string into the current buffer, use the
command @kbd{M-x vc-insert-headers}.  This command works only on
Subversion, CVS, RCS, and SCCS@.  The variable
@code{vc-@var{backend}-header} contains the list of keywords to insert
into the version header; for instance, CVS uses @code{vc-cvs-header},
whose default value is @code{'("\$Id\$")} (@pxref{Keyword
substitution,,,cvs,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 @code{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.

@vindex vc-static-header-alist
  The variable @code{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 @code{(@var{regexp} . @var{format})}.  Whenever
@var{regexp} matches the buffer name, @var{format} is also inserted as
part of the version header.  A @samp{%s} in @var{format} is replaced
with the file's version control type.

@node Editing VC Commands
@subsubsection Editing VC Commands

@findex vc-edit-next-command
@kindex C-x v !
You can use the @kbd{C-x v !} (@code{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
@w{@kbd{C-x v b L}} (@code{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 @w{@kbd{C-x v ! C-x v b L}} and then append the names of
additional branches to the end of the @samp{git log} command that VC is
about to run.

@node Preparing Patches
@subsubsection Preparing Patches

@findex vc-prepare-patch
When collaborating on projects it is common to send patches via email,
to share changes.  You can do this using VC with the
@code{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
@var{crm-separator}, commas by default.  The command will then prepare
those revisions using your @abbr{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.

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

@vindex vc-default-patch-addressee
If you expect to contribute patches on a regular basis, you can set
the user option @code{vc-default-patch-addressee} to the address(es)
you wish to use.  This will be used as the default value when invoking
@code{vc-prepare-patch}.  Project maintainers may consider setting
this as a directory local variable
@iftex
(@pxref{Directory Variables,,Per-Directory Local Variables,
emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{Directory Variables}).
@end ifnottex

@node VC Auto-Reverting
@subsubsection 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
(@pxref{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 (@pxref{Version Headers}).

@findex vc-auto-revert-mode
  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
@code{vc-auto-revert-mode} instead, by customizing that variable to a
non-@code{nil} value.

  This mode is just like @code{global-auto-revert-mode} (@pxref{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.

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

@node Rewinding Branches
@subsubsection Rewinding Branches
@cindex rewinding a branch (VC)

@table @kbd
@item M-x vc-delete-revisions-from-end
Delete revisions from the end of the current branch.

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

@findex vc-delete-revisions-from-end
  For decentralized version control systems (@pxref{VCS Repositories}),
these commands provide ways to move the current branch back to an
earlier revision.  @code{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
@dfn{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 (@pxref{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.

@cindex uncommitting revisions
@findex vc-uncommit-revisions-from-end
  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 @code{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
@w{@kbd{C-x v +}} (@pxref{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
@code{log-view-uncommit-revisions-from-end} and
@code{log-view-delete-revisions-from-end} commands, bound to @kbd{x} and
@kbd{X}, respectively, in Log View mode buffers (@pxref{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.

@node Customizing VC
@subsection Customizing VC

@vindex vc-handled-backends
  The variable @code{vc-handled-backends} determines which version
control systems VC should handle.  The default value is @code{(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 @code{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 @code{vc-handled-backends} by default.  The order is also
significant when you register a file for the first time
@iftex
(@pxref{Registering,,,emacs, the Emacs Manual}).
@end iftex
@ifnottex
(@pxref{Registering}).
@end ifnottex

@menu
* General VC Options::  Options that apply to multiple back ends.
* RCS and SCCS::        Options for RCS and SCCS.
* CVS Options::         Options for CVS.
@end menu

@node General VC Options
@subsubsection General Options

@vindex vc-make-backup-files
  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
@code{vc-make-backup-files} to a non-@code{nil} value.

@vindex vc-follow-symlinks
@cindex symbolic links (and version control)
  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 @code{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 @code{ask} (the default),
Emacs asks for confirmation.  If it is @code{nil}, Emacs just displays
a warning message.  If it is @code{t}, Emacs automatically follows the
link and visits the real file instead.

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

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

@vindex vc-display-failed-async-commands
  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 (@pxref{Pulling / Pushing}).
When the command starts, VC displays a buffer into which the commands
output will be written.  If @code{vc-display-failed-async-commands} is
non-@code{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.

@vindex vc-async-checkin
  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 @code{vc-async-checkin}
to non-@code{nil} switches to doing checkin operations asynchronously.
This is particularly useful as a directory local variable in
repositories where checkin operations are slow (@pxref{Directory Local
Variables,,,elisp,GNU Emacs Lisp Reference Manual}).

  While an asynchronous checkin operation is in progress, if you use
@kbd{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.

@node RCS and SCCS
@subsubsection Options for RCS and SCCS

@cindex non-strict locking (RCS)
@cindex locking, non-strict (RCS)
  By default, RCS uses locking to coordinate the activities of several
users, but there is a mode called @dfn{non-strict locking} in which
you can check-in changes without locking the file first.  Use
@samp{rcs -U} to switch to non-strict locking for a particular file,
see the @code{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 (@pxref{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 @emph{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 @code{vc-consult-headers} to @code{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 @code{vc-consult-headers} does not affect SCCS use.

@node CVS Options
@subsubsection Options specific for CVS

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

@vindex vc-cvs-stay-local
@cindex remote repositories (CVS)
  When using a CVS repository on a remote machine, VC can try keeping
network interactions to a minimum.  This is controlled by the variable
@code{vc-cvs-stay-local}.  If @code{vc-cvs-stay-local} is
@code{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 @code{vc-cvs-stay-local} to @code{nil}, VC queries the
remote repository @emph{before} it decides what to do in
@code{vc-next-action} (@kbd{C-x v v}), just as it does for local
repositories.

  You can also set @code{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.

@cindex automatic version backups
  When using a remote repository, Emacs normally makes @dfn{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;
@iftex
@pxref{Backup,,,emacs, the Emacs Manual}.)
@end iftex
@ifnottex
@pxref{Backup}.)
@end ifnottex
Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic
version backups, if possible, to avoid having to access the network.

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

@cindex manual version backups
  Automatic version backups have names of the form
@w{@code{@var{file}.~@var{version}.~}}.  This is similar to the name
that @kbd{C-x v ~} saves old versions to
@iftex
(@pxref{Old Revisions,,,emacs, the Emacs Manual}),
@end iftex
@ifnottex
(@pxref{Old Revisions}),
@end ifnottex
except for the additional dot (@samp{.}) 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 @kbd{C-x v
~} are not deleted automatically when you commit.

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