Commit | Line | Data |
---|---|---|
8cf51b2c GM |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. | |
3 | @c See file emacs.texi for copying conditions. | |
4 | @c | |
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). | |
7 | @node VC Dired Mode | |
8 | @subsection Dired under VC | |
9 | ||
10 | @cindex PCL-CVS | |
11 | @pindex cvs | |
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}. | |
17 | ||
18 | @kindex C-x v d | |
19 | @findex vc-directory | |
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. | |
26 | ||
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 | |
30 | @iftex | |
31 | (@pxref{Dired,,,emacs, the Emacs Manual}); | |
32 | @end iftex | |
33 | @ifnottex | |
34 | (@pxref{Dired}); | |
35 | @end ifnottex | |
36 | however, normally it shows only the noteworthy files (those locked or | |
37 | not up-to-date). This is called @dfn{terse display}. If you set the | |
38 | variable @code{vc-dired-terse-display} to @code{nil}, then VC Dired | |
39 | shows all relevant files---those managed under version control, plus | |
40 | all subdirectories (@dfn{full display}). The command @kbd{v t} in a | |
41 | VC Dired buffer toggles between terse display and full display | |
42 | (@pxref{VC Dired Commands}). | |
43 | ||
44 | @vindex vc-dired-recurse | |
45 | By default, VC Dired produces a recursive listing of noteworthy or | |
46 | relevant files at or below the given directory. You can change this by | |
47 | setting the variable @code{vc-dired-recurse} to @code{nil}; then VC | |
48 | Dired shows only the files in the given directory. | |
49 | ||
50 | The line for an individual file shows the version control state in the | |
51 | place of the hard link count, owner, group, and size of the file. If | |
52 | the file is unmodified, in sync with the master file, the version | |
53 | control state shown is blank. Otherwise it consists of text in | |
54 | parentheses. Under RCS and SCCS, the name of the user locking the file | |
55 | is shown; under CVS, an abbreviated version of the @samp{cvs status} | |
56 | output is used. Here is an example using RCS: | |
57 | ||
58 | @smallexample | |
59 | @group | |
60 | /home/jim/project: | |
61 | ||
62 | -rw-r--r-- (jim) Apr 2 23:39 file1 | |
63 | -r--r--r-- Apr 5 20:21 file2 | |
64 | @end group | |
65 | @end smallexample | |
66 | ||
67 | @noindent | |
68 | The files @samp{file1} and @samp{file2} are under version control, | |
69 | @samp{file1} is locked by user jim, and @samp{file2} is unlocked. | |
70 | ||
71 | Here is an example using CVS: | |
72 | ||
73 | @smallexample | |
74 | @group | |
75 | /home/joe/develop: | |
76 | ||
77 | -rw-r--r-- (modified) Aug 2 1997 file1.c | |
78 | -rw-r--r-- Apr 4 20:09 file2.c | |
79 | -rw-r--r-- (merge) Sep 13 1996 file3.c | |
80 | @end group | |
81 | @end smallexample | |
82 | ||
83 | Here @samp{file1.c} is modified with respect to the repository, and | |
84 | @samp{file2.c} is not. @samp{file3.c} is modified, but other changes | |
85 | have also been checked in to the repository---you need to merge them | |
86 | with the work file before you can check it in. | |
87 | ||
88 | @vindex vc-stay-local | |
89 | @vindex vc-cvs-stay-local | |
90 | In the above, if the repository were on a remote machine, VC would | |
91 | only contact it when the variable @code{vc-stay-local} (or | |
92 | @code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is | |
93 | because access to the repository may be slow, or you may be working | |
94 | offline and not have access to the repository at all. As a | |
95 | consequence, VC would not be able to tell you that @samp{file3.c} is | |
96 | in the ``merge'' state; you would learn that only when you try to | |
97 | check-in your modified copy of the file, or use a command such as | |
98 | @kbd{C-x v m}. | |
99 | ||
100 | In practice, this is not a problem because CVS handles this case | |
101 | consistently whenever it arises. In VC, you'll simply get prompted to | |
102 | merge the remote changes into your work file first. The benefits of | |
103 | less network communication usually outweigh the disadvantage of not | |
104 | seeing remote changes immediately. | |
105 | ||
106 | @vindex vc-directory-exclusion-list | |
107 | When VC Dired displays subdirectories (in the ``full'' display mode), | |
108 | it omits some that should never contain any files under version control. | |
109 | By default, this includes Version Control subdirectories such as | |
110 | @samp{RCS} and @samp{CVS}; you can customize this by setting the | |
111 | variable @code{vc-directory-exclusion-list}. | |
112 | ||
113 | You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in | |
114 | ordinary Dired, that allows you to specify additional switches for the | |
115 | @samp{ls} command. | |
116 | ||
117 | @node VC Dired Commands | |
118 | @subsection VC Dired Commands | |
119 | ||
120 | All the usual Dired commands work normally in VC Dired mode, except | |
121 | for @kbd{v}, which is redefined as the version control prefix. You can | |
122 | invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by | |
0870a421 ER |
123 | typing @kbd{v =}, or @kbd{v l}, and so on. These commands will apply |
124 | to the set of files you have marked for operation in the VC-Dired | |
125 | buffer. | |
8cf51b2c GM |
126 | |
127 | The command @kbd{v v} (@code{vc-next-action}) operates on all the | |
128 | marked files, so that you can lock or check in several files at once. | |
0870a421 ER |
129 | If the underlying VC supports atomic commits of multiple-file |
130 | changesets @kbd{v v} with a selected set of modified but not committed | |
131 | files wuill commit all of them at once as a single changeset. | |
132 | ||
133 | When @kbd{v v} (@code{vc-next-action}) operates on a set of files, | |
134 | it requires that all of those files must be in the same state; | |
135 | otherwise it will throw an error. Note that this differs from the | |
136 | behavior of older versions of VC, which did not have fileset | |
137 | operations and simply did @code{vc-next-action} on each file | |
138 | individually. | |
139 | ||
140 | If any files are in a state that calls for commit, @kbd{v v} reads a | |
141 | single log entry and uses it for the changeset as a whole. If the | |
142 | underling VCS is file- rather than changeset-oriented, the log entry | |
143 | will be replicated into the history of each file. | |
8cf51b2c GM |
144 | |
145 | @findex vc-dired-toggle-terse-mode | |
146 | @findex vc-dired-mark-locked | |
147 | You can toggle between terse display (only locked files, or files not | |
148 | up-to-date) and full display at any time by typing @kbd{v t} | |
149 | (@code{vc-dired-toggle-terse-mode}). There is also a special command | |
150 | @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently | |
151 | locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l | |
152 | t k} is another way to delete from the buffer all files except those | |
153 | currently locked. | |
154 | ||
155 | @ignore | |
156 | arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 | |
157 | @end ignore |