New VC command docs for the Emacs manual.

2 files changed, 94 insertions, 56 deletions

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 41decab74bf..67f85861e2d 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,6 +1,11 @@
+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>
diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi
index 6e90cff5776..92bd9c1bd49 100644
--- a/doc/emacs/files.texi
+++ b/doc/emacs/files.texi
@@ -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.