comparison man/files.texi @ 83494:b901f4f12f33

Merged from [e-mail] Patches applied: * [e-mail]/emacs--devo--0--patch-160 Update from CVS * [e-mail]/emacs--devo--0--patch-161 Update from CVS * [e-mail]/emacs--devo--0--patch-162 Update from CVS * [e-mail]/emacs--devo--0--patch-163 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-164 Update from CVS * [e-mail]/emacs--devo--0--patch-165 Update from CVS * [e-mail]/emacs--devo--0--patch-166 Update from CVS * [e-mail]/emacs--devo--0--patch-167 Update from CVS * [e-mail]/emacs--devo--0--patch-168 Update from CVS * [e-mail]/emacs--devo--0--patch-169 Update from CVS * [e-mail]/emacs--devo--0--patch-170 Merge from gnus--rel--5.10 * [e-mail]/emacs--devo--0--patch-171 Update from CVS: man/mh-e.texi (Folders): Various edits. * [e-mail]/emacs--devo--0--patch-172 Update from CVS * [e-mail]/gnus--rel--5.10--patch-58 Update from CVS * [e-mail]/gnus--rel--5.10--patch-59 Update from CVS * [e-mail]/gnus--rel--5.10--patch-60 Update from CVS * [e-mail]/gnus--rel--5.10--patch-61 Update from CVS * [e-mail]/gnus--rel--5.10--patch-62 Merge from emacs--devo--0 * [e-mail]/gnus--rel--5.10--patch-63 Update from CVS * [e-mail]/gnus--rel--5.10--patch-64 Update from CVS git-archimport-id: [e-mail]--2004/emacs--multi-tty--0--patch-534

83493:1bf2ca323037

  SCCS is a proprietary but widely used version control system.  In
terms of capabilities, it is the weakest of the six that VC supports.
VC compensates for certain features missing in SCCS (snapshots, for
example) by implementing them itself, but some other VC features, such
as multiple branches, are not available with SCCS.  Since SCCS is
non-free, not respecting its users freedom,d, you should not use it;
use its free replacement CSSC instead.  But you should use CSSC only
if for some reason you cannot use RCS, or one of the higher-level
systems such as CVS or GNU Arch.

In the following, we discuss mainly RCS, SCCS and CVS.  Nearly

@item C-x v ~ @var{version} @key{RET}
Examine version @var{version} of the visited file, in a buffer of its
own.

@item C-x v =
Compare the current buffer contents with the latest checked-in version
of the file.

@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
Compare the specified two versions of @var{file}.

@item C-x v g

@findex vc-diff
@kindex C-x v =
  It is usually more convenient to compare two versions of the file,
with the command @kbd{C-x v =} (@code{vc-diff}).  Plain @kbd{C-x v =}
compares the current buffer contents (saving them in the file if
necessary) with the last checked-in version of the file.  @kbd{C-u C-x
v =}, with a numeric argument, reads a file name and two version
numbers, then compares those versions of the specified file.  Both
forms display the output in a special buffer in another window.

  You can specify a checked-in version by its number; an empty input
specifies the current contents of the work file (which may be different
from all the checked-in versions).  You can also specify a snapshot name
(@pxref{Snapshots}) instead of one or both version numbers.

find the corresponding locations in the current work file.  (Older
versions are not, in general, present as files on your disk.)

@findex vc-annotate
@kindex C-x v g
  For some backends, you can display the file @dfn{annotated} with
per-line version information and using colors to enhance the visual
appearance, with the command @kbd{M-x vc-annotate}.
It creates a new buffer (the ``annotate buffer'') displaying the
file's text, with each part colored to show how old it is.  Text
colored red is new, blue means old, and intermediate colors indicate

line.

@item W
Annotate the workfile version--the one you are editing.  If you used
@kbd{P} and @kbd{N} to browse to other revisions, use this key to
return to the latest version.
@end table

@node Secondary VC Commands
@subsection The Secondary Commands of VC

@node VC Undo
@subsubsection Undoing Version Control Actions

@table @kbd
@item C-x v u
Revert the buffer and the file to the last checked-in version.

@item C-x v c
Remove the last-entered change from the master for the visited file.
This undoes your last check-in.
@end table

@kindex C-x v u
@findex vc-revert-buffer
  If you want to discard your current set of changes and revert to the
