Commit | Line | Data |
---|---|---|
6f585e44 | 1 | @c This is part of the Emacs manual. |
4e6835db | 2 | @c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. |
6f585e44 EZ |
3 | @c See file emacs.texi for copying conditions. |
4 | @c | |
c5184807 EZ |
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 | |
d5d04ab2 EZ |
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}). | |
c5184807 EZ |
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 | |
123 | typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply | |
124 | to the file name on the current line. | |
125 | ||
126 | The command @kbd{v v} (@code{vc-next-action}) operates on all the | |
127 | marked files, so that you can lock or check in several files at once. | |
128 | If it operates on more than one file, it handles each file according to | |
129 | its current state; thus, it might lock one file, but check in another | |
130 | file. This could be confusing; it is up to you to avoid confusing | |
131 | behavior by marking a set of files that are in a similar state. If no | |
132 | files are marked, @kbd{v v} operates on the file in the current line. | |
133 | ||
134 | If any files call for check-in, @kbd{v v} reads a single log entry, | |
135 | then uses it for all the files being checked in. This is convenient for | |
136 | registering or checking in several files at once, as part of the same | |
137 | change. | |
138 | ||
139 | @findex vc-dired-toggle-terse-mode | |
140 | @findex vc-dired-mark-locked | |
141 | You can toggle between terse display (only locked files, or files not | |
142 | up-to-date) and full display at any time by typing @kbd{v t} | |
143 | (@code{vc-dired-toggle-terse-mode}). There is also a special command | |
144 | @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently | |
145 | locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l | |
146 | t k} is another way to delete from the buffer all files except those | |
147 | currently locked. | |
14831d20 MB |
148 | |
149 | @ignore | |
150 | arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 | |
151 | @end ignore |