Commit da1080a2 authored by Eric S. Raymond's avatar Eric S. Raymond
Browse files

New VC command docs for the Emacs manual.

parent d7b60083
2007-10-10 Eric S. Raymond <esr@snark.thyrsus.com>
* files.texi (Version Systems): Merge in changes for new VC
with fileset-orienrted operations.
2007-10-09 Eric S. Raymond <esr@snark.thyrsus.com>
* files.texi (Version Systems): Describe newerte VCses.
* files.texi (Version Systems): Describe newer VCses.
Reorder the descriptions to be chronological.
2007-10-04 Nick Roberts <nickrob@snap.net.nz>
......
......@@ -1465,6 +1465,15 @@ figure that out, and while file-based systems are passing out of use
there are lots of legacy repositories still to be dealt with at time of
writing in 2007.
In fact, older versions of VC mode supported only file-based systems,
leading to some unhappy results when it was used to drive
changeset-based ones--the Subversion support, for example, used to break
up changesets into multiple per-file commits. This has been fixed, but
it has left a legacy in VC-mode's terminology. The terms ``checkin''
and ``checkout'' are associated with file-based and locking-based
systems and a bit archaic; nowadays those operations are usually called
``commit'' and ``update''.
@cindex centralized vs. decentralized
Early version-control systems were designed around a @dfn{centralized}
......@@ -1575,8 +1584,46 @@ system, but is usually not excessive.
@node Basic VC Editing
@subsection Basic Editing under Version Control
@node Selecting a fileset
@subsubsection Choosing the scope of your command
@cindex filesets
Most VC commands operate on @dfn{filesets}. A fileset is a
group of files that you have chosen to treat as a unit at the
time you perform the command. Filesets are the way that VC
mode bridges the gap between file-based and changeset-based
version-control systems.
If you are visiting a version-controlled file in the current buffer,
the default fileset for any command is simply that one file. If you
are visiting a VC Dired buffer, and some files in it are marked,
your fileset is the marked files only.
All files in a fileset must be under the same version-control system.
If they are not, VC mode wil throw an error when you attempt to execute
a command on the fileset.
Filesets, are, essentially, a way to pass multiple file arguments as
a group to underlying version-control commands. For example, on
Subversion a checkin with more than one file in its fileset will become a
joint commit, as though you had typed @command{svn
commit} with those file arguments at the shell command line in the
directory of the selected buffer.
If you are used to earlier versions of VC, the change in behavior you
will notice is in VC-Dired mode. Other than @kbd{C-x v v}, most VC-mode
commands used to operate on only one file selected by the line the
cursor is on. The change in the behavior of @kbd{C-x v v} is more
subtle. Formerly it operated in parallel on all marked files, but did
not pass them to the version-control backends as a group. Now it does,
which enables VC to drive changeset-based version-control systems.
@node Doing the next logical thing
@subsubsection Performing the next operation in the development cycle
The principal VC command is an all-purpose command that performs
either locking or check-in, depending on the situation.
either locking or check-in on your current fileset, depending on
the situation.
@table @kbd
@itemx C-x v v
......@@ -1776,11 +1823,13 @@ in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
time to complete the check-in.
If you change several source files for the same reason, it is often
convenient to specify the same log entry for many of the files. To do
this, use the history of previous log entries. The commands @kbd{M-n},
@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
minibuffer history commands (except that these versions are used outside
the minibuffer).
convenient to specify the same log entry for many of the files. (This
is the normal way to do things on a changeset-oriented system, where
comments are attached to changesets rather than the history of
individual files.) The most convenient way to do this is to mark all the
files in VC-Dired mode and check in from there; the log buffer will
carry the fileset information with it and do a group commit when you
confirm it with @kbd{C-c C-c}.
However, you can also browse the history of previous log entries to
duplicate a checkin comment. This can be useful when you want several
......@@ -1806,11 +1855,11 @@ 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 focus version from which
you started editing.
Compare the buffer contents of the current
fileset with the focus 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-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
Compare the specified two repository versions of the current fileset.
@item C-x v g
Display the file with per-line version information and using colors.
......@@ -1827,14 +1876,18 @@ and create a branch from it. @xref{Branches}.)
@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.
@kbd{C-x v =} compares the current buffer contents of each file in the
current fileset (saving them in the file if necessary) with the
repository version from which you started editing each file (this is not
necessarily the latest version of the file). The diff will be displayed
in a special buffer in another window.
@findex vc-diff
@kindex C-u C-x v =
You can compare two repository versions of the current fileset with
the command @kbd{C-u C-x v =} (@code{vc-diff}). @kbd{C-u C-x v =} reads
two version numbers or tags. The diff will be displayed 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
......@@ -1847,9 +1900,16 @@ from all the checked-in versions). You can also specify a snapshot name
@end ifnottex
instead of one or both version numbers.
If you supply a directory name instead of the name of a registered
file, this command compares the two specified versions of all registered
files in that directory and its subdirectories.
Note that if your version-control system is file-oriented (SCCS, RCS,
CVS) rather than fileset-oriented (CVS, Subversion, GNU Arch) specifying
a version of a multiple-file fileset by number (as opposed to a snapshot
name or RSCCS/RCS tag) is unlikely to return diffs that are connected in
any meaningful way.
If you invoke @kbd{C-u C-x v =} or @kbd{C-u C-x v =} from a buffer
that is neither visiting a version-controlled file nor a VC Dired
buffer, these commands will generate a diff of all registered files in
the current directory and its subdirectories.
@vindex vc-diff-switches
@vindex vc-rcs-diff-switches
......@@ -2083,41 +2143,14 @@ haven't made any changes with respect to the master version.
then decide not to change it.
@kindex C-x v c
@findex vc-cancel-version
@findex vc-rollback
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.
When @kbd{C-x v c} does not revert the buffer, it unexpands all
version control headers in the buffer instead
@iftex
(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
@end iftex
@ifnottex
(@pxref{Version Headers}).
@end ifnottex
This is because the buffer no longer corresponds to any existing
version. If you check it in again, the check-in process will expand
the headers properly for the new version number.
However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
automatically. If you use that header feature, you have to unexpand it
by hand---by deleting the entry for the version that you just canceled.
Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
work with it. To help you be careful, this command always requires
confirmation with @kbd{yes}. Note also that this command is disabled
under CVS, because canceling versions is very dangerous and discouraged
with CVS.
(@code{vc-rollback}). 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. Note that many version-control systems do
not support rollback at all; this command is something of a historical
relic.
@ifnottex
@c vc1-xtra.texi needs extra level of lowering.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment