More updates for VC documentation.

* doc/emacs/maintaining.texi (VCS Merging, VCS Changesets): Index entries.
(VC Mode Line): Add index entry for "version control status".
(VC Undo): Use vc-revert instead of its vc-revert-buffer alias.
Document vc-revert-show-diff.  De-document vc-rollback.
(VC Directory Mode): Rewrite introduction.  Move prefix arg
documentation here from VC Directory Buffer node.
(VC Directory Buffer): Use a decentralized VCS example.
(VC Directory Commands): Use a table.  Remove material duplicated
in previous nodes on multi-file VC filsets.

diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE
index 23d2bd2b16a9117fb5d090fe96a12560329e56e2..fc36fb6e1d73b2362160aeb69cf08437f133b88e 100644 (file)
--- a/admin/FOR-RELEASE
+++ b/admin/FOR-RELEASE
@@ -61,13 +61,6 @@ sk   Miroslav Vaško
 
 * BUGS
 
 
 * BUGS
 

-** Does deleting frames run Lisp code?  If so, can we get rid of that?
-It is a dangerous design.
-http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01330.html
-
-** Why were the calls to x_fully_uncatch_errors commented out in eval.c?
-http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg01987.html
-

 ** rms: gnus-dired.el is a mistake.  Those features should not
 be part of Gnus.  They should be moved to some other part of Emacs.
 rsteib: Gnus dependencies in `gnus-dired.el' (and `mailcap.el') have been
 ** rms: gnus-dired.el is a mistake.  Those features should not
 be part of Gnus.  They should be moved to some other part of Emacs.
 rsteib: Gnus dependencies in `gnus-dired.el' (and `mailcap.el') have been


@@ -90,25 +83,8 @@ and change key bindings where necessary.  The current list of modes:
    `log-edit-comment-search-forward'.  Perhaps search commands
    on the global key binding `M-s' are useless in these modes.
 
    `log-edit-comment-search-forward'.  Perhaps search commands
    on the global key binding `M-s' are useless in these modes.
 

-** sdl.web@gmail.com, 30 Oct: ps-lpr-switches has no effect
-http://lists.gnu.org/archive/html/emacs-devel/2007-10/msg02091.html
-
-Fixed by this change?
-
-2007-11-09  Vinicius Jose Latorre  <viniciusjl@ig.com.br>
-
-       * ps-print.el: [...]
-       (ps-do-despool): If ps-lpr-switches is not a list, force it to be one.
-
-** In C, use EMACS_INT for variables and structure members
-for buffer/string positions.  E.g. struct it, struct text_pos.
-

 * DOCUMENTATION
 
 * DOCUMENTATION
 

-** Clean up Emacs.app references in code and documentation.
-
-** Document new font backend
-

 ** Document XEmbed support
 
 ** Check the Emacs Tutorial.
 ** Document XEmbed support
 
 ** Check the Emacs Tutorial.


@@ -154,7 +130,7 @@ anti.texi
 arevert-xtra.texi cyd
 basic.texi        cyd
 buffers.texi      cyd
 arevert-xtra.texi cyd
 basic.texi        cyd
 buffers.texi      cyd

-building.texi     
+building.texi     cyd

 calendar.texi     
 cal-xtra.texi     
 cmdargs.texi      
 calendar.texi     
 cal-xtra.texi     
 cmdargs.texi      


@@ -188,13 +164,13 @@ msdog-xtra.texi
 mule.texi         
 m-x.texi          cyd
 picture-xtra.texi
 mule.texi         
 m-x.texi          cyd
 picture-xtra.texi

-programs.texi     
+programs.texi     cyd

 regs.texi         cyd
 rmail.texi        
 screen.texi       cyd
 search.texi       cyd
 sending.texi      
 regs.texi         cyd
 rmail.texi        
 screen.texi       cyd
 search.texi       cyd
 sending.texi      

-text.texi         
+text.texi         cyd

 trouble.texi      
 vc-xtra.texi
 vc1-xtra.texi
 trouble.texi      
 vc-xtra.texi
 vc1-xtra.texi

diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index 20f068e4ef6e06be5fa256a2a2b826d64d7a3db4..90bc9dc8c91241961819d6f99cd178e37f4d455f 100644 (file)
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,15 @@
+2011-12-19  Chong Yidong  <cyd@gnu.org>
+
+       * maintaining.texi (VCS Merging, VCS Changesets): Index entries.
+       (VC Mode Line): Add index entry for "version control status".
+       (VC Undo): Use vc-revert instead of its vc-revert-buffer alias.
+       Document vc-revert-show-diff.  De-document vc-rollback.
+       (VC Directory Mode): Rewrite introduction.  Move prefix arg
+       documentation here from VC Directory Buffer node.
+       (VC Directory Buffer): Use a decentralized VCS example.
+       (VC Directory Commands): Use a table.  Remove material duplicated
+       in previous nodes on multi-file VC filsets.
+

 2011-12-17  Chong Yidong  <cyd@gnu.org>
 
        * maintaining.texi (VCS Concepts): Make "revision" terminology
 2011-12-17  Chong Yidong  <cyd@gnu.org>
 
        * maintaining.texi (VCS Concepts): Make "revision" terminology

diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index 063d0e65f5b5a29957e310b8dfddd68dc6258147..96d520e143c18a260b522dbad89e357bf701a20e 100644 (file)
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -227,17 +227,18 @@ these modes of operation, but it cannot hide the differences.
 
 @node VCS Merging
 @subsubsection Merge-based vs lock-based Version Control
 
 @node VCS Merging
 @subsubsection Merge-based vs lock-based Version Control

-@cindex locking versus merging

 
   A version control system typically has some mechanism to coordinate
 between users who want to change the same file.  There are two ways to
 do this: merging and locking.
 
 
   A version control system typically has some mechanism to coordinate
 between users who want to change the same file.  There are two ways to
 do this: merging and locking.
 

+@cindex merging-based version

   In a version control system that uses merging, each user may modify
 a work file at any time.  The system lets you @dfn{merge} your work
 file, which may contain changes that have not been committed, with the
 latest changes that others have committed.
 
   In a version control system that uses merging, each user may modify
 a work file at any time.  The system lets you @dfn{merge} your work
 file, which may contain changes that have not been committed, with the
 latest changes that others have committed.
 

+@cindex locking-based version

   Older version control systems use a @dfn{locking} scheme instead.
 Here, work files are normally read-only.  To edit a file, you ask the
 version control system to make it writable for you by @dfn{locking}
   Older version control systems use a @dfn{locking} scheme instead.
 Here, work files are normally read-only.  To edit a file, you ask the
 version control system to make it writable for you by @dfn{locking}


@@ -274,7 +275,7 @@ possible.
 @node VCS Changesets
 @subsubsection Changeset-based vs File-based Version Control
 
 @node VCS Changesets
 @subsubsection Changeset-based vs File-based Version Control
 

-@cindex changesets
+@cindex file-based version control

   On SCCS, RCS, CVS, and other early version control systems, version
 control operations are @dfn{file-based}: each file has its own comment
 and revision history separate from that of all other files.  Newer
   On SCCS, RCS, CVS, and other early version control systems, version
 control operations are @dfn{file-based}: each file has its own comment
 and revision history separate from that of all other files.  Newer


@@ -283,6 +284,7 @@ commit may include changes to several files, and the entire set of
 changes is handled as a unit.  Any comment associated with the change
 does not belong to a single file, but to the changeset itself.
 
 changes is handled as a unit.  Any comment associated with the change
 does not belong to a single file, but to the changeset itself.
 

+@cindex changeset-based version control

   Changeset-based version control is more flexible and powerful than
 file-based version control; usually, when a change to multiple files
 has to be reversed, it's good to be able to easily identify and remove
   Changeset-based version control is more flexible and powerful than
 file-based version control; usually, when a change to multiple files
 has to be reversed, it's good to be able to easily identify and remove


@@ -356,20 +358,22 @@ later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
 
 @node VC Mode Line
 @subsection Version Control and the Mode Line
 
 @node VC Mode Line
 @subsection Version Control and the Mode Line

