annotate doc/emacs/vc1-xtra.texi @ 97109:20a9ca33d937

(VC Directory Mode): Update the display format and fix the vc-dir command name.

@c This is part of the Emacs manual.
@c Copyright (C) 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@c
@c This file is included either in vc-xtra.texi (when producing the
@c printed version) or in the main Emacs manual (for the on-line version).
@node VC Directory Mode
@subsection VC Directory Mode

@cindex PCL-CVS
@pindex cvs
@cindex CVS directory mode
  The VC directory mode described here works with all the version control
systems that VC supports.  Another more powerful facility, designed
specifically for CVS, is called PCL-CVS.  @xref{Top, , About PCL-CVS,
pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.

@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.

  @kbd{C-x v d} creates a buffer which uses VC directory mode. This 
buffer will contain a listing of version-controlled files beneath
the current directory, and their containing directories.  Files
which are up-to-date (have no local differences from the repository
copy) will be omitted; if all files in a directory are up-to-date,
the directory will be omitted as well.  But there is an exception; 
if VC mode detects that a file changed to up-to-date state since your
last look at it, that state will be shown.

  The line for an individual file will show 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 RCS:

  Here is an example using CVS:

@smallexample
@group
                       ./
    modified           file1.c
    update             file2.c
@end group
@end smallexample

  Here @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 checked in to the repository---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 would
only contact it when the variable @code{vc-stay-local} (or
@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  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
check-in 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
  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}.

@node VC Directory Commands
@subsection 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 with the right mouse button.

  Up and down-arrow keys move in the buffer; @kbd{n} and @kbd{p}  also
move vertically as in other list-browsing modes.  @kbd{SPC} and
@kbd{TAB} behave like down-arrow, and the back-tab behaves like up-arrow.

  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.

  @kbd{x} toggles hiding of up-to-date files.

  @kbd{m} marks the file on the current line.  @kbd{M} marks all
files. @kbd{u} marks the file on the current line.  @kbd{U} unmarks all
files.

  Normal VC command with the @kbd{C-x v} prefix work in 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 lock or check in several files at once.
If the underlying VC supports atomic commits of multiple-file
changesets @kbd{v v} with a selected set of modified but not committed 
files wuill commit all of them at once as a single changeset.

  When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files,
it requires that all of those files must be in the same state;
otherwise it will throw an error.  Note that 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.

@ignore
   arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263
@end ignore