last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
This leaves the file unlocked; if locking is in use, you must first lock
the file again before you change it again.  @kbd{C-x v u} requires
confirmation, unless it sees that you haven't made any changes since the
last checked-in version.

  @kbd{C-x v u} is also the command to unlock a file if you lock it and
then decide not to change it.

@kindex C-x v c
@findex vc-cancel-version
  To cancel a change that you already checked in, use @kbd{C-x v c}
(@code{vc-cancel-version}).  This command discards all record of the
most recent checked-in version.  @kbd{C-x v c} also offers to revert
your work file and buffer to the previous version (the one that precedes
the version that is deleted).

  If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
the file.  The no-revert option is useful when you have checked in a
change and then discover a trivial error in it; you can cancel the
erroneous check-in, fix the error, and check the file in again.

  Here @samp{file1.c} is modified with respect to the repository, and
@samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
have also been checked in to the repository---you need to merge them
with the work file before you can check it in.

@vindex vc-directory-exclusion-list
  When VC Dired displays subdirectories (in the ``full'' display mode),
it omits some that should never contain any files under version control.
By default, this includes Version Control subdirectories such as

@cindex named configurations (RCS)
  VC's snapshot facilities are modeled on RCS's named-configuration
support.  They use RCS's native facilities for this, so
snapshots made using RCS through VC are visible even when you bypass VC.

@c worded verbosely to avoid overfull hbox.
  For SCCS, VC implements snapshots itself.  The files it uses contain
name/file/version-number triples.  These snapshots are visible only
through VC.

@c ??? What about CVS?

  A snapshot is a set of checked-in versions.  So make sure that all the
files are checked in and not locked when you make a snapshot.

  File renaming and deletion can create some difficulties with snapshots.

Visit the current directory's change log file and, for registered files
in that directory, create new entries for versions checked in since the
most recent entry in the change log file.
(@code{vc-update-change-log}).

This command works with RCS or CVS only, not with SCCS.

@c ??? What about other back ends?

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

@item M-1 C-x v a

accordingly.  It also updates any snapshots (@pxref{Snapshots}) that
mention the file, so that they use the new name; despite this, the
snapshot thus modified may not completely work (@pxref{Snapshot
Caveats}).

  Some backends do not provide an explicit rename operation to their
repositories.  After issuing @code{vc-rename-file}, use @kbd{C-x v v}
on the original and renamed buffers and provide the necessary edit
log.

  You cannot use @code{vc-rename-file} on a file that is locked by

@subsubsection Inserting Version Control Headers

   Sometimes it is convenient to put version identification strings
directly into working files.  Certain special strings called
@dfn{version headers} are replaced in each successive version by the
number of that version.

@c ??? How does this relate to CVS?

  If you are using RCS, and version headers are present in your working
files, Emacs can use them to determine the current version and the
locking state of the files.  This is more reliable than referring to the
master files, which is done when there are no version headers.  Note
that in a multi-branch environment, version headers are necessary to
make VC behave correctly (@pxref{Multi-User Branching}).

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

@kindex C-x v h
@findex vc-insert-headers
  You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
insert a suitable header string.

make it writable.  VC calls @code{cvs edit} to make the file writable,
and CVS takes care to notify other developers of the fact that you
intend to change the file.  See the CVS documentation for details on
using the watch feature.

@vindex vc-cvs-stay-local
@cindex remote repositories (CVS)
  When a file's repository is on a remote machine, VC tries to keep
network interactions to a minimum.  This is controlled by the variable
@code{vc-cvs-stay-local}.  If it is @code{t} (the default), then VC uses
only the entry in the local CVS subdirectory to determine the file's
state (and possibly information returned by previous CVS commands).  One
consequence of this is that when you have modified a file, and somebody
else has already checked in other changes to the file, you are not
notified of it until you actually try to commit.  (But you can try to
pick up any recent changes from the repository first, using @kbd{C-x v m
@key{RET}}, @pxref{Merging}).

@vindex vc-cvs-global-switches
  The variable @code{vc-cvs-global-switches}, if non-@code{nil},
should be a string specifying switches to pass to CVS for all CVS
operations.

  When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
version backups, so that simple diff and revert operations are
completely local (@pxref{Version Backups}).

repositories.  It also does not make any version backups.

  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.

@node Directories
@section File Directories

@cindex file directory

typically the result of a failed merge from a version control system
``update'' outside VC, due to conflicting changes to a file.  Smerge
mode provides commands to resolve conflicts by selecting specific
changes.

  See also @ref{Emerge}, and @ref{Top,,, ediff, The Ediff Manual}, for
