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