Dired under VC
--------------

The VC Dired 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 Dired Mode.  This looks much like an ordinary Dired buffer (see Dired); however, normally it shows only the noteworthy files (those locked or not up-to-date).  This is called terse display.  If you set the variable vc-dired-terse-display to nil, then VC Dired shows all relevant files---those managed under version control, plus all subdirectories (full display).  The command v t in a VC Dired buffer toggles between terse display and full display (see VC Dired Commands).

By default, VC Dired produces a recursive listing of noteworthy or relevant files at or below the given directory.  You can change this by setting the variable vc-dired-recurse to nil; then VC Dired shows only the files in the given directory.

The line for an individual file shows the version control state in the place of the hard link count, owner, group, and size of the file.  If the file is unmodified, in sync with the master file, the version control state shown is blank.  Otherwise it consists of text in parentheses.  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:

       /home/jim/project:

       -rw-r--r-- (jim)      Apr  2 23:39 file1
       -r--r--r--            Apr  5 20:21 file2

The files file1 and file2 are under version control, file1 is locked by user jim, and file2 is unlocked.

Here is an example using CVS:

       /home/joe/develop:

       -rw-r--r-- (modified) Aug  2  1997 file1.c
       -rw-r--r--            Apr  4 20:09 file2.c
       -rw-r--r-- (merge)    Sep 13  1996 file3.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 VC Dired displays subdirectories (in the ``full'' display mode), 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.

You can fine-tune VC Dired's format by typing C-u C-x v d---as in ordinary Dired, that allows you to specify additional switches for the ls command.

VC Dired Commands
-----------------

All the usual Dired commands work normally in VC Dired mode, except for v, which is redefined as the version control prefix.  You can invoke VC commands such as vc-diff and vc-print-log by typing v =, or v l, and so on.  These commands will apply to the set of files you have marked for operation in the VC-Dired buffer.

The command 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 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, 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.

You can toggle between terse display (only locked files, or files not up-to-date) and full display at any time by typing v t (vc-dired-toggle-terse-mode).  There is also a special command * l (vc-dired-mark-locked), which marks all files currently locked (or, with CVS, all files not up-to-date).  Thus, typing * l t k is another way to delete from the buffer all files except those currently locked.