Commit | Line | Data |
---|---|---|
8cf51b2c | 1 | @c This is part of the Emacs manual. |
acaf905b | 2 | @c Copyright (C) 2004-2012 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 | |
d3098e1e CY |
202 | In a file-oriented VCS, when you rename a registered file you need |
203 | to rename its master along with it; the command @code{vc-rename-file} | |
204 | will do this automatically. If you are using SCCS, you must also | |
205 | update the records of the tag, to mention the file by its new name | |
206 | (@code{vc-rename-file} does this, too). An old tag that refers to a | |
207 | master file that no longer exists under the recorded name is invalid; | |
208 | VC can no longer retrieve it. It would be beyond the scope of this | |
209 | manual to explain enough about RCS and SCCS to explain how to update | |
210 | the tags by hand. Using @code{vc-rename-file} makes the tag remain | |
211 | valid for retrieval, but it does not solve all problems. For example, | |
212 | some of the files in your program probably refer to others by name. | |
213 | At the very least, the makefile probably mentions the file that you | |
214 | renamed. If you retrieve an old tag, the renamed file is retrieved | |
215 | under its new name, which is not the name that the makefile expects. | |
216 | So the program won't really work as retrieved. | |
1ab2e8ba CY |
217 | |
218 | @node Version Headers | |
219 | @subsubsection Inserting Version Control Headers | |
220 | ||
2785d024 CY |
221 | On Subversion, CVS, RCS, and SCCS, you can put certain special |
222 | strings called @dfn{version headers} into a work file. When the file | |
223 | is committed, the version control system automatically puts the | |
224 | revision number, the name of the user who made the commit, and other | |
225 | relevant information into the version header. | |
226 | ||
227 | @vindex vc-consult-headers | |
228 | VC does not normally use the information in the version headers. As | |
229 | an exception, when using RCS, Emacs uses the version header, if there | |
230 | is one, to determine the file version, since it is often more reliable | |
231 | than the RCS master file. To inhibit using the version header this | |
232 | way, change the variable @code{vc-consult-headers} to @code{nil}. | |
1ab2e8ba CY |
233 | |
234 | @kindex C-x v h | |
235 | @findex vc-insert-headers | |
1ab2e8ba | 236 | @vindex vc-@var{backend}-header |
2785d024 CY |
237 | To insert a suitable header string into the current buffer, type |
238 | @kbd{C-x v h} (@code{vc-insert-headers}). This command works only on | |
1df7defd | 239 | Subversion, CVS, RCS, and SCCS@. The variable |
2785d024 CY |
240 | @code{vc-@var{backend}-header} contains the list of keywords to insert |
241 | into the version header; for instance, CVS uses @code{vc-cvs-header}, | |
242 | whose default value is @code{'("\$Id\$")}. (The extra backslashes | |
243 | prevent the string constant from being interpreted as a header, if the | |
244 | Emacs Lisp file defining it is maintained with version control.) The | |
245 | @kbd{C-x v h} command inserts each keyword in the list on a new line | |
246 | at point, surrounded by tabs, and inside comment delimiters if | |
247 | necessary. | |
1ab2e8ba CY |
248 | |
249 | @vindex vc-static-header-alist | |
250 | The variable @code{vc-static-header-alist} specifies further strings | |
251 | to add based on the name of the buffer. Its value should be a list of | |
252 | elements of the form @code{(@var{regexp} . @var{format})}. Whenever | |
2785d024 CY |
253 | @var{regexp} matches the buffer name, @var{format} is also inserted as |
254 | part of the version header. A @samp{%s} in @var{format} is replaced | |
255 | with the file's version control type. | |
1ab2e8ba CY |
256 | |
257 | @node Customizing VC | |
258 | @subsection Customizing VC | |
259 | ||
260 | @vindex vc-handled-backends | |
2785d024 | 261 | The variable @code{vc-handled-backends} determines which version |
1ab2e8ba | 262 | control systems VC should handle. The default value is @code{(RCS CVS |
17a6e278 | 263 | SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems |
1ab2e8ba | 264 | that are currently supported. If you want VC to ignore one or more of |
2785d024 CY |
265 | these systems, exclude its name from the list. To disable VC |
266 | entirely, set this variable to @code{nil}. | |
1ab2e8ba | 267 | |
2785d024 CY |
268 | The order of systems in the list is significant: when you visit a |
269 | file registered in more than one system, VC uses the system that comes | |
d3098e1e | 270 | first in @code{vc-handled-backends} by default. The order is also |
2785d024 | 271 | significant when you register a file for the first time |
1ab2e8ba | 272 | @iftex |
2785d024 | 273 | (@pxref{Registering,,,emacs, the Emacs Manual}). |
1ab2e8ba CY |
274 | @end iftex |
275 | @ifnottex | |
2785d024 | 276 | (@pxref{Registering}). |
1ab2e8ba | 277 | @end ifnottex |
1ab2e8ba CY |
278 | |
279 | @menu | |
280 | * General VC Options:: Options that apply to multiple back ends. | |
281 | * RCS and SCCS:: Options for RCS and SCCS. | |
282 | * CVS Options:: Options for CVS. | |
283 | @end menu | |
284 | ||
285 | @node General VC Options | |
286 | @subsubsection General Options | |
287 | ||
288 | @vindex vc-make-backup-files | |
289 | Emacs normally does not save backup files for source files that are | |
290 | maintained with version control. If you want to make backup files even | |
291 | for files that use version control, set the variable | |
292 | @code{vc-make-backup-files} to a non-@code{nil} value. | |
293 | ||
1ab2e8ba | 294 | @vindex vc-follow-symlinks |
2785d024 CY |
295 | @cindex symbolic links (and version control) |
296 | Editing a version-controlled file through a symbolic link may cause | |
297 | unexpected results, if you are unaware that the underlying file is | |
298 | version-controlled. The variable @code{vc-follow-symlinks} controls | |
299 | what Emacs does if you try to visit a symbolic link pointing to a | |
300 | version-controlled file. If the value is @code{ask} (the default), | |
301 | Emacs asks for confirmation. If it is @code{nil}, Emacs just displays | |
302 | a warning message. If it is @code{t}, Emacs automatically follows the | |
303 | link and visits the real file instead. | |
1ab2e8ba CY |
304 | |
305 | @vindex vc-suppress-confirm | |
306 | If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} | |
307 | and @kbd{C-x v i} can save the current buffer without asking, and | |
2785d024 | 308 | @kbd{C-x v u} also operates without asking for confirmation. |
1ab2e8ba CY |
309 | |
310 | @vindex vc-command-messages | |
17a6e278 | 311 | VC mode does much of its work by running the shell commands for the |
2785d024 CY |
312 | appropriate version control system. If @code{vc-command-messages} is |
313 | non-@code{nil}, VC displays messages to indicate which shell commands | |
314 | it runs, and additional messages when the commands finish. | |
1ab2e8ba | 315 | |
1ab2e8ba CY |
316 | @node RCS and SCCS |
317 | @subsubsection Options for RCS and SCCS | |
318 | ||
319 | @cindex non-strict locking (RCS) | |
320 | @cindex locking, non-strict (RCS) | |
321 | By default, RCS uses locking to coordinate the activities of several | |
322 | users, but there is a mode called @dfn{non-strict locking} in which | |
323 | you can check-in changes without locking the file first. Use | |
324 | @samp{rcs -U} to switch to non-strict locking for a particular file, | |
325 | see the @code{rcs} manual page for details. | |
326 | ||
327 | When deducing the version control state of an RCS file, VC first | |
328 | looks for an RCS version header string in the file (@pxref{Version | |
329 | Headers}). If there is no header string, VC normally looks at the | |
330 | file permissions of the work file; this is fast. But there might be | |
331 | situations when the file permissions cannot be trusted. In this case | |
332 | the master file has to be consulted, which is rather expensive. Also | |
333 | the master file can only tell you @emph{if} there's any lock on the | |
334 | file, but not whether your work file really contains that locked | |
335 | version. | |
336 | ||
337 | @vindex vc-consult-headers | |
338 | You can tell VC not to use version headers to determine the file | |
339 | status by setting @code{vc-consult-headers} to @code{nil}. VC then | |
340 | always uses the file permissions (if it is supposed to trust them), or | |
341 | else checks the master file. | |
342 | ||
343 | @vindex vc-mistrust-permissions | |
344 | You can specify the criterion for whether to trust the file | |
345 | permissions by setting the variable @code{vc-mistrust-permissions}. | |
346 | Its value can be @code{t} (always mistrust the file permissions and | |
347 | check the master file), @code{nil} (always trust the file | |
348 | permissions), or a function of one argument which makes the decision. | |
349 | The argument is the directory name of the @file{RCS} subdirectory. A | |
350 | non-@code{nil} value from the function says to mistrust the file | |
351 | permissions. If you find that the file permissions of work files are | |
352 | changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. | |
353 | Then VC always checks the master file to determine the file's status. | |
354 | ||
355 | VC determines the version control state of files under SCCS much as | |
1df7defd | 356 | with RCS@. It does not consider SCCS version headers, though. Thus, |
1ab2e8ba CY |
357 | the variable @code{vc-mistrust-permissions} affects SCCS use, but |
358 | @code{vc-consult-headers} does not. | |
359 | ||
360 | @node CVS Options | |
361 | @subsubsection Options specific for CVS | |
362 | ||
d3098e1e CY |
363 | @vindex vc-cvs-global-switches |
364 | You can specify additional command line options to pass to all CVS | |
365 | operations in the variable @code{vc-cvs-global-switches}. These | |
366 | switches are inserted immediately after the @code{cvs} command, before | |
367 | the name of the operation to invoke. | |
8cf51b2c GM |
368 | |
369 | @vindex vc-stay-local | |
370 | @vindex vc-cvs-stay-local | |
1ab2e8ba | 371 | @cindex remote repositories (CVS) |
d3098e1e | 372 | When using a CVS repository on a remote machine, VC can try keeping |
1ab2e8ba CY |
373 | network interactions to a minimum. This is controlled by the variable |
374 | @code{vc-cvs-stay-local}. There is another variable, | |
375 | @code{vc-stay-local}, which enables the feature also for other back | |
1df7defd | 376 | ends that support it, including CVS@. In the following, we will talk |
1ab2e8ba CY |
377 | only about @code{vc-cvs-stay-local}, but everything applies to |
378 | @code{vc-stay-local} as well. | |
379 | ||
d3098e1e CY |
380 | If @code{vc-cvs-stay-local} is @code{t} (the default), VC determines |
381 | the version control status of each file using only the entry in the | |
382 | local CVS subdirectory and the information returned by previous CVS | |
383 | commands. As a consequence, if you have modified a file and somebody | |
384 | else has checked in other changes, you will not be notified of the | |
385 | conflict until you try to commit. | |
386 | ||
387 | If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the | |
388 | remote repository @emph{before} it decides what to do in | |
389 | @code{vc-next-action} (@kbd{C-x v v}), just as it does for local | |
390 | repositories. | |
391 | ||
392 | You can also set @code{vc-cvs-stay-local} to a regular expression | |
393 | that is matched against the repository host name; VC then stays local | |
394 | only for repositories from hosts that match the pattern. | |
395 | ||
396 | @cindex automatic version backups | |
397 | When using a remote repository, Emacs normally makes @dfn{automatic | |
398 | version backups} of the original versions of each edited file. These | |
399 | local backups are made whenever you save the first changes to a file, | |
400 | and they are removed after you commit your changes to the repository. | |
401 | (Note that these are not the same as ordinary Emacs backup files; | |
1ab2e8ba | 402 | @iftex |
d3098e1e | 403 | @pxref{Backup,,,emacs, the Emacs Manual}.) |
1ab2e8ba CY |
404 | @end iftex |
405 | @ifnottex | |
d3098e1e | 406 | @pxref{Backup}.) |
1ab2e8ba | 407 | @end ifnottex |
d3098e1e CY |
408 | Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic |
409 | version backups, if possible, to avoid having to access the network. | |
1ab2e8ba | 410 | |
d3098e1e CY |
411 | Setting @code{vc-cvs-stay-local} to @code{nil} disables the making |
412 | of automatic version backups. | |
1ab2e8ba | 413 | |
d3098e1e CY |
414 | @cindex manual version backups |
415 | Automatic version backups have names of the form | |
416 | @w{@code{@var{file}.~@var{version}.~}}. This is similar to the name | |
417 | that @kbd{C-x v ~} saves old versions to | |
418 | @iftex | |
419 | (@pxref{Old Revisions,,,emacs, the Emacs Manual}), | |
420 | @end iftex | |
421 | @ifnottex | |
422 | (@pxref{Old Revisions}), | |
423 | @end ifnottex | |
424 | except for the additional dot (@samp{.}) after the version. The | |
425 | relevant VC commands can use both kinds of version backups. The main | |
426 | difference is that the ``manual'' version backups made by @kbd{C-x v | |
427 | ~} are not deleted automatically when you commit. | |
1ab2e8ba | 428 | |
d3098e1e CY |
429 | @cindex locking (CVS) |
430 | CVS does not use locking by default, but there are ways to enable | |
431 | locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; | |
432 | see the CVS documentation for details. If that case, you can use | |
433 | @kbd{C-x v v} in Emacs to toggle locking, as you would for a | |
5f9756ec GM |
434 | locking-based version control system |
435 | @iftex | |
436 | (@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}). | |
437 | @end iftex | |
438 | @ifnottex | |
439 | (@pxref{VC With A Locking VCS}). | |
440 | @end ifnottex |