1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2004, 2005, 2006 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
5 @c This file is included either in vc-xtra.texi (when producing the
6 @c printed version) or in the main Emacs manual (for the on-line version).
8 @subsection Dired under VC
12 @cindex CVS Dired Mode
13 The VC Dired Mode described here works with all the version control
14 systems that VC supports. Another more powerful facility, designed
15 specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS,
16 pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
20 When you are working on a large program, it is often useful to find
21 out which files have changed within an entire directory tree, or to view
22 the status of all files under version control at once, and to perform
23 version control operations on collections of files. You can use the
24 command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
25 that includes only files relevant for version control.
27 @vindex vc-dired-terse-display
28 @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks
29 much like an ordinary Dired buffer (@pxref{Dired,,,emacs, the
30 Emacs Manual}); however, normally it shows only the noteworthy files
31 (those locked or not up-to-date). This is called @dfn{terse display}.
32 If you set the variable @code{vc-dired-terse-display} to @code{nil},
33 then VC Dired shows all relevant files---those managed under version
34 control, plus all subdirectories (@dfn{full display}). The command
35 @kbd{v t} in a VC Dired buffer toggles between terse display and full
36 display (@pxref{VC Dired Commands}).
38 @vindex vc-dired-recurse
39 By default, VC Dired produces a recursive listing of noteworthy or
40 relevant files at or below the given directory. You can change this by
41 setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
42 Dired shows only the files in the given directory.
44 The line for an individual file shows the version control state in the
45 place of the hard link count, owner, group, and size of the file. If
46 the file is unmodified, in sync with the master file, the version
47 control state shown is blank. Otherwise it consists of text in
48 parentheses. Under RCS and SCCS, the name of the user locking the file
49 is shown; under CVS, an abbreviated version of the @samp{cvs status}
50 output is used. Here is an example using RCS:
56 -rw-r--r-- (jim) Apr 2 23:39 file1
57 -r--r--r-- Apr 5 20:21 file2
62 The files @samp{file1} and @samp{file2} are under version control,
63 @samp{file1} is locked by user jim, and @samp{file2} is unlocked.
65 Here is an example using CVS:
71 -rw-r--r-- (modified) Aug 2 1997 file1.c
72 -rw-r--r-- Apr 4 20:09 file2.c
73 -rw-r--r-- (merge) Sep 13 1996 file3.c
77 Here @samp{file1.c} is modified with respect to the repository, and
78 @samp{file2.c} is not. @samp{file3.c} is modified, but other changes
79 have also been checked in to the repository---you need to merge them
80 with the work file before you can check it in.
83 @vindex vc-cvs-stay-local
84 In the above, if the repository were on a remote machine, VC would
85 only contact it when the variable @code{vc-stay-local} (or
86 @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is
87 because access to the repository may be slow, or you may be working
88 offline and not have access to the repository at all. As a
89 consequence, VC would not be able to tell you that @samp{file3.c} is
90 in the ``merge'' state; you would learn that only when you try to
91 check-in your modified copy of the file, or use a command such as
94 In practice, this is not a problem because CVS handles this case
95 consistently whenever it arises. In VC, you'll simply get prompted to
96 merge the remote changes into your work file first. The benefits of
97 less network communication usually outweigh the disadvantage of not
98 seeing remote changes immediately.
100 @vindex vc-directory-exclusion-list
101 When VC Dired displays subdirectories (in the ``full'' display mode),
102 it omits some that should never contain any files under version control.
103 By default, this includes Version Control subdirectories such as
104 @samp{RCS} and @samp{CVS}; you can customize this by setting the
105 variable @code{vc-directory-exclusion-list}.
107 You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
108 ordinary Dired, that allows you to specify additional switches for the
111 @node VC Dired Commands
112 @subsection VC Dired Commands
114 All the usual Dired commands work normally in VC Dired mode, except
115 for @kbd{v}, which is redefined as the version control prefix. You can
116 invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
117 typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply
118 to the file name on the current line.
120 The command @kbd{v v} (@code{vc-next-action}) operates on all the
121 marked files, so that you can lock or check in several files at once.
122 If it operates on more than one file, it handles each file according to
123 its current state; thus, it might lock one file, but check in another
124 file. This could be confusing; it is up to you to avoid confusing
125 behavior by marking a set of files that are in a similar state. If no
126 files are marked, @kbd{v v} operates on the file in the current line.
128 If any files call for check-in, @kbd{v v} reads a single log entry,
129 then uses it for all the files being checked in. This is convenient for
130 registering or checking in several files at once, as part of the same
133 @findex vc-dired-toggle-terse-mode
134 @findex vc-dired-mark-locked
135 You can toggle between terse display (only locked files, or files not
136 up-to-date) and full display at any time by typing @kbd{v t}
137 (@code{vc-dired-toggle-terse-mode}). There is also a special command
138 @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
139 locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l
140 t k} is another way to delete from the buffer all files except those
144 arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263