[Emacs-diffs] Changes to emacs/doc/emacs/files.texi,v

[Eric S. Raymond]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Eric S. Raymond <esr>   07/10/10 13:24:29

Index: files.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/files.texi,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -b -r1.4 -r1.5
--- files.texi  9 Oct 2007 17:49:23 -0000       1.4
+++ files.texi  10 Oct 2007 13:24:29 -0000      1.5
@@ -1465,6 +1465,15 @@
 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 @@
 @node Basic VC Editing
 @subsection Basic Editing under Version Control
 
address@hidden Selecting a fileset
address@hidden Choosing the scope of your command
+
address@hidden 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.
+
address@hidden Doing the next logical thing
address@hidden 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 @@
 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},
address@hidden, @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 @@
 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.
 
address@hidden 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}.
address@hidden 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 @@
 
 @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).
address@hidden 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.
address@hidden 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.
+
address@hidden vc-diff
address@hidden 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 @@
 @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 @@
 then decide not to change it.
 
 @kindex C-x v c
address@hidden vc-cancel-version
address@hidden 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
address@hidden
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Version Headers}).
address@hidden 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 @address@hidden 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.