-@cindex VC, mode line indicator
+@cindex VC mode line indicator

 
   When you visit a file that is under version control, Emacs indicates
 this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
 is used for that file, and the current revision ID is 1223.
 
 
   When you visit a file that is under version control, Emacs indicates
 this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
 is used for that file, and the current revision ID is 1223.
 

+@cindex version control status

   The character between the back-end name and the revision ID
   The character between the back-end name and the revision ID

-indicates the status of the work file.  In a merge-based version
-control system, a @samp{-} character indicates that the work file is
-unmodified, and @samp{:} indicates that it has been modified.
-@samp{!} indicates that the file contains conflicts as result of a
-recent merge operation (@pxref{Merging}), or that the file was removed
-from the version control.  Finally, @samp{?}  means that the file is
-under version control, but is missing from the working tree.
+indicates the @dfn{version control status} of the work file.  In a
+merge-based version control system, a @samp{-} character indicates
+that the work file is unmodified, and @samp{:} indicates that it has
+been modified.  @samp{!} indicates that the file contains conflicts as
+result of a recent merge operation (@pxref{Merging}), or that the file
+was removed from the version control.  Finally, @samp{?}  means that
+the file is under version control, but is missing from the working
+tree.

 
   In a lock-based system, @samp{-} indicates an unlocked file, and
 @samp{:} a locked file; if the file is locked by another user (for
 
   In a lock-based system, @samp{-} indicates an unlocked file, and
 @samp{:} a locked file; if the file is locked by another user (for


@@ -399,6 +403,7 @@ system, but is usually not excessive.
 @subsection Basic Editing under Version Control
 
 @cindex filesets, VC
 @subsection Basic Editing under Version Control
 
 @cindex filesets, VC

+@cindex VC filesets

    Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
 collection of one or more files that a VC operation acts on.  When you
 type VC commands in a buffer visiting a version-controlled file, the
    Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
 collection of one or more files that a VC operation acts on.  When you
 type VC commands in a buffer visiting a version-controlled file, the


@@ -451,9 +456,9 @@ and don't persist across sessions.
 @itemize @bullet
 @item
 If there is more than one file in the VC fileset and the files have
 @itemize @bullet
 @item
 If there is more than one file in the VC fileset and the files have

-inconsistent version control states, signal an error.  (Note, however,
-that a fileset is allowed to include both ``newly-added'' files and
-``modified'' files; @pxref{Registering}.)
+inconsistent version control statuses, signal an error.  (Note,
+however, that a fileset is allowed to include both ``newly-added''
+files and ``modified'' files; @pxref{Registering}.)

 
 @item
 If none of the files in the VC fileset are registered with a version
 
 @item
 If none of the files in the VC fileset are registered with a version


@@ -504,7 +509,7 @@ its default mode), @kbd{C-x v v} does the following:
 @itemize @bullet
 @item
 If there is more than one file in the VC fileset and the files have
 @itemize @bullet
 @item
 If there is more than one file in the VC fileset and the files have

-inconsistent version control states, signal an error.
+inconsistent version control statuses, signal an error.

 
 @item
 If each file in the VC fileset is not registered with a version
 
 @item
 If each file in the VC fileset is not registered with a version


@@ -887,7 +892,7 @@ the file contents without distraction from the annotations.
 
 @table @kbd
 @item C-x v l
 
 @table @kbd
 @item C-x v l

-Display revision control state and change history
+Display the change history for the current fileset

 (@code{vc-print-log}).
 
 @item C-x v L
 (@code{vc-print-log}).
 
 @item C-x v L


@@ -927,8 +932,8 @@ this feature).  With a prefix argument, the command prompts for the
 maximum number of revisions to display.
 
   The @kbd{C-x v L} history is shown in a compact form, usually
 maximum number of revisions to display.
 
   The @kbd{C-x v L} history is shown in a compact form, usually

-omitting all but the first line of each log entry.  However, you can
-type @key{RET} (@code{log-view-toggle-entry-display}) in the
+showing only the first line of each log entry.  However, you can type
+@key{RET} (@code{log-view-toggle-entry-display}) in the

 @samp{*vc-change-log*} buffer to reveal the entire log entry for the
 revision at point.  A second @key{RET} hides it again.
 
 @samp{*vc-change-log*} buffer to reveal the entire log entry for the
 revision at point.  A second @key{RET} hides it again.
 


