VC 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.  See About PCL-CVS (PCL-CVS --- The Emacs Front-End to CVS).

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 C-x v d (vc-directory) to make a directory listing that includes only files relevant for version control.

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 cvs status output is used.  Here is an example using RCS:

Here is an example using CVS:

         DIRECTORY            ./
         edited               file1.c
         up-to-date           file2.c

Here file1.c is modified with respect to the repository, and file2.c is not.  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.

In the above, if the repository were on a remote machine, VC would only contact it when the variable vc-stay-local (or vc-cvs-stay-local) is nil (see 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 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 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.

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 RCS and CVS; you can customize this by setting the variable vc-directory-exclusion-list.

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; n and p  also move vertically as in other list-browsing modes.  SPC and TAB behave like down-arrow, and the back-tab behaves like up-arrow.

Both C-m and f visit the file on the current line. o visits that file in another window.  q dismisses the directory buffer.

x toggles hiding of up-to-date files.

m marks the file on the current line.  M marks all files. u marks the file on the current line.  U unmarks all files.

Normal VC command with the C-x v prefix work in directory buffers.  Some single-key shortcuts are available as well; =, +, l, i, and v behave as through prefixed with C-x v.

The command C-x v v (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 v v with a selected set of modified but not committed files wuill commit all of them at once as a single changeset.

When C-x v v (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 vc-next-action on each file individually.

If any files are in a state that calls for commit, 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.