annotate doc/emacs/vc1-xtra.texi @ 97312:aa4551463556

(VC Directory Mode): Talk about multiple VC systems.

@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 below 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.  (However, the directory in which @code{vc-dir} was
run will always be shown as @file{./}.)  There is an exception to this
rule: if VC mode detects that a file changed to up-to-date state since
you last looked at it, that state will be shown.

If a directory uses more that one VC systems, the VC system to use for
the vc-dir command can be chosen with a prefix argument,
i.e. @kbd{C-u C-x v d}.

  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
    needs-update       file2.c
    needs-merge        file3.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 by the @kbd{mouse-2} button.

  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.

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

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

  @kbd{u} unmarks the file or directory on the current line.  If the
region is active, it unmarks all the files in the region.

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

  @kbd{S} searches the marked files.

  @kbd{Q} does a query replace on the marked files.

  @kbd{M-s a C-s} does an incremental search on the marked files.

  @kbd{M-s a C-M-s} does an incremental search on the marked files.

  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.

  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 check in 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 a set of files,
it requires that all of those files must be either in the same state or
in compatible states; otherwise it will throw an error (added,
modified and removed states are considered compatible).  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