@@ -1008,58 +1013,67 @@ buffer.  However, RCS, SCCS, and CVS do not support this feature.
 
 @table @kbd
 @item C-x v u
 
 @table @kbd
 @item C-x v u

-Revert the buffer and the file to the working revision 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 commit.
+Revert the work file(s) in the current VC fileset to the last revision
+(@code{vc-revert}).

 @end table
 
 @end table
 

+@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific.
+

 @kindex C-x v u
 @kindex C-x v u

-@findex vc-revert-buffer
-  If you want to discard your current set of changes and revert to the
-working revision from which you started editing the file, use @kbd{C-x
-v u} (@code{vc-revert-buffer}).  If the version control system is
-locking-based, this leaves the file unlocked, and you must lock it
-again before making new changes.  @kbd{C-x v u} requires confirmation,
-unless it sees that you haven't made any changes with respect to the
-master copy of the working revision.
-
-  @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-rollback
-  To cancel a change that you already committed, use @kbd{C-x v c}
-(@code{vc-rollback}).  This command discards all record of the most
-recent checked-in revision, but only if your work file corresponds to
-that revision---you cannot use @kbd{C-x v c} to cancel a revision 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.
+@findex vc-revert
+@vindex vc-revert-show-diff
+  If you want to discard all the changes you have made to the current
+VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}).  This shows
+you a diff between the work file(s) and the revision from which you
+started editing, and asks for confirmation for discarding the changes.
+If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
+u} to show a diff, set the variable @code{vc-revert-show-diff} to
+@code{nil} (you can still view the diff directly with @kbd{C-x v =};
+@pxref{Old Revisions}).  Note that @kbd{C-x v u} cannot be reversed
+with the usual undo commands (@pxref{Undo}), so use it with care.
+
+  On locking-based version control systems, @kbd{C-x v u} leaves files
+unlocked; you must lock again to resume editing.  You can also use
+@kbd{C-x v u} to unlock a file if you lock it and then decide not to
+change it.

 
 @node VC Directory Mode
 @subsection VC Directory Mode
 
 
 @node VC Directory Mode
 @subsection VC Directory Mode
 

+@cindex VC Directory buffer
+  The @dfn{VC Directory buffer} is a specialized buffer for viewing
+the version control statuses of the files in a directory tree, and
+performing version control operations on those files.  In particular,
+it is used to specify multi-file VC filesets for commands like
+@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
+

 @kindex C-x v d
 @findex vc-dir
 @kindex C-x v d
 @findex vc-dir

-  When you are working on a large program, it is often useful to find
-out which files have changed within an entire directory tree, or to
-view the status of all files under version control at once, and to
-perform version control operations on collections of files.  You can
-use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory
-listing that includes only files relevant for version control.  This
-creates a @dfn{VC Directory buffer} and displays it in a separate
-window.
+  To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
+This reads a directory name using the minibuffer, and switches to a VC
+Directory buffer for that directory.  By default, the buffer is named
+@samp{*vc-dir*}.  Its contents are described
+@iftex
+below.
+@end iftex
+@ifnottex
+in @ref{VC Directory Buffer}.
+@end ifnottex

 
 

+  The @code{vc-dir} command automatically detects the version control
+system to be used in the specified directory.  In the event that more
+than one system is being used in the directory, you should invoke the
+command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
+the version control system which the VC Directory buffer should use.
+
+@ifnottex

 @cindex PCL-CVS
 @pindex cvs
 @cindex CVS directory mode
 @cindex PCL-CVS
 @pindex cvs
 @cindex CVS directory mode

