28.1.10 VC Directory Mode

The VC Directory buffer is a specialized buffer for viewing the version control statuses of the files in a directory tree, and performing version control operations on those files. In particular, it is used to specify multi-file VC filesets for commands like C-x v v to act on (see VC Directory Commands).

To use the VC Directory buffer, type C-x v d (vc-dir). This reads a directory’s name using the minibuffer, and switches to a VC Directory buffer for that directory. By default, the buffer is named *vc-dir*. Its contents are described in VC Directory Buffer.

The vc-dir command automatically detects the version control system to be used in the specified directory. In the event that more than one system is being used in the directory, you should invoke the command with a prefix argument, C-u C-x v d; this prompts for the version control system which the VC Directory buffer should use.

In addition to the VC Directory buffer, Emacs has a similar facility called PCL-CVS which is specialized for CVS. See About PCL-CVS in PCL-CVS—The Emacs Front-End to CVS.

• Buffer		What the buffer looks like and means.
• Commands		Commands to use in a VC directory buffer.

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

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. 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 CVS Options), 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.

28.1.10.2 VC Directory Commands

Emacs provides several commands for navigating the VC Directory buffer, and for marking files as belonging to the current VC fileset.

n

SPC

Move point to the next entry (vc-dir-next-line).

p

Move point to the previous entry (vc-dir-previous-line).

TAB

Move to the next directory entry (vc-dir-next-directory).

S-TAB

Move to the previous directory entry (vc-dir-previous-directory).

RET

f

Visit the file or directory listed on the current line (vc-dir-find-file).

o

Visit the file or directory on the current line, in a separate window (vc-dir-find-file-other-window).

m

Mark the file or directory on the current line (vc-dir-mark), putting it in the current VC fileset. If the region is active, mark all files in the region.

A file cannot be marked with this command if it is already in a marked directory, or one of its subdirectories. Similarly, a directory cannot be marked with this command if any file in its tree is marked.

M

If point is on a file entry, mark all files with the same status; if point is on a directory entry, mark all files in that directory tree (vc-dir-mark-all-files). With a prefix argument, mark all listed files and directories.

G

Add the file under point to the list of files that the VC should ignore (vc-dir-ignore). For instance, if the VC is Git, it will append this file to the .gitignore file. If given a prefix, do this with all the marked files.

q

Quit the VC Directory buffer, and bury it (quit-window).

u

Unmark the file or directory on the current line. If the region is active, unmark all the files in the region (vc-dir-unmark).

U

If point is on a file entry, unmark all files with the same status; if point is on a directory entry, unmark all files in that directory tree (vc-dir-unmark-all-files). With a prefix argument, unmark all files and directories.

x

Hide files with ‘up-to-date’ or ‘ignored’ status (vc-dir-hide-up-to-date). With a prefix argument, hide items whose state is that of the item at point.

While in the VC Directory buffer, all the files that you mark with m (vc-dir-mark) or M (vc-dir-mark-all-files) are in the current VC fileset. If you mark a directory entry with m, all the listed files in that directory tree are in the current VC fileset. The files and directories that belong to the current VC fileset are indicated with a ‘*’ character in the VC Directory buffer, next to their VC status. In this way, you can set up a multi-file VC fileset to be acted on by VC commands like C-x v v (see Basic VC Editing), C-x v = (see Old Revisions), and C-x v u (see VC Undo).

The VC Directory buffer also defines some single-key shortcuts for VC commands with the C-x v prefix: =, +, l, i, D, L, G, I, O, and v.

For example, you can commit a set of edited files by opening a VC Directory buffer, where the files are listed with the ‘edited’ status; marking the files; and typing v or C-x v v (vc-next-action). If the version control system is changeset-based, Emacs will commit the files in a single revision.

While in the VC Directory buffer, you can also perform search and replace on the current VC fileset, with the following commands:

S

Search the fileset (vc-dir-search).

Q

Do a regular expression query replace on the fileset (vc-dir-query-replace-regexp).

M-s a C-s

Do an incremental search on the fileset (vc-dir-isearch).

M-s a C-M-s

Do an incremental regular expression search on the fileset (vc-dir-isearch-regexp).

Apart from acting on multiple files, these commands behave much like their single-buffer counterparts (see Search).

The VC Directory buffer additionally defines some branch-related commands starting with the prefix B:

B c

Create a new branch (vc-create-tag).

B l

Prompt for the name of a branch and display the change history of that branch (vc-print-branch-log).

B s

Switch to a branch (vc-retrieve-tag). See Switching Branches.

d

Delete the marked files, or the current file if no marks (vc-dir-clean-delete). The files will not be marked as deleted in the version control system, so this function is mostly useful for unregistered files.

The above commands are also available via the menu bar, and via a context menu invoked by mouse-2. Furthermore, some VC backends use the menu to provide extra backend-specific commands. For example, Git and Bazaar allow you to manipulate stashes and shelves (which are a way to temporarily put aside uncommitted changes, and bring them back at a later time).