32.1.7.1 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 vc-dir command by invoking vc-dir with a prefix argument: 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 ‘cvs status’ output is used. Here is an example using CVS:

                            ./
         modified           file1.c
         needs-update       file2.c
         needs-merge        file3.c

In this example, ‘file1.c’ is modified with respect to the repository, and ‘file2.c’ is not. ‘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.

In the above, if the repository were on a remote machine, VC only contacts 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.