-  The VC Directory buffer works with all the version control systems
-that VC supports.  For CVS, Emacs also offers a more powerful facility
-called PCL-CVS.  @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
-Emacs Front-End to CVS}.
+  In addition to the VC Directory buffer, Emacs has a similar facility
+called PCL-CVS which is specialized for CVS.  @xref{Top, , About
+PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+@end ifnottex

 
 @menu
 * Buffer: VC Directory Buffer.      What the buffer looks like and means.
 
 @menu
 * Buffer: VC Directory Buffer.      What the buffer looks like and means.


@@ -1070,152 +1084,188 @@ Emacs Front-End to CVS}.
 @subsubsection The VC Directory Buffer
 
   The VC Directory buffer contains a list of version-controlled files
 @subsubsection The VC Directory Buffer
 
   The VC Directory buffer contains a list of version-controlled files

-in the current directory and its subdirectories.  Files which are
-up-to-date (have no local differences from the repository copy) are
-usually hidden; if all files in a subdirectory are up-to-date, the
-subdirectory is hidden as well.  There is an exception to this rule:
-if VC mode detects that a file has changed to an up-to-date state
-since you last looked at it, that file and its state are shown.
-
-  If a directory uses more that one version control system, you can
-select which system to use for the @code{vc-dir} command by invoking
-@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}.
-
-  The line for an individual file shows the version control state of
-the file.  Under RCS and SCCS, the name of the user locking the file
-is shown; under CVS, an abbreviated version of the @samp{cvs status}
-output is used.  Here is an example using CVS:
+and their version control statuses.  It lists files in the current
+directory (the one specified when you called @kbd{C-x v d}) and its
+subdirectories, but only those with a ``noteworthy'' status.  Files
+that are up-to-date (i.e.@: the same as in the repository) are
+omitted.  If all the files in a subdirectory are up-to-date, the
+subdirectory is not listed either.  As an exception, if a file has
+become up-to-date as a direct result of a VC command, it is listed.
+
+  Here is an example of a VC Directory buffer listing:

 
 @smallexample
 @group
 
 @smallexample
 @group

-                       ./
-    modified           file1.c
-    needs-update       file2.c
-    needs-merge        file3.c
+                     ./
+    edited           configure.ac
+*   added            README
+    unregistered     temp.txt
+                     src/
+*   edited           src/main.c

 @end group
 @end smallexample
 
 @noindent
 @end group
 @end smallexample
 
 @noindent

-In this example, @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 committed---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 only
-contacts it when the variable @code{vc-stay-local} (or
-@code{vc-cvs-stay-local}) is @code{nil}
+Two work files have been modified but not committed:
+@file{configure.ac} in the current directory, and @file{foo.c} in the
+@file{src/} subdirectory.  The file named @file{README} has been added
+but is not yet committed, while @file{temp.txt} is not under version
+control (@pxref{Registering}).
+
+The @samp{*} characters next to the entries for @file{README} and
+@file{src/main.c} indicate that the user has marked out these files as
+the current VC fileset

 @iftex
 @iftex

-(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
+(see below).

 @end iftex
 @ifnottex
 @end iftex
 @ifnottex

-(@pxref{CVS Options}).
+(@pxref{VC Directory Commands}).
+@end ifnottex
+
+  The above example is typical for a decentralized version control
+system like Bazaar, Git, or Mercurial.  Other systems can show other
+statuses.  For instance, CVS shows the @samp{needs-update} status if
+the repository has changes that have not been applied to the work
+file.  RCS and SCCS show the name of the user locking a file as its
+status.
+
+@ifnottex
+@vindex vc-stay-local
+@vindex vc-cvs-stay-local
+  On CVS and Subversion, the @code{vc-dir} command normally contacts
+the repository, which may be on a remote machine, to check for
+updates.  If you change the variable @code{vc-stay-local} or
+@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
+Options}), then Emacs avoids contacting a remote repository when
+generating the VC Directory buffer (it will still contact it when
+necessary, e.g.@: when doing a commit).  This may be desirable if you
+are working offline or the network is slow.

 @end ifnottex
 @end ifnottex

-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
-commit 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
 
 @vindex vc-directory-exclusion-list

-  When a VC directory displays subdirectories it omits some that
-should never contain any files under version control.  By default,
-this includes Version Control subdirectories such as @samp{RCS} and
-@samp{CVS}; you can customize this by setting the variable
-@code{vc-directory-exclusion-list}.
+  The VC Directory buffer omits subdirectories listed in the variable
+@code{vc-directory-exclusion-list}.  The default value of this
+variable contains directories that are used internally by version
+control systems.

 
 @node VC Directory Commands
 @subsubsection VC Directory Commands
 
 
 @node VC Directory Commands
 @subsubsection VC Directory Commands
 

