path: root/doc/emacs/vc1-xtra.texi

@c This is part of the Emacs manual.
@c Copyright (C) 2004--2023 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.
* 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
@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 M-x vc-delete-file
Prompt for a file name, delete the file from the working tree, and
schedule the deletion for committing.

@item M-x vc-rename-file
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, use the command
@kbd{M-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
@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{M-x 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
@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 (@code{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
@code{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.

@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\$")}.  (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
@kbd{C-x v b l} (@code{vc-print-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 (@pxref{Directory Variables}).

@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} is
non-@code{nil}, VC displays messages to indicate which shell commands
it runs, and additional messages when the commands finish.

@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