Mercurial > emacs
comparison man/vc2-xtra.texi @ 70440:5e1c038e4afa
New file, a portion of emacs-xtra.texi.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Sat, 06 May 2006 12:45:46 +0000 |
parents | |
children | bdd0ac985d67 |
comparison
equal
deleted
inserted
replaced
70439:48fec2b642c9 | 70440:5e1c038e4afa |
---|---|
1 @c This file is included either in vc-xtra.texi (when producing the | |
2 @c printed version) or in the main Emacs manual (for the on-line version). | |
3 @node Remote Repositories | |
4 @subsection Remote Repositories | |
5 @cindex remote repositories (CVS) | |
6 | |
7 A common way of using CVS is to set up a central CVS repository on | |
8 some Internet host, then have each developer check out a personal | |
9 working copy of the files on his local machine. Committing changes to | |
10 the repository, and picking up changes from other users into one's own | |
11 working area, then works by direct interactions with the CVS server. | |
12 | |
13 One difficulty is that access to the CVS server is often slow, and | |
14 that developers might need to work off-line as well. VC is designed | |
15 to reduce the amount of network interaction necessary. | |
16 | |
17 @menu | |
18 * Version Backups:: Keeping local copies of repository versions. | |
19 * Local Version Control:: Using another version system for local editing. | |
20 @end menu | |
21 | |
22 @node Version Backups | |
23 @subsubsection Version Backups | |
24 @cindex version backups | |
25 | |
26 @cindex automatic version backups | |
27 When VC sees that the CVS repository for a file is on a remote | |
28 machine, it automatically makes local backups of unmodified versions | |
29 of the file---@dfn{automatic version backups}. This means that you | |
30 can compare the file to the repository version (@kbd{C-x v =}), or | |
31 revert to that version (@kbd{C-x v u}), without any network | |
32 interactions. | |
33 | |
34 The local copy of the unmodified file is called a @dfn{version | |
35 backup} to indicate that it corresponds exactly to a version that is | |
36 stored in the repository. Note that version backups are not the same | |
37 as ordinary Emacs backup files (@pxref{Backup,,,emacs, the Emacs | |
38 Manual}). But they follow a similar naming convention. | |
39 | |
40 For a file that comes from a remote CVS repository, VC makes a | |
41 version backup whenever you save the first changes to the file, and | |
42 removes it after you have committed your modified version to the | |
43 repository. You can disable the making of automatic version backups by | |
44 setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). | |
45 | |
46 @cindex manual version backups | |
47 The name of the automatic version backup for version @var{version} | |
48 of file @var{file} is @code{@var{file}.~@var{version}.~}. This is | |
49 almost the same as the name used by @kbd{C-x v ~} (@pxref{Old | |
50 Versions,,,emacs, the Emacs Manual}), the only difference being | |
51 the additional dot (@samp{.}) after the version number. This | |
52 similarity is intentional, because both kinds of files store the same | |
53 kind of information. The file made by @kbd{C-x v ~} acts as a | |
54 @dfn{manual version backup}. | |
55 | |
56 All the VC commands that operate on old versions of a file can use | |
57 both kinds of version backups. For instance, @kbd{C-x v ~} uses | |
58 either an automatic or a manual version backup, if possible, to get | |
59 the contents of the version you request. Likewise, @kbd{C-x v =} and | |
60 @kbd{C-x v u} use either an automatic or a manual version backup, if | |
61 one of them exists, to get the contents of a version to compare or | |
62 revert to. If you changed a file outside of Emacs, so that no | |
63 automatic version backup was created for the previous text, you can | |
64 create a manual backup of that version using @kbd{C-x v ~}, and thus | |
65 obtain the benefit of the local copy for Emacs commands. | |
66 | |
67 The only difference in Emacs's handling of manual and automatic | |
68 version backups, once they exist, is that Emacs deletes automatic | |
69 version backups when you commit to the repository. By contrast, | |
70 manual version backups remain until you delete them. | |
71 | |
72 @node Local Version Control | |
73 @subsubsection Local Version Control | |
74 @cindex local version control | |
75 @cindex local back end (version control) | |
76 | |
77 When you make many changes to a file that comes from a remote | |
78 repository, it can be convenient to have version control on your local | |
79 machine as well. You can then record intermediate versions, revert to | |
80 a previous state, etc., before you actually commit your changes to the | |
81 remote server. | |
82 | |
83 VC lets you do this by putting a file under a second, local version | |
84 control system, so that the file is effectively registered in two | |
85 systems at the same time. For the description here, we will assume | |
86 that the remote system is CVS, and you use RCS locally, although the | |
87 mechanism works with any combination of version control systems | |
88 (@dfn{back ends}). | |
89 | |
90 To make it work with other back ends, you must make sure that the | |
91 ``more local'' back end comes before the ``more remote'' back end in | |
92 the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By | |
93 default, this variable is set up so that you can use remote CVS and | |
94 local RCS as described here. | |
95 | |
96 To start using local RCS for a file that comes from a remote CVS | |
97 server, you must @emph{register the file in RCS}, by typing @kbd{C-u | |
98 C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a | |
99 prefix argument, and specify RCS as the back end.) | |
100 | |
101 You can do this at any time; it does not matter whether you have | |
102 already modified the file with respect to the version in the CVS | |
103 repository. If possible, VC tries to make the RCS master start with | |
104 the unmodified repository version, then checks in any local changes | |
105 as a new version. This works if you have not made any changes yet, or | |
106 if the unmodified repository version exists locally as a version | |
107 backup (@pxref{Version Backups}). If the unmodified version is not | |
108 available locally, the RCS master starts with the modified version; | |
109 the only drawback to this is that you cannot compare your changes | |
110 locally to what is stored in the repository. | |
111 | |
112 The version number of the RCS master is derived from the current CVS | |
113 version, starting a branch from it. For example, if the current CVS | |
114 version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in | |
115 the RCS master will be identical to version 1.23 under CVS; your first | |
116 changes are checked in as 1.23.1.1. (If the unmodified file is not | |
117 available locally, VC will check in the modified file twice, both as | |
118 1.23 and 1.23.1.1, to make the revision numbers consistent.) | |
119 | |
120 If you do not use locking under CVS (the default), locking is also | |
121 disabled for RCS, so that editing under RCS works exactly as under | |
122 CVS. | |
123 | |
124 When you are done with local editing, you can commit the final version | |
125 back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. | |
126 This initializes the log entry buffer (@pxref{Log Buffer,,,emacs, the | |
127 Emacs Manual}) to contain all the log entries you have recorded in the | |
128 RCS master; you can edit them as you wish, and then commit in CVS by | |
129 typing @kbd{C-c C-c}. If the commit is successful, VC removes the RCS | |
130 master, so that the file is once again registered under CVS only. | |
131 (The RCS master is not actually deleted, just renamed by appending | |
132 @samp{~} to the name, so that you can refer to it later if you wish.) | |
133 | |
134 While using local RCS, you can pick up recent changes from the CVS | |
135 repository into your local file, or commit some of your changes back | |
136 to CVS, without terminating local RCS version control. To do this, | |
137 switch to the CVS back end temporarily, with the @kbd{C-x v b} command: | |
138 | |
139 @table @kbd | |
140 @item C-x v b | |
141 Switch to another back end that the current file is registered | |
142 under (@code{vc-switch-backend}). | |
143 | |
144 @item C-u C-x v b @var{backend} @key{RET} | |
145 Switch to @var{backend} for the current file. | |
146 @end table | |
147 | |
148 @kindex C-x v b | |
149 @findex vc-switch-backend | |
150 @kbd{C-x v b} does not change the buffer contents, or any files; it | |
151 only changes VC's perspective on how to handle the file. Any | |
152 subsequent VC commands for that file will operate on the back end that | |
153 is currently selected. | |
154 | |
155 If the current file is registered in more than one back end, typing | |
156 @kbd{C-x v b} ``cycles'' through all of these back ends. With a | |
157 prefix argument, it asks for the back end to use in the minibuffer. | |
158 | |
159 Thus, if you are using local RCS, and you want to pick up some recent | |
160 changes in the file from remote CVS, first visit the file, then type | |
161 @kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m | |
162 @key{RET}} to merge the news (@pxref{Merging,,,emacs, the Emacs | |
163 Manual}). You can then switch back to RCS by typing @kbd{C-x v b} | |
164 again, and continue to edit locally. | |
165 | |
166 But if you do this, the revision numbers in the RCS master no longer | |
167 correspond to those of CVS. Technically, this is not a problem, but | |
168 it can become difficult to keep track of what is in the CVS repository | |
169 and what is not. So we suggest that you return from time to time to | |
170 CVS-only operation, by committing your local changes back to the | |
171 repository using @kbd{C-u C-x v v cvs @key{RET}}. | |
172 | |
173 @node Snapshots | |
174 @subsection Snapshots | |
175 @cindex snapshots and version control | |
176 | |
177 A @dfn{snapshot} is a named set of file versions (one for each | |
178 registered file) that you can treat as a unit. One important kind of | |
179 snapshot is a @dfn{release}, a (theoretically) stable version of the | |
180 system that is ready for distribution to users. | |
181 | |
182 @menu | |
183 * Making Snapshots:: The snapshot facilities. | |
184 * Snapshot Caveats:: Things to be careful of when using snapshots. | |
185 @end menu | |
186 | |
187 @node Making Snapshots | |
188 @subsubsection Making and Using Snapshots | |
189 | |
190 There are two basic commands for snapshots; one makes a | |
191 snapshot with a given name, the other retrieves a named snapshot. | |
192 | |
193 @table @code | |
194 @kindex C-x v s | |
195 @findex vc-create-snapshot | |
196 @item C-x v s @var{name} @key{RET} | |
197 Define the last saved versions of every registered file in or under the | |
198 current directory as a snapshot named @var{name} | |
199 (@code{vc-create-snapshot}). | |
200 | |
201 @kindex C-x v r | |
202 @findex vc-retrieve-snapshot | |
203 @item C-x v r @var{name} @key{RET} | |
204 For all registered files at or below the current directory level, select | |
205 whatever versions correspond to the snapshot @var{name} | |
206 (@code{vc-retrieve-snapshot}). | |
207 | |
208 This command reports an error if any files are locked at or below the | |
209 current directory, without changing anything; this is to avoid | |
210 overwriting work in progress. | |
211 @end table | |
212 | |
213 A snapshot uses a very small amount of resources---just enough to record | |
214 the list of file names and which version belongs to the snapshot. Thus, | |
215 you need not hesitate to create snapshots whenever they are useful. | |
216 | |
217 You can give a snapshot name as an argument to @kbd{C-x v =} or | |
218 @kbd{C-x v ~} (@pxref{Old Versions,,,emacs, the Emacs Manual}). | |
219 Thus, you can use it to compare a snapshot against the current files, | |
220 or two snapshots against each other, or a snapshot against a named | |
221 version. | |
222 | |
223 @node Snapshot Caveats | |
224 @subsubsection Snapshot Caveats | |
225 | |
226 @cindex named configurations (RCS) | |
227 VC's snapshot facilities are modeled on RCS's named-configuration | |
228 support. They use RCS's native facilities for this, so | |
229 snapshots made using RCS through VC are visible even when you bypass VC. | |
230 | |
231 With CVS, Meta-CVS, and Subversion, VC also uses the native | |
232 mechanism provided by that back end to make snapshots and retrieve them | |
233 (@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion). | |
234 | |
235 @c worded verbosely to avoid overfull hbox. | |
236 For SCCS, VC implements snapshots itself. The files it uses contain | |
237 name/file/version-number triples. These snapshots are visible only | |
238 through VC. | |
239 | |
240 There is no support for VC snapshots using GNU Arch yet. | |
241 | |
242 A snapshot is a set of checked-in versions. So make sure that all the | |
243 files are checked in and not locked when you make a snapshot. | |
244 | |
245 File renaming and deletion can create some difficulties with snapshots. | |
246 This is not a VC-specific problem, but a general design issue in version | |
247 control systems that no one has solved very well yet. | |
248 | |
249 If you rename a registered file, you need to rename its master along | |
250 with it (the command @code{vc-rename-file} does this automatically). If | |
251 you are using SCCS, you must also update the records of the snapshot, to | |
252 mention the file by its new name (@code{vc-rename-file} does this, | |
253 too). An old snapshot that refers to a master file that no longer | |
254 exists under the recorded name is invalid; VC can no longer retrieve | |
255 it. It would be beyond the scope of this manual to explain enough about | |
256 RCS and SCCS to explain how to update the snapshots by hand. | |
257 | |
258 Using @code{vc-rename-file} makes the snapshot remain valid for | |
259 retrieval, but it does not solve all problems. For example, some of the | |
260 files in your program probably refer to others by name. At the very | |
261 least, the makefile probably mentions the file that you renamed. If you | |
262 retrieve an old snapshot, the renamed file is retrieved under its new | |
263 name, which is not the name that the makefile expects. So the program | |
264 won't really work as retrieved. | |
265 | |
266 @node Miscellaneous VC | |
267 @subsection Miscellaneous Commands and Features of VC | |
268 | |
269 This section explains the less-frequently-used features of VC. | |
270 | |
271 @menu | |
272 * Change Logs and VC:: Generating a change log file from log entries. | |
273 * Renaming and VC:: A command to rename both the source and master | |
274 file correctly. | |
275 * Version Headers:: Inserting version control headers into working files. | |
276 @end menu | |
277 | |
278 @node Change Logs and VC | |
279 @subsubsection Change Logs and VC | |
280 | |
281 If you use RCS or CVS for a program and also maintain a change log | |
282 file for it (@pxref{Change Log,,,emacs, the Emacs Manual}), you | |
283 can generate change log entries automatically from the version control | |
284 log entries: | |
285 | |
286 @table @kbd | |
287 @item C-x v a | |
288 @kindex C-x v a | |
289 @findex vc-update-change-log | |
290 Visit the current directory's change log file and, for registered files | |
291 in that directory, create new entries for versions checked in since the | |
292 most recent entry in the change log file. | |
293 (@code{vc-update-change-log}). | |
294 | |
295 This command works with RCS or CVS only, not with any of the other | |
296 back ends. | |
297 | |
298 @item C-u C-x v a | |
299 As above, but only find entries for the current buffer's file. | |
300 | |
301 @item M-1 C-x v a | |
302 As above, but find entries for all the currently visited files that are | |
303 maintained with version control. This works only with RCS, and it puts | |
304 all entries in the log for the default directory, which may not be | |
305 appropriate. | |
306 @end table | |
307 | |
308 For example, suppose the first line of @file{ChangeLog} is dated | |
309 1999-04-10, and that the only check-in since then was by Nathaniel | |
310 Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log | |
311 messages that start with `#'.}. Then @kbd{C-x v a} visits | |
312 @file{ChangeLog} and inserts text like this: | |
313 | |
314 @iftex | |
315 @medbreak | |
316 @end iftex | |
317 @smallexample | |
318 @group | |
319 1999-05-22 Nathaniel Bowditch <nat@@apn.org> | |
320 | |
321 * rcs2log: Ignore log messages that start with `#'. | |
322 @end group | |
323 @end smallexample | |
324 @iftex | |
325 @medbreak | |
326 @end iftex | |
327 | |
328 @noindent | |
329 You can then edit the new change log entry further as you wish. | |
330 | |
331 Some of the new change log entries may duplicate what's already in | |
332 ChangeLog. You will have to remove these duplicates by hand. | |
333 | |
334 Normally, the log entry for file @file{foo} is displayed as @samp{* | |
335 foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted | |
336 if the text of the log entry starts with @w{@samp{(@var{functionname}): | |
337 }}. For example, if the log entry for @file{vc.el} is | |
338 @samp{(vc-do-command): Check call-process status.}, then the text in | |
339 @file{ChangeLog} looks like this: | |
340 | |
341 @iftex | |
342 @medbreak | |
343 @end iftex | |
344 @smallexample | |
345 @group | |
346 1999-05-06 Nathaniel Bowditch <nat@@apn.org> | |
347 | |
348 * vc.el (vc-do-command): Check call-process status. | |
349 @end group | |
350 @end smallexample | |
351 @iftex | |
352 @medbreak | |
353 @end iftex | |
354 | |
355 When @kbd{C-x v a} adds several change log entries at once, it groups | |
356 related log entries together if they all are checked in by the same | |
357 author at nearly the same time. If the log entries for several such | |
358 files all have the same text, it coalesces them into a single entry. | |
359 For example, suppose the most recent check-ins have the following log | |
360 entries: | |
361 | |
362 @flushleft | |
363 @bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} | |
364 @bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} | |
365 @bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} | |
366 @end flushleft | |
367 | |
368 @noindent | |
369 They appear like this in @file{ChangeLog}: | |
370 | |
371 @iftex | |
372 @medbreak | |
373 @end iftex | |
374 @smallexample | |
375 @group | |
376 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
377 | |
378 * vc.texinfo: Fix expansion typos. | |
379 | |
380 * vc.el, vc-hooks.el: Don't call expand-file-name. | |
381 @end group | |
382 @end smallexample | |
383 @iftex | |
384 @medbreak | |
385 @end iftex | |
386 | |
387 Normally, @kbd{C-x v a} separates log entries by a blank line, but you | |
388 can mark several related log entries to be clumped together (without an | |
389 intervening blank line) by starting the text of each related log entry | |
390 with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label | |
391 itself is not copied to @file{ChangeLog}. For example, suppose the log | |
392 entries are: | |
393 | |
394 @flushleft | |
395 @bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} | |
396 @bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} | |
397 @bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} | |
398 @end flushleft | |
399 | |
400 @noindent | |
401 Then the text in @file{ChangeLog} looks like this: | |
402 | |
403 @iftex | |
404 @medbreak | |
405 @end iftex | |
406 @smallexample | |
407 @group | |
408 1999-04-01 Nathaniel Bowditch <nat@@apn.org> | |
409 | |
410 * vc.texinfo: Fix expansion typos. | |
411 * vc.el, vc-hooks.el: Don't call expand-file-name. | |
412 @end group | |
413 @end smallexample | |
414 @iftex | |
415 @medbreak | |
416 @end iftex | |
417 | |
418 A log entry whose text begins with @samp{#} is not copied to | |
419 @file{ChangeLog}. For example, if you merely fix some misspellings in | |
420 comments, you can log the change with an entry beginning with @samp{#} | |
421 to avoid putting such trivia into @file{ChangeLog}. | |
422 | |
423 @node Renaming and VC | |
424 @subsubsection Renaming VC Work Files and Master Files | |
425 | |
426 @findex vc-rename-file | |
427 When you rename a registered file, you must also rename its master | |
428 file correspondingly to get proper results. Use @code{vc-rename-file} | |
429 to rename the source file as you specify, and rename its master file | |
430 accordingly. It also updates any snapshots (@pxref{Snapshots}) that | |
431 mention the file, so that they use the new name; despite this, the | |
432 snapshot thus modified may not completely work (@pxref{Snapshot | |
433 Caveats}). | |
434 | |
435 Some back ends do not provide an explicit rename operation to their | |
436 repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} | |
437 on the original and renamed buffers and provide the necessary edit | |
438 log. | |
439 | |
440 You cannot use @code{vc-rename-file} on a file that is locked by | |
441 someone else. | |
442 | |
443 @node Version Headers | |
444 @subsubsection Inserting Version Control Headers | |
445 | |
446 Sometimes it is convenient to put version identification strings | |
447 directly into working files. Certain special strings called | |
448 @dfn{version headers} are replaced in each successive version by the | |
449 number of that version, the name of the user who created it, and other | |
450 relevant information. All of the back ends that VC supports have such | |
451 a mechanism, except GNU Arch. | |
452 | |
453 VC does not normally use the information contained in these headers. | |
454 The exception is RCS---with RCS, version headers are sometimes more | |
455 reliable than the master file to determine which version of the file | |
456 you are editing. Note that in a multi-branch environment, version | |
457 headers are necessary to make VC behave correctly (@pxref{Multi-User | |
458 Branching,,,emacs, the Emacs Manual}). | |
459 | |
460 Searching for RCS version headers is controlled by the variable | |
461 @code{vc-consult-headers}. If it is non-@code{nil} (the default), | |
462 Emacs searches for headers to determine the version number you are | |
463 editing. Setting it to @code{nil} disables this feature. | |
464 | |
465 Note that although CVS uses the same kind of version headers as RCS | |
466 does, VC never searches for these headers if you are using CVS, | |
467 regardless of the above setting. | |
468 | |
469 @kindex C-x v h | |
470 @findex vc-insert-headers | |
471 You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to | |
472 insert a suitable header string. | |
473 | |
474 @table @kbd | |
475 @item C-x v h | |
476 Insert headers in a file for use with your version-control system. | |
477 @end table | |
478 | |
479 @vindex vc-@var{backend}-header | |
480 The default header string is @samp{@w{$}Id$} for RCS and | |
481 @samp{@w{%}W%} for SCCS. You can specify other headers to insert by | |
482 setting the variables @code{vc-@var{backend}-header} where | |
483 @var{backend} is @code{rcs} or @code{sccs}. | |
484 | |
485 Instead of a single string, you can specify a list of strings; then | |
486 each string in the list is inserted as a separate header on a line of | |
487 its own. | |
488 | |
489 It may be necessary to use apparently-superfluous backslashes when | |
490 writing the strings that you put in this variable. For instance, you | |
491 might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra | |
492 backslash prevents the string constant from being interpreted as a | |
493 header, if the Emacs Lisp file containing it is maintained with | |
494 version control. | |
495 | |
496 @vindex vc-comment-alist | |
497 Each header is inserted surrounded by tabs, inside comment delimiters, | |
498 on a new line at point. Normally the ordinary comment | |
499 start and comment end strings of the current mode are used, but for | |
500 certain modes, there are special comment delimiters for this purpose; | |
501 the variable @code{vc-comment-alist} specifies them. Each element of | |
502 this list has the form @code{(@var{mode} @var{starter} @var{ender})}. | |
503 | |
504 @vindex vc-static-header-alist | |
505 The variable @code{vc-static-header-alist} specifies further strings | |
506 to add based on the name of the buffer. Its value should be a list of | |
507 elements of the form @code{(@var{regexp} . @var{format})}. Whenever | |
508 @var{regexp} matches the buffer name, @var{format} is inserted as part | |
509 of the header. A header line is inserted for each element that matches | |
510 the buffer name, and for each string specified by | |
511 @code{vc-@var{backend}-header}. The header line is made by processing the | |
512 string from @code{vc-@var{backend}-header} with the format taken from the | |
513 element. The default value for @code{vc-static-header-alist} is as follows: | |
514 | |
515 @example | |
516 @group | |
517 (("\\.c$" . | |
518 "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ | |
519 #endif /* lint */\n")) | |
520 @end group | |
521 @end example | |
522 | |
523 @noindent | |
524 It specifies insertion of text of this form: | |
525 | |
526 @example | |
527 @group | |
528 | |
529 #ifndef lint | |
530 static char vcid[] = "@var{string}"; | |
531 #endif /* lint */ | |
532 @end group | |
533 @end example | |
534 | |
535 @noindent | |
536 Note that the text above starts with a blank line. | |
537 | |
538 If you use more than one version header in a file, put them close | |
539 together in the file. The mechanism in @code{revert-buffer} that | |
540 preserves markers may not handle markers positioned between two version | |
541 headers. | |
542 | |
543 @node Customizing VC | |
544 @subsection Customizing VC | |
545 | |
546 @vindex vc-handled-backends | |
547 The variable @code{vc-handled-backends} determines which version | |
548 control systems VC should handle. The default value is @code{(RCS CVS | |
549 SVN SCCS Arch MCVS)}, so it contains all six version systems that are | |
550 currently supported. If you want VC to ignore one or more of these | |
551 systems, exclude its name from the list. To disable VC entirely, set | |
552 this variable to @code{nil}. | |
553 | |
554 The order of systems in the list is significant: when you visit a file | |
555 registered in more than one system (@pxref{Local Version Control}), VC | |
556 uses the system that comes first in @code{vc-handled-backends} by | |
557 default. The order is also significant when you register a file for | |
558 the first time, @pxref{Registering,,,emacs, the Emacs Manual} for | |
559 details. | |
560 | |
561 @menu | |
562 * General VC Options:: Options that apply to multiple back ends. | |
563 * RCS and SCCS:: Options for RCS and SCCS. | |
564 * CVS Options:: Options for CVS. | |
565 @end menu | |
566 | |
567 @node General VC Options | |
568 @subsubsection General Options | |
569 | |
570 @vindex vc-make-backup-files | |
571 Emacs normally does not save backup files for source files that are | |
572 maintained with version control. If you want to make backup files even | |
573 for files that use version control, set the variable | |
574 @code{vc-make-backup-files} to a non-@code{nil} value. | |
575 | |
576 @vindex vc-keep-workfiles | |
577 Normally the work file exists all the time, whether it is locked or | |
578 not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking | |
579 in a new version with @kbd{C-x v v} deletes the work file; but any | |
580 attempt to visit the file with Emacs creates it again. (With CVS, work | |
581 files are always kept.) | |
582 | |
583 @vindex vc-follow-symlinks | |
584 Editing a version-controlled file through a symbolic link can be | |
585 dangerous. It bypasses the version control system---you can edit the | |
586 file without locking it, and fail to check your changes in. Also, | |
587 your changes might overwrite those of another user. To protect against | |
588 this, VC checks each symbolic link that you visit, to see if it points | |
589 to a file under version control. | |
590 | |
591 The variable @code{vc-follow-symlinks} controls what to do when a | |
592 symbolic link points to a version-controlled file. If it is @code{nil}, | |
593 VC only displays a warning message. If it is @code{t}, VC automatically | |
594 follows the link, and visits the real file instead, telling you about | |
595 this in the echo area. If the value is @code{ask} (the default), VC | |
596 asks you each time whether to follow the link. | |
597 | |
598 @vindex vc-suppress-confirm | |
599 If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} | |
600 and @kbd{C-x v i} can save the current buffer without asking, and | |
601 @kbd{C-x v u} also operates without asking for confirmation. (This | |
602 variable does not affect @kbd{C-x v c}; that operation is so drastic | |
603 that it should always ask for confirmation.) | |
604 | |
605 @vindex vc-command-messages | |
606 VC mode does much of its work by running the shell commands for RCS, | |
607 CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC | |
608 displays messages to indicate which shell commands it runs, and | |
609 additional messages when the commands finish. | |
610 | |
611 @vindex vc-path | |
612 You can specify additional directories to search for version control | |
613 programs by setting the variable @code{vc-path}. These directories | |
614 are searched before the usual search path. It is rarely necessary to | |
615 set this variable, because VC normally finds the proper files | |
616 automatically. | |
617 | |
618 @node RCS and SCCS | |
619 @subsubsection Options for RCS and SCCS | |
620 | |
621 @cindex non-strict locking (RCS) | |
622 @cindex locking, non-strict (RCS) | |
623 By default, RCS uses locking to coordinate the activities of several | |
624 users, but there is a mode called @dfn{non-strict locking} in which | |
625 you can check-in changes without locking the file first. Use | |
626 @samp{rcs -U} to switch to non-strict locking for a particular file, | |
627 see the @code{rcs} manual page for details. | |
628 | |
629 When deducing the version control state of an RCS file, VC first | |
630 looks for an RCS version header string in the file (@pxref{Version | |
631 Headers}). If there is no header string, VC normally looks at the | |
632 file permissions of the work file; this is fast. But there might be | |
633 situations when the file permissions cannot be trusted. In this case | |
634 the master file has to be consulted, which is rather expensive. Also | |
635 the master file can only tell you @emph{if} there's any lock on the | |
636 file, but not whether your work file really contains that locked | |
637 version. | |
638 | |
639 @vindex vc-consult-headers | |
640 You can tell VC not to use version headers to determine the file | |
641 status by setting @code{vc-consult-headers} to @code{nil}. VC then | |
642 always uses the file permissions (if it is supposed to trust them), or | |
643 else checks the master file. | |
644 | |
645 @vindex vc-mistrust-permissions | |
646 You can specify the criterion for whether to trust the file | |
647 permissions by setting the variable @code{vc-mistrust-permissions}. | |
648 Its value can be @code{t} (always mistrust the file permissions and | |
649 check the master file), @code{nil} (always trust the file | |
650 permissions), or a function of one argument which makes the decision. | |
651 The argument is the directory name of the @file{RCS} subdirectory. A | |
652 non-@code{nil} value from the function says to mistrust the file | |
653 permissions. If you find that the file permissions of work files are | |
654 changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. | |
655 Then VC always checks the master file to determine the file's status. | |
656 | |
657 VC determines the version control state of files under SCCS much as | |
658 with RCS. It does not consider SCCS version headers, though. Thus, | |
659 the variable @code{vc-mistrust-permissions} affects SCCS use, but | |
660 @code{vc-consult-headers} does not. | |
661 | |
662 @node CVS Options | |
663 @subsubsection Options specific for CVS | |
664 | |
665 @cindex locking (CVS) | |
666 By default, CVS does not use locking to coordinate the activities of | |
667 several users; anyone can change a work file at any time. However, | |
668 there are ways to restrict this, resulting in behavior that resembles | |
669 locking. | |
670 | |
671 @cindex CVSREAD environment variable (CVS) | |
672 For one thing, you can set the @env{CVSREAD} environment variable | |
673 (the value you use makes no difference). If this variable is defined, | |
674 CVS makes your work files read-only by default. In Emacs, you must | |
675 type @kbd{C-x v v} to make the file writable, so that editing works | |
676 in fact similar as if locking was used. Note however, that no actual | |
677 locking is performed, so several users can make their files writable | |
678 at the same time. When setting @env{CVSREAD} for the first time, make | |
679 sure to check out all your modules anew, so that the file protections | |
680 are set correctly. | |
681 | |
682 @cindex cvs watch feature | |
683 @cindex watching files (CVS) | |
684 Another way to achieve something similar to locking is to use the | |
685 @dfn{watch} feature of CVS. If a file is being watched, CVS makes it | |
686 read-only by default, and you must also use @kbd{C-x v v} in Emacs to | |
687 make it writable. VC calls @code{cvs edit} to make the file writable, | |
688 and CVS takes care to notify other developers of the fact that you | |
689 intend to change the file. See the CVS documentation for details on | |
690 using the watch feature. | |
691 | |
692 @vindex vc-stay-local | |
693 @vindex vc-cvs-stay-local | |
694 @cindex remote repositories (CVS) | |
695 When a file's repository is on a remote machine, VC tries to keep | |
696 network interactions to a minimum. This is controlled by the variable | |
697 @code{vc-cvs-stay-local}. There is another variable, | |
698 @code{vc-stay-local}, which enables the feature also for other back | |
699 ends that support it, including CVS. In the following, we will talk | |
700 only about @code{vc-cvs-stay-local}, but everything applies to | |
701 @code{vc-stay-local} as well. | |
702 | |
703 If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses | |
704 only the entry in the local CVS subdirectory to determine the file's | |
705 state (and possibly information returned by previous CVS commands). | |
706 One consequence of this is that when you have modified a file, and | |
707 somebody else has already checked in other changes to the file, you | |
708 are not notified of it until you actually try to commit. (But you can | |
709 try to pick up any recent changes from the repository first, using | |
710 @kbd{C-x v m @key{RET}}, @pxref{Merging,,,emacs, the Emacs Manual}). | |
711 | |
712 When @code{vc-cvs-stay-local} is @code{t}, VC also makes local | |
713 version backups, so that simple diff and revert operations are | |
714 completely local (@pxref{Version Backups}). | |
715 | |
716 On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, | |
717 then VC queries the remote repository @emph{before} it decides what to | |
718 do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local | |
719 repositories. It also does not make any version backups. | |
720 | |
721 You can also set @code{vc-cvs-stay-local} to a regular expression | |
722 that is matched against the repository host name; VC then stays local | |
723 only for repositories from hosts that match the pattern. | |
724 | |
725 @vindex vc-cvs-global-switches | |
726 You can specify additional command line options to pass to all CVS | |
727 operations in the variable @code{vc-cvs-global-switches}. These | |
728 switches are inserted immediately after the @code{cvs} command, before | |
729 the name of the operation to invoke. |