-  VC Directory mode has a full set of navigation and marking commands
-for picking out filesets.  Some of these are also available in a
-context menu invoked by @kbd{mouse-2}.
+  Emacs provides several commands for navigating the VC Directory
+buffer, and for ``marking'' files as belonging to the current VC
+fileset.

 
 

-  Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
-move vertically as in other list-browsing modes.  @key{SPC} and
-@key{TAB} behave like down-arrow, and @key{BackTab} behaves like
-up-arrow.
+@table @kbd
+@item n
+@itemx @key{SPC}
+Move point to the next entry (@code{vc-dir-next-line}).

 
 

-  Both @kbd{C-m} and @kbd{f} visit the file on the current
-line.  @kbd{o} visits that file in another window.  @kbd{q} dismisses
-the directory buffer.
+@item p
+Move point to the previous entry (@code{vc-dir-previous-line}).

 
 

-  @kbd{x} hides up-to-date files.
+@item @key{TAB}
+Move to the next directory entry (@code{vc-dir-next-directory}).

 
 

-  @kbd{m} marks the file or directory on the current line.  If the
-region is active, @kbd{m} marks all the files in the region.  There
-are some restrictions when marking: a file cannot be marked if any of
-its parent directories are marked, and a directory cannot be marked if
-any files in it or in its child directories are marked.
+@item S-@key{TAB}
+Move to the previous directory entry
+(@code{vc-dir-previous-directory}).

 
 

-  @kbd{M} marks all the files with the same VC state as the current
-file if the cursor is on a file.  If the cursor is on a directory, it
-marks all child files.  With a prefix argument: marks all files and
-directories.
+@item @key{RET}
+@itemx f
+Visit the file or directory listed on the current line
+(@code{vc-dir-find-file}).

 
 

-  @kbd{u} unmarks the file or directory on the current line.  If the
-region is active, it unmarks all the files in the region.
+@item o
+Visit the file or directory on the current line, in a separate window
+(@code{vc-dir-find-file-other-window}).

 
 

