30.1.10.1 The VC Directory Buffer ¶

The VC Directory buffer contains a list of version-controlled files and their version control statuses. It lists files in the current directory (the one specified when you called C-x v d) and its subdirectories, but only those with a noteworthy status. Files that are up-to-date (i.e., the same as in the repository) are omitted. If all the files in a subdirectory are up-to-date, the subdirectory is not listed either. As an exception, if a file has become up-to-date as a direct result of a VC command, it is listed.

Here is an example of a VC Directory buffer listing:

                     ./
    edited           configure.ac
*   added            README
    unregistered     temp.txt
                     src/
*   edited           src/main.c

Two work files have been modified but not committed: configure.ac in the current directory, and main.c in the src/ subdirectory. The file named README has been added but is not yet committed, while temp.txt is not under version control (see Registering a File for Version Control).

The ‘*’ characters next to the entries for README and src/main.c indicate that the user has marked these files as the current VC fileset (see VC Directory Commands).

The above example is typical for a decentralized version control system like Bazaar, Git, or Mercurial (see Decentralized vs Centralized Repositories). Other systems can show other statuses. For instance, CVS shows the ‘needs-update’ status if the repository has changes that have not been applied to the work file. RCS and SCCS show the name of the user locking a file as its status.

On CVS, the vc-dir command normally contacts the repository, which may be on a remote machine, to check for updates. If you change the variable vc-cvs-stay-local to nil (see Options specific for CVS), then Emacs avoids contacting a remote repository when generating the VC Directory buffer (it will still contact it when necessary, e.g., when doing a commit). This may be desirable if you are working offline or the network is slow.

The VC Directory buffer omits subdirectories listed in the variable vc-directory-exclusion-list. Its default value contains directories that are used internally by version control systems.

At the top of the buffer Emacs displays some information about the repository, such as the name of the backend in use and the working directory. In addition, for decentralized VCS, if you have outgoing commits (see VC Change Log), Emacs displays a line "Outgoing : N unpushed revisions" where N is a number. You can click on this text to execute the vc-log-outgoing command (see VC Change Log).

Emacs tries to use cached information to determine the number of unpushed revisions, but for some backends this isn’t possible. In these cases Emacs must occasionally fetch from the remote repository in order to determine the count. If your connection to the remote repository is slow then this may cause unacceptable slowdowns in refreshing the VC Directory buffer. If this affects you, you can customize vc-dir-show-outgoing-count to nil to disable the unpushed revisions count altogether. You can also set this on a per-repository basis using directory local variables (see Per-Directory Local Variables).