Commit | Line | Data |
---|---|---|
8cf51b2c | 1 | @c This is part of the Emacs manual. |
ab422c4d | 2 | @c Copyright (C) 2004-2013 Free Software Foundation, Inc. |
8cf51b2c GM |
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). | |
8cf51b2c | 7 | |
1ab2e8ba CY |
8 | @node Miscellaneous VC |
9 | @subsection Miscellaneous Commands and Features of VC | |
10 | ||
11 | This section explains the less-frequently-used features of VC. | |
12 | ||
13 | @menu | |
14 | * Change Logs and VC:: Generating a change log file from log entries. | |
3d992aa0 | 15 | * VC Delete/Rename:: Deleting and renaming version-controlled files. |
d3098e1e | 16 | * Revision Tags:: Symbolic names for revisions. |
1ab2e8ba CY |
17 | * Version Headers:: Inserting version control headers into working files. |
18 | @end menu | |
19 | ||
20 | @node Change Logs and VC | |
21 | @subsubsection Change Logs and VC | |
22 | ||
d3098e1e | 23 | If you use RCS or CVS for a program with a @file{ChangeLog} file |
1ab2e8ba CY |
24 | @iftex |
25 | (@pxref{Change Log,,,emacs, the Emacs Manual}), | |
26 | @end iftex | |
27 | @ifnottex | |
28 | (@pxref{Change Log}), | |
29 | @end ifnottex | |
d3098e1e CY |
30 | you can generate change log entries from the version control log |
31 | entries of previous commits. | |
32 | ||
1df7defd | 33 | Note that this only works with RCS or CVS@. This procedure would be |
d3098e1e CY |
34 | particularly incorrect on a modern changeset-based version control |
35 | system, where changes to the @file{ChangeLog} file would normally be | |
36 | committed as part of a changeset. In that case, you should write the | |
37 | change log entries first, then pull them into the @samp{*vc-log*} | |
38 | buffer when you commit | |
39 | @iftex | |
40 | (@pxref{Log Buffer,,,emacs, the Emacs Manual}). | |
41 | @end iftex | |
42 | @ifnottex | |
43 | (@pxref{Log Buffer}). | |
44 | @end ifnottex | |
1ab2e8ba CY |
45 | |
46 | @table @kbd | |
47 | @item C-x v a | |
48 | @kindex C-x v a | |
49 | @findex vc-update-change-log | |
d3098e1e CY |
50 | Visit the current directory's @file{ChangeLog} file and, for |
51 | registered files in that directory, create new entries for versions | |
52 | committed since the most recent change log entry | |
1ab2e8ba CY |
53 | (@code{vc-update-change-log}). |
54 | ||
1ab2e8ba CY |
55 | @item C-u C-x v a |
56 | As above, but only find entries for the current buffer's file. | |
1ab2e8ba CY |
57 | @end table |
58 | ||
59 | For example, suppose the first line of @file{ChangeLog} is dated | |
60 | 1999-04-10, and that the only check-in since then was by Nathaniel | |
d3098e1e CY |
61 | Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore |
62 | log messages that start with `#'.}. Then @kbd{C-x v a} inserts this | |
63 | @file{ChangeLog} entry: | |
1ab2e8ba CY |
64 | |
65 | @iftex | |
66 | @medbreak | |
67 | @end iftex | |
8cf51b2c GM |
68 | @smallexample |
69 | @group | |
1ab2e8ba CY |
70 | 1999-05-22 Nathaniel Bowditch <nat@@apn.org> |
71 | ||
72 | * rcs2log: Ignore log messages that start with `#'. | |
8cf51b2c GM |
73 | @end group |
74 | @end smallexample | |
1ab2e8ba CY |
75 | @iftex |
76 | @medbreak | |
77 | @end iftex | |
78 | ||
79 | @noindent | |
d3098e1e CY |
80 | If the version control log entry specifies a function name (in |
81 | parenthesis at the beginning of a line), that is reflected in the | |
82 | @file{ChangeLog} entry. For example, if a log entry for @file{vc.el} | |
83 | is @samp{(vc-do-command): Check call-process status.}, the | |
84 | @file{ChangeLog} entry is: | |
1ab2e8ba CY |
85 | |
86 | @iftex | |
87 | @medbreak | |
88 | @end iftex | |
89 | @smallexample | |
90 | @group | |
91 | 1999-05-06 Nathaniel Bowditch <nat@@apn.org> | |
92 | ||
93 | * vc.el (vc-do-command): Check call-process status. | |
94 | @end group | |
95 | @end smallexample | |
96 | @iftex | |
97 | @medbreak | |
98 | @end iftex | |
99 | ||
d3098e1e CY |
100 | When @kbd{C-x v a} adds several change log entries at once, it |
101 | groups related log entries together if they all are checked in by the | |
102 | same author at nearly the same time. If the log entries for several | |
103 | such files all have the same text, it coalesces them into a single | |
104 | entry. | |
1ab2e8ba | 105 | |
3d992aa0 CY |
106 | @node VC Delete/Rename |
107 | @subsubsection Deleting and Renaming Version-Controlled Files | |
d3098e1e | 108 | @cindex renaming version-controlled files |
1ab2e8ba | 109 | |
d3098e1e | 110 | @table @kbd |
3d992aa0 CY |
111 | @item M-x vc-delete-file |
112 | Prompt for a file name, delete the file from the working tree, and | |
113 | schedule the deletion for committing. | |
114 | ||
d3098e1e | 115 | @item M-x vc-rename-file |
3d992aa0 CY |
116 | Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the |
117 | working tree, and schedule the renaming for committing. | |
d3098e1e | 118 | @end table |
1ab2e8ba | 119 | |
3d992aa0 CY |
120 | @findex vc-delete-file |
121 | If you wish to delete a version-controlled file, use the command | |
122 | @kbd{M-x vc-delete-file}. This prompts for the file name, and deletes | |
123 | it via the version control system. The file is removed from the | |
124 | working tree, and in the VC Directory buffer | |
125 | @iftex | |
5f9756ec | 126 | (@pxref{VC Directory Mode,,, emacs, the Emacs Manual}), |
3d992aa0 CY |
127 | @end iftex |
128 | @ifnottex | |
129 | (@pxref{VC Directory Mode}), | |
130 | @end ifnottex | |
131 | it is displayed with the @samp{removed} status. When you commit it, | |
132 | the deletion takes effect in the repository. | |
d3098e1e | 133 | |
3d992aa0 CY |
134 | @findex vc-rename-file |
135 | To rename a version-controlled file, type @kbd{M-x vc-rename-file}. | |
136 | This prompts for two arguments: the name of the file you wish to | |
137 | rename, and the new name; then it performs the renaming via the | |
138 | version control system. The renaming takes effect immediately in the | |
d3098e1e | 139 | working tree, and takes effect in the repository when you commit the |
3d992aa0 | 140 | renamed file. |
d3098e1e | 141 | |
3d992aa0 CY |
142 | On modern version control systems that have built-in support for |
143 | renaming, the renamed file retains the full change history of the | |
144 | original file. On CVS and older version control systems, the | |
145 | @code{vc-rename-file} command actually works by creating a copy of the | |
146 | old file under the new name, registering it, and deleting the old | |
147 | file. In this case, the change history is not preserved. | |
1ab2e8ba | 148 | |
d3098e1e CY |
149 | @node Revision Tags |
150 | @subsubsection Revision Tags | |
151 | @cindex revision tag | |
152 | @cindex tags for version control | |
1ab2e8ba | 153 | |
d3098e1e CY |
154 | Most version control systems allow you to apply a @dfn{revision tag} |
155 | to a specific version of a version-controlled tree. On modern | |
156 | changeset-based version control systems, a revision tag is simply a | |
157 | symbolic name for a particular revision. On older file-based systems | |
158 | like CVS, each tag is added to the entire set of version-controlled | |
159 | files, allowing them to be handled as a unit. Revision tags are | |
160 | commonly used to identify releases that are distributed to users. | |
1ab2e8ba | 161 | |
d3098e1e CY |
162 | There are two basic commands for tags; one makes a tag with a given |
163 | name, the other retrieves a named tag. | |
1ab2e8ba | 164 | |
d3098e1e CY |
165 | @table @code |
166 | @kindex C-x v s | |
167 | @findex vc-create-tag | |
168 | @item C-x v s @var{name} @key{RET} | |
169 | Define the working revision of every registered file in or under the | |
170 | current directory as a tag named @var{name} | |
171 | (@code{vc-create-tag}). | |
1ab2e8ba | 172 | |
d3098e1e CY |
173 | @kindex C-x v r |
174 | @findex vc-retrieve-tag | |
175 | @item C-x v r @var{name} @key{RET} | |
176 | For all registered files at or below the current directory level, | |
177 | retrieve the tagged revision @var{name}. This command will switch to a | |
178 | branch if @var{name} is a branch name and your VCS distinguishes | |
179 | branches from tags. (@code{vc-retrieve-tag}). | |
1ab2e8ba | 180 | |
d3098e1e CY |
181 | This command reports an error if any files are locked at or below the |
182 | current directory, without changing anything; this is to avoid | |
183 | overwriting work in progress. | |
184 | @end table | |
1ab2e8ba | 185 | |
d3098e1e CY |
186 | You can give a tag or branch name as an argument to @kbd{C-x v =} or |
187 | @kbd{C-x v ~} | |
1ab2e8ba | 188 | @iftex |
d3098e1e | 189 | (@pxref{Old Revisions,,,emacs, the Emacs Manual}). |
1ab2e8ba | 190 | @end iftex |
d3098e1e CY |
191 | @ifnottex |
192 | (@pxref{Old Revisions}). | |
193 | @end ifnottex | |
194 | Thus, you can use it to compare a tagged version against the current files, | |
195 | or two tagged versions against each other. | |
1ab2e8ba | 196 | |
d3098e1e | 197 | On SCCS, VC implements tags itself; these tags are visible only |
1df7defd | 198 | through VC@. Most later systems (including CVS, Subversion, bzr, git, |
d3098e1e CY |
199 | and hg) have a native tag facility, and VC uses it where available; |
200 | those tags will be visible even when you bypass VC. | |
1ab2e8ba | 201 | |
2bc4a725 XF |
202 | In file-based version control systems, when you rename a registered |
203 | file you need to rename its master along with it; the command | |
204 | @code{vc-rename-file} will do this automatically | |
205 | @iftex | |
206 | (@pxref{VC Delete/Rename,,,emacs, the Emacs Manual}). | |
207 | @end iftex | |
208 | @ifnottex | |
209 | (@pxref{VC Delete/Rename}). | |
210 | @end ifnottex | |
211 | If you are using SCCS, you must also update the records of the tag, to | |
212 | mention the file by its new name (@code{vc-rename-file} does this, | |
213 | too). An old tag that refers to a master file that no longer exists | |
214 | under the recorded name is invalid; VC can no longer retrieve it. It | |
215 | would be beyond the scope of this manual to explain enough about RCS | |
216 | and SCCS to explain how to update the tags by hand. Using | |
217 | @code{vc-rename-file} makes the tag remain valid for retrieval, but it | |
218 | does not solve all problems. For example, some of the files in your | |
219 | program probably refer to others by name. At the very least, the | |
220 | makefile probably mentions the file that you renamed. If you retrieve | |
221 | an old tag, the renamed file is retrieved under its new name, which is | |
222 | not the name that the makefile expects. So the program won't really | |
223 | work as retrieved. | |
1ab2e8ba CY |
224 | |
225 | @node Version Headers | |
226 | @subsubsection Inserting Version Control Headers | |
227 | ||
2785d024 CY |
228 | On Subversion, CVS, RCS, and SCCS, you can put certain special |
229 | strings called @dfn{version headers} into a work file. When the file | |
230 | is committed, the version control system automatically puts the | |
231 | revision number, the name of the user who made the commit, and other | |
232 | relevant information into the version header. | |
233 | ||
234 | @vindex vc-consult-headers | |
235 | VC does not normally use the information in the version headers. As | |
236 | an exception, when using RCS, Emacs uses the version header, if there | |
237 | is one, to determine the file version, since it is often more reliable | |
238 | than the RCS master file. To inhibit using the version header this | |
239 | way, change the variable @code{vc-consult-headers} to @code{nil}. | |
1ab2e8ba CY |
240 | |
241 | @kindex C-x v h | |
242 | @findex vc-insert-headers | |
1ab2e8ba | 243 | @vindex vc-@var{backend}-header |
2785d024 CY |
244 | To insert a suitable header string into the current buffer, type |
245 | @kbd{C-x v h} (@code{vc-insert-headers}). This command works only on | |
1df7defd | 246 | Subversion, CVS, RCS, and SCCS@. The variable |
2785d024 CY |
247 | @code{vc-@var{backend}-header} contains the list of keywords to insert |
248 | into the version header; for instance, CVS uses @code{vc-cvs-header}, | |
249 | whose default value is @code{'("\$Id\$")}. (The extra backslashes | |
250 | prevent the string constant from being interpreted as a header, if the | |
251 | Emacs Lisp file defining it is maintained with version control.) The | |
252 | @kbd{C-x v h} command inserts each keyword in the list on a new line | |
253 | at point, surrounded by tabs, and inside comment delimiters if | |
254 | necessary. | |
1ab2e8ba CY |
255 | |
256 | @vindex vc-static-header-alist | |
257 | The variable @code{vc-static-header-alist} specifies further strings | |
258 | to add based on the name of the buffer. Its value should be a list of | |
259 | elements of the form @code{(@var{regexp} . @var{format})}. Whenever | |
2785d024 CY |
260 | @var{regexp} matches the buffer name, @var{format} is also inserted as |
261 | part of the version header. A @samp{%s} in @var{format} is replaced | |
262 | with the file's version control type. | |
1ab2e8ba CY |
263 | |
264 | @node Customizing VC | |
265 | @subsection Customizing VC | |
266 | ||
267 | @vindex vc-handled-backends | |
2785d024 | 268 | The variable @code{vc-handled-backends} determines which version |
1ab2e8ba | 269 | control systems VC should handle. The default value is @code{(RCS CVS |
17a6e278 | 270 | SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems |
1ab2e8ba | 271 | that are currently supported. If you want VC to ignore one or more of |
2785d024 CY |
272 | these systems, exclude its name from the list. To disable VC |
273 | entirely, set this variable to @code{nil}. | |
1ab2e8ba | 274 | |
2785d024 CY |
275 | The order of systems in the list is significant: when you visit a |
276 | file registered in more than one system, VC uses the system that comes | |
d3098e1e | 277 | first in @code{vc-handled-backends} by default. The order is also |
2785d024 | 278 | significant when you register a file for the first time |
1ab2e8ba | 279 | @iftex |
2785d024 | 280 | (@pxref{Registering,,,emacs, the Emacs Manual}). |
1ab2e8ba CY |
281 | @end iftex |
282 | @ifnottex | |
2785d024 | 283 | (@pxref{Registering}). |
1ab2e8ba | 284 | @end ifnottex |
1ab2e8ba CY |
285 | |
286 | @menu | |
287 | * General VC Options:: Options that apply to multiple back ends. | |
288 | * RCS and SCCS:: Options for RCS and SCCS. | |
289 | * CVS Options:: Options for CVS. | |
290 | @end menu | |
291 | ||
292 | @node General VC Options | |
293 | @subsubsection General Options | |
294 | ||
295 | @vindex vc-make-backup-files | |
296 | Emacs normally does not save backup files for source files that are | |
297 | maintained with version control. If you want to make backup files even | |
298 | for files that use version control, set the variable | |
299 | @code{vc-make-backup-files} to a non-@code{nil} value. | |
300 | ||
1ab2e8ba | 301 | @vindex vc-follow-symlinks |
2785d024 CY |
302 | @cindex symbolic links (and version control) |
303 | Editing a version-controlled file through a symbolic link may cause | |
304 | unexpected results, if you are unaware that the underlying file is | |
305 | version-controlled. The variable @code{vc-follow-symlinks} controls | |
306 | what Emacs does if you try to visit a symbolic link pointing to a | |
307 | version-controlled file. If the value is @code{ask} (the default), | |
308 | Emacs asks for confirmation. If it is @code{nil}, Emacs just displays | |
309 | a warning message. If it is @code{t}, Emacs automatically follows the | |
310 | link and visits the real file instead. | |
1ab2e8ba CY |
311 | |
312 | @vindex vc-suppress-confirm | |
313 | If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} | |
314 | and @kbd{C-x v i} can save the current buffer without asking, and | |
2785d024 | 315 | @kbd{C-x v u} also operates without asking for confirmation. |
1ab2e8ba CY |
316 | |
317 | @vindex vc-command-messages | |
17a6e278 | 318 | VC mode does much of its work by running the shell commands for the |
2785d024 CY |
319 | appropriate version control system. If @code{vc-command-messages} is |
320 | non-@code{nil}, VC displays messages to indicate which shell commands | |
321 | it runs, and additional messages when the commands finish. | |
1ab2e8ba | 322 | |
1ab2e8ba CY |
323 | @node RCS and SCCS |
324 | @subsubsection Options for RCS and SCCS | |
325 | ||
326 | @cindex non-strict locking (RCS) | |
327 | @cindex locking, non-strict (RCS) | |
328 | By default, RCS uses locking to coordinate the activities of several | |
329 | users, but there is a mode called @dfn{non-strict locking} in which | |
330 | you can check-in changes without locking the file first. Use | |
331 | @samp{rcs -U} to switch to non-strict locking for a particular file, | |
332 | see the @code{rcs} manual page for details. | |
333 | ||
334 | When deducing the version control state of an RCS file, VC first | |
335 | looks for an RCS version header string in the file (@pxref{Version | |
336 | Headers}). If there is no header string, VC normally looks at the | |
337 | file permissions of the work file; this is fast. But there might be | |
338 | situations when the file permissions cannot be trusted. In this case | |
339 | the master file has to be consulted, which is rather expensive. Also | |
340 | the master file can only tell you @emph{if} there's any lock on the | |
341 | file, but not whether your work file really contains that locked | |
342 | version. | |
343 | ||
344 | @vindex vc-consult-headers | |
345 | You can tell VC not to use version headers to determine the file | |
346 | status by setting @code{vc-consult-headers} to @code{nil}. VC then | |
347 | always uses the file permissions (if it is supposed to trust them), or | |
348 | else checks the master file. | |
349 | ||
350 | @vindex vc-mistrust-permissions | |
351 | You can specify the criterion for whether to trust the file | |
352 | permissions by setting the variable @code{vc-mistrust-permissions}. | |
353 | Its value can be @code{t} (always mistrust the file permissions and | |
354 | check the master file), @code{nil} (always trust the file | |
355 | permissions), or a function of one argument which makes the decision. | |
356 | The argument is the directory name of the @file{RCS} subdirectory. A | |
357 | non-@code{nil} value from the function says to mistrust the file | |
358 | permissions. If you find that the file permissions of work files are | |
359 | changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. | |
360 | Then VC always checks the master file to determine the file's status. | |
361 | ||
362 | VC determines the version control state of files under SCCS much as | |
1df7defd | 363 | with RCS@. It does not consider SCCS version headers, though. Thus, |
1ab2e8ba CY |
364 | the variable @code{vc-mistrust-permissions} affects SCCS use, but |
365 | @code{vc-consult-headers} does not. | |
366 | ||
367 | @node CVS Options | |
368 | @subsubsection Options specific for CVS | |
369 | ||
d3098e1e CY |
370 | @vindex vc-cvs-global-switches |
371 | You can specify additional command line options to pass to all CVS | |
372 | operations in the variable @code{vc-cvs-global-switches}. These | |
373 | switches are inserted immediately after the @code{cvs} command, before | |
374 | the name of the operation to invoke. | |
8cf51b2c GM |
375 | |
376 | @vindex vc-stay-local | |
377 | @vindex vc-cvs-stay-local | |
1ab2e8ba | 378 | @cindex remote repositories (CVS) |
d3098e1e | 379 | When using a CVS repository on a remote machine, VC can try keeping |
1ab2e8ba CY |
380 | network interactions to a minimum. This is controlled by the variable |
381 | @code{vc-cvs-stay-local}. There is another variable, | |
382 | @code{vc-stay-local}, which enables the feature also for other back | |
1df7defd | 383 | ends that support it, including CVS@. In the following, we will talk |
1ab2e8ba CY |
384 | only about @code{vc-cvs-stay-local}, but everything applies to |
385 | @code{vc-stay-local} as well. | |
386 | ||
8d0b26f6 XF |
387 | If @code{vc-cvs-stay-local} is @code{only-file} (the default), VC |
388 | determines the version control status of each file using only the | |
389 | entry in the local CVS subdirectory and the information returned by | |
390 | previous CVS commands. As a consequence, if you have modified a file | |
391 | and somebody else has checked in other changes, you will not be | |
392 | notified of the conflict until you try to commit. | |
d3098e1e CY |
393 | |
394 | If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the | |
395 | remote repository @emph{before} it decides what to do in | |
396 | @code{vc-next-action} (@kbd{C-x v v}), just as it does for local | |
397 | repositories. | |
398 | ||
399 | You can also set @code{vc-cvs-stay-local} to a regular expression | |
400 | that is matched against the repository host name; VC then stays local | |
401 | only for repositories from hosts that match the pattern. | |
402 | ||
403 | @cindex automatic version backups | |
404 | When using a remote repository, Emacs normally makes @dfn{automatic | |
405 | version backups} of the original versions of each edited file. These | |
406 | local backups are made whenever you save the first changes to a file, | |
407 | and they are removed after you commit your changes to the repository. | |
408 | (Note that these are not the same as ordinary Emacs backup files; | |
1ab2e8ba | 409 | @iftex |
d3098e1e | 410 | @pxref{Backup,,,emacs, the Emacs Manual}.) |
1ab2e8ba CY |
411 | @end iftex |
412 | @ifnottex | |
d3098e1e | 413 | @pxref{Backup}.) |
1ab2e8ba | 414 | @end ifnottex |
d3098e1e CY |
415 | Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic |
416 | version backups, if possible, to avoid having to access the network. | |
1ab2e8ba | 417 | |
d3098e1e CY |
418 | Setting @code{vc-cvs-stay-local} to @code{nil} disables the making |
419 | of automatic version backups. | |
1ab2e8ba | 420 | |
d3098e1e CY |
421 | @cindex manual version backups |
422 | Automatic version backups have names of the form | |
423 | @w{@code{@var{file}.~@var{version}.~}}. This is similar to the name | |
424 | that @kbd{C-x v ~} saves old versions to | |
425 | @iftex | |
426 | (@pxref{Old Revisions,,,emacs, the Emacs Manual}), | |
427 | @end iftex | |
428 | @ifnottex | |
429 | (@pxref{Old Revisions}), | |
430 | @end ifnottex | |
431 | except for the additional dot (@samp{.}) after the version. The | |
432 | relevant VC commands can use both kinds of version backups. The main | |
433 | difference is that the ``manual'' version backups made by @kbd{C-x v | |
434 | ~} are not deleted automatically when you commit. | |
1ab2e8ba | 435 | |
d3098e1e CY |
436 | @cindex locking (CVS) |
437 | CVS does not use locking by default, but there are ways to enable | |
438 | locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; | |
439 | see the CVS documentation for details. If that case, you can use | |
440 | @kbd{C-x v v} in Emacs to toggle locking, as you would for a | |
5f9756ec GM |
441 | locking-based version control system |
442 | @iftex | |
443 | (@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}). | |
444 | @end iftex | |
445 | @ifnottex | |
446 | (@pxref{VC With A Locking VCS}). | |
447 | @end ifnottex |