-  @kbd{U} marks all the files with the same VC state as the current file
-if the cursor is on a file.  If the cursor is on a directory, it
-unmarks all child files.  With a prefix argument: unmarks all marked
+@item m
+Mark the file or directory on the current line (@code{vc-dir-mark}),
+putting it in the current VC fileset.  If the region is active, mark
+all files in the region.
+
+A file cannot be marked with this command if it is already in a marked
+directory, or one of its subdirectories.  Similarly, a directory
+cannot be marked with this command if any file in its tree is marked.
+
+@item M
+If point is on a file entry, mark all files with the same status; if
+point is on a directory entry, mark all files in that directory tree
+(@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
+listed files and directories.
+
+@item u
+Unmark the file or directory on the current line.  If the region is
+active, unmark all the files in the region (@code{vc-dir-unmark}).
+
+@item U
+If point is on a file entry, umark all files with the same status; if
+point is on a directory entry, unmark all files in that directory tree
+(@code{vc-dir-unmark-all-files}).  With a prefix argument, unmark all

 files and directories.
 
 files and directories.
 

-  It is possible to do search, search and replace, incremental search,
-and incremental regexp search on multiple files.  These commands will
-work on all the marked files or the current file if nothing is marked.
-If a directory is marked, the files in that directory shown in the VC
-directory buffer will be used.
+@item x
+Hide files with @samp{up-to-date} status
+(@code{vc-dir-hide-up-to-date}).
+
+@item q
+Quit the VC Directory buffer, and bury it (@code{quit-window}).
+@end table
+
+@findex vc-dir-mark
+@findex vc-dir-mark-all-files
+  While in the VC Directory buffer, all the files that you mark with
+@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in
+the current VC fileset.  If you mark a directory entry with @kbd{m},
+all the listed files in that directory tree are in the current VC
+fileset.  The files and directories that belong to the current VC
+fileset are indicated with a @samp{*} character in the VC Directory
+buffer, next to their VC status.  In this way, you can set up a
+multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v
+v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old
+Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
+
+  The VC Directory buffer also defines some single-key shortcuts for
+VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
+@kbd{i}, and @kbd{v}.
+
+  For example, you can commit a set of edited files by opening a VC
+Directory buffer, where the files are listed with the @samp{edited}
+status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
+(@code{vc-next-action}).  If the version control system is
+changeset-based, Emacs will commit the files in a single revision.
+
+  While in the VC Directory buffer, you can also perform search and
+replace on the current VC fileset, with the following commands:

 
 

-  @kbd{S} searches the marked files.
+@table @kbd
+@item S
+Search the fileset (@code{vc-dir-search}).
+
+@item Q
+Do a regular expression query replace on the fileset
+(@code{vc-dir-query-replace-regexp}).

 
 

-  @kbd{Q} does a query replace on the marked files.
+@item M-s a C-s
+Do an incremental search on the fileset (@code{vc-dir-isearch}).

 
 

-  @kbd{M-s a C-s} does an incremental search on the marked files.
+@item M-s a C-M-s
+Do an incremental regular expression search on the fileset
+(@code{vc-dir-isearch-regexp}).
+@end table

 
 

-  @kbd{M-s a C-M-s} does an incremental regular expression search
-on the marked files.
+@noindent
+Apart from acting on multiple files, these commands behave much like
+their single-buffer counterparts (@pxref{Search}).

 
 @cindex stashes in version control
 @cindex shelves in version control
 
 @cindex stashes in version control
 @cindex shelves in version control

-  Commands are also accessible from the VC-dir menu.  Note that some
-VC backends use the VC-dir menu to make available extra,
-backend-specific, commands.  For example, Git and Bazaar allow you to
-manipulate @dfn{stashes} and @dfn{shelves}.  (These provide a
-mechanism to temporarily store uncommitted changes somewhere out of
-the way, and bring them back at a later time.)
-
-  Normal VC commands with the @kbd{C-x v} prefix work in VC directory
-buffers.  Some single-key shortcuts are available as well; @kbd{=},
-@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with
-@kbd{C-x v}.
-
-  The command @kbd{C-x v v} (@code{vc-next-action}) operates on all
-the marked files, so that you can commit several files at once.  If
-the underlying VC supports atomic commits of multiple-file changesets,
-@kbd{C-x v v} with a selected set of modified but not committed files
-will commit all of them at once as a single changeset.
-
-  When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
-files, all of those files must be either in the same state or in
-compatible states (added, modified and removed states are considered
-compatible).  Otherwise it signals an error.  This differs from the
-behavior of older versions of VC, which did not have fileset
-operations and simply did @code{vc-next-action} on each file
-individually.
-
-  If any files are in a state that calls for commit, @kbd{C-x v v} reads a
-single log entry and uses it for the changeset as a whole.  If the
-underling VCS is file- rather than changeset-oriented, the log entry
-will be replicated into the history of each file.
+  The above commands are also available via the menu bar, and via a
+context menu invoked by @kbd{Mouse-2}.  Furthermore, some VC backends
+use the menu to provide extra backend-specific commands.  For example,
+Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
+(where are a way to temporarily put aside uncommitted changes, and
+bring them back at a later time).

 
 @node Branches
 @subsection Multiple Branches of a File
 
 @node Branches
 @subsection Multiple Branches of a File

diff --git a/etc/NEWS b/etc/NEWS
index 7454a4a89a3a46631766f2ac9c273443e1be36c4..65a3b41f5bf3eca255e1c861766f4f32243d250c 100644 (file)
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -849,6 +849,7 @@ the user for specifics, e.g. a merge source.
 
 **** Currently supported for Bzr, Git, and Mercurial.
 
 
 **** Currently supported for Bzr, Git, and Mercurial.
 

++++

 *** New option `vc-revert-show-diff' controls whether `vc-revert'
 shows a diff while querying the user.  It defaults to t.
 
 *** New option `vc-revert-show-diff' controls whether `vc-revert'
 shows a diff while querying the user.  It defaults to t.