convenient facilities for merging two similar files.

@node Misc File Ops
@section Miscellaneous File Operations

  Emacs has commands for performing many other operations on files.

83494:b901f4f12f33

  SCCS is a proprietary but widely used version control system.  In
terms of capabilities, it is the weakest of the six that VC supports.
VC compensates for certain features missing in SCCS (snapshots, for
example) by implementing them itself, but some other VC features, such
as multiple branches, are not available with SCCS.  Since SCCS is
non-free, not respecting its users freedom, you should not use it;
use its free replacement CSSC instead.  But you should use CSSC only
if for some reason you cannot use RCS, or one of the higher-level
systems such as CVS or GNU Arch.

In the following, we discuss mainly RCS, SCCS and CVS.  Nearly

@item C-x v ~ @var{version} @key{RET}
Examine version @var{version} of the visited file, in a buffer of its
own.

@item C-x v =
Compare the current buffer contents with the master version from which
you started editing.

@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
Compare the specified two versions of @var{file}.

@item C-x v g

@findex vc-diff
@kindex C-x v =
  It is usually more convenient to compare two versions of the file,
with the command @kbd{C-x v =} (@code{vc-diff}).  Plain @kbd{C-x v =}
compares the current buffer contents (saving them in the file if
necessary) with the master version from which you started editing the
file (this is not necessarily the latest version of the file).
@kbd{C-u C-x v =}, with a numeric argument, reads a file name and two
version numbers, then compares those versions of the specified file.
Both forms display the output in a special buffer in another window.

  You can specify a checked-in version by its number; an empty input
specifies the current contents of the work file (which may be different
from all the checked-in versions).  You can also specify a snapshot name
(@pxref{Snapshots}) instead of one or both version numbers.

find the corresponding locations in the current work file.  (Older
versions are not, in general, present as files on your disk.)

@findex vc-annotate
@kindex C-x v g
  For some back ends, you can display the file @dfn{annotated} with
per-line version information and using colors to enhance the visual
appearance, with the command @kbd{M-x vc-annotate}.
It creates a new buffer (the ``annotate buffer'') displaying the
file's text, with each part colored to show how old it is.  Text
colored red is new, blue means old, and intermediate colors indicate

line.

@item W
Annotate the workfile version--the one you are editing.  If you used
@kbd{P} and @kbd{N} to browse to other revisions, use this key to
return to your current version.
@end table

@node Secondary VC Commands
@subsection The Secondary Commands of VC

@node VC Undo
@subsubsection Undoing Version Control Actions

@table @kbd
@item C-x v u
Revert the buffer and the file to the version from which you started
editing the file.

@item C-x v c
Remove the last-entered change from the master for the visited file.
This undoes your last check-in.
@end table

@kindex C-x v u
@findex vc-revert-buffer
  If you want to discard your current set of changes and revert to the
version from which you started editing the file, use @kbd{C-x v u}
(@code{vc-revert-buffer}).  This leaves the file unlocked; if locking
is in use, you must first lock the file again before you change it
again.  @kbd{C-x v u} requires confirmation, unless it sees that you
haven't made any changes with respect to the master version.

  @kbd{C-x v u} is also the command to unlock a file if you lock it and
then decide not to change it.

@kindex C-x v c
@findex vc-cancel-version
  To cancel a change that you already checked in, use @kbd{C-x v c}
(@code{vc-cancel-version}).  This command discards all record of the
most recent checked-in version, but only if your work file corresponds
to that version---you cannot use @kbd{C-x v c} to cancel a version
that is not the latest on its branch.  @kbd{C-x v c} also offers to
revert your work file and buffer to the previous version (the one that
precedes the version that is deleted).

  If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
the file.  The no-revert option is useful when you have checked in a
change and then discover a trivial error in it; you can cancel the
erroneous check-in, fix the error, and check the file in again.

  Here @samp{file1.c} is modified with respect to the repository, and
@samp{file2.c} is not.  @samp{file3.c} is modified, but other changes
have also been checked in to the repository---you need to merge them
with the work file before you can check it in.

@vindex vc-stay-local
@vindex vc-cvs-stay-local
  In the above, if the repository were on a remote machine, VC would
