From da1080a25c39c8f8fd1f73edcffed10d409a934f Mon Sep 17 00:00:00 2001 From: "Eric S. Raymond" Date: Wed, 10 Oct 2007 13:24:29 +0000 Subject: [PATCH] New VC command docs for the Emacs manual. --- doc/emacs/ChangeLog | 7 ++- doc/emacs/files.texi | 143 +++++++++++++++++++++++++++++++-------------------- 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 + + * files.texi (Version Systems): Merge in changes for new VC + with fileset-orienrted operations. + 2007-10-09 Eric S. Raymond - * 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 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. -- 2.11.4.GIT