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