only contact it when the variable @code{vc-stay-local} (or
@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  This is
because access to the repository may be slow, or you may be working
offline and not have access to the repository at all.  As a
consequence, VC would not be able to tell you that @samp{file3.c} is
in the ``merge'' state; you would learn that only when you try to
check-in your modified copy of the file, or use a command such as
@kbd{C-x v m}.

  In practice, this is not a problem because CVS handles this case
consistently whenever it arises.  In VC, you'll simply get prompted to
merge the remote changes into your work file first.  The benefits of
less network communication usually outweigh the disadvantage of not
seeing remote changes immediately.

@vindex vc-directory-exclusion-list
  When VC Dired displays subdirectories (in the ``full'' display mode),
it omits some that should never contain any files under version control.
By default, this includes Version Control subdirectories such as

@cindex named configurations (RCS)
  VC's snapshot facilities are modeled on RCS's named-configuration
support.  They use RCS's native facilities for this, so
snapshots made using RCS through VC are visible even when you bypass VC.

  With CVS, Meta-CVS, and Subversion, VC also uses the native
mechanism provided by that back end to make snapshots and retrieve them
(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion).

@c worded verbosely to avoid overfull hbox.
  For SCCS, VC implements snapshots itself.  The files it uses contain
name/file/version-number triples.  These snapshots are visible only
through VC.

  There is no support for VC snapshots using GNU Arch yet.

  A snapshot is a set of checked-in versions.  So make sure that all the
files are checked in and not locked when you make a snapshot.

  File renaming and deletion can create some difficulties with snapshots.

Visit the current directory's change log file and, for registered files
in that directory, create new entries for versions checked in since the
most recent entry in the change log file.
(@code{vc-update-change-log}).

This command works with RCS or CVS only, not with any of the other
back ends.

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

@item M-1 C-x v a

accordingly.  It also updates any snapshots (@pxref{Snapshots}) that
mention the file, so that they use the new name; despite this, the
snapshot thus modified may not completely work (@pxref{Snapshot
Caveats}).

  Some back ends do not provide an explicit rename operation to their
repositories.  After issuing @code{vc-rename-file}, use @kbd{C-x v v}
on the original and renamed buffers and provide the necessary edit
log.

  You cannot use @code{vc-rename-file} on a file that is locked by

@subsubsection Inserting Version Control Headers

   Sometimes it is convenient to put version identification strings
directly into working files.  Certain special strings called
@dfn{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.  Note that in a multi-branch environment, version
headers are necessary to make VC behave correctly (@pxref{Multi-User
Branching}).

  Searching for RCS version headers is controlled by the variable
@code{vc-consult-headers}.  If it is non-@code{nil} (the default),
Emacs searches for headers to determine the version number you are
editing.  Setting it to @code{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.

@kindex C-x v h
@findex vc-insert-headers
  You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
insert a suitable header string.

make it writable.  VC calls @code{cvs edit} to make the file writable,
and CVS takes care to notify other developers of the fact that you
intend to change the file.  See the CVS documentation for details on
using the watch feature.

@vindex vc-stay-local
@vindex vc-cvs-stay-local
@cindex remote repositories (CVS)
  When a file's repository is on a remote machine, VC tries to keep
network interactions to a minimum.  This is controlled by the variable
@code{vc-cvs-stay-local}.  There is another variable,
@code{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 @code{vc-cvs-stay-local}, but everything applies to
@code{vc-stay-local} as well.

If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses
only the entry in the local CVS subdirectory to determine the file's
state (and possibly information returned by previous CVS commands).
One consequence of this is that when you have modified a file, and
somebody else has already checked in other changes to the file, you
are not notified of it until you actually try to commit.  (But you can
try to pick up any recent changes from the repository first, using
@kbd{C-x v m @key{RET}}, @pxref{Merging}).

  When @code{vc-cvs-stay-local} is @code{t}, VC also makes local
version backups, so that simple diff and revert operations are
completely local (@pxref{Version Backups}).

repositories.  It also does not make any version backups.

  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.

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

@node Directories
@section File Directories

@cindex file directory

typically the result of a failed merge from a version control system
``update'' outside VC, due to conflicting changes to a file.  Smerge
mode provides commands to resolve conflicts by selecting specific
changes.

  @inforef{Emerge,, emacs-xtra} for the Emerge facility, which
provides a powerful interface for merging files.

@node Misc File Ops
@section Miscellaneous File Operations

  Emacs has commands for performing many other operations on files.