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