X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/a57471f93507c55b55ee9e28c493ba78b46796e3..7e09ef09a479731d01b1ca46e94ddadd73ac98e3:/doc/emacs/vc1-xtra.texi?ds=sidebyside diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 05e89e69f0..a2bf249380 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -1,305 +1,10 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2015 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @c This file is included either in vc-xtra.texi (when producing the @c printed version) or in the main Emacs manual (for the on-line version). -@node Remote Repositories -@subsection Remote Repositories -@cindex remote repositories - - A common way of using CVS and other more advanced VCSes is to set up -a central repository on some Internet host, then have each -developer check out a personal working copy of the files on his local -machine. Committing changes to the repository, and picking up changes -from other users into one's own working area, then works by direct -interactions with the repository server. - - One difficulty is that access to a repository server is often slow, -and that developers might need to work off-line as well. While only -third-generation decentralized VCses such as GNU Arch or Mercurial -really solve this problem, VC is designed to reduce the amount of -network interaction necessary. - - If you are using a truly decentralized VCS you can skip the rest of -this section. It describes backup and local-repository techniques -that are only useful for Subversion and earlier VCSes. - -@menu -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. -@end menu - -@node Version Backups -@subsubsection Version Backups -@cindex version backups - -@cindex automatic version backups - When VC sees that the repository for a file is on a remote -machine, it automatically makes local backups of unmodified versions -of the file---@dfn{automatic version backups}. This means that you -can compare the file to the repository version (@kbd{C-x v =}), or -revert to that version (@kbd{C-x v u}), without any network -interactions. - - The local copy of the unmodified file is called a @dfn{version -backup} to indicate that it corresponds exactly to a version that is -stored in the repository. Note that version backups are not the same -as ordinary Emacs backup files -@iftex -(@pxref{Backup,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Backup}). -@end ifnottex -But they follow a similar naming convention. - - For a file that comes from a remote repository, VC makes a -version backup whenever you save the first changes to the file, and -removes it after you have committed your modified version to the -repository. You can disable the making of automatic version backups by -setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). - -@cindex manual version backups - The name of the automatic version backup for version @var{version} -of file @var{file} is @code{@var{file}.~@var{version}.~}. This is -almost the same as the name used by @kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Revisions}), -@end ifnottex -the only difference being the additional dot (@samp{.}) after the -version number. This similarity is intentional, because both kinds of -files store the same kind of information. The file made by @kbd{C-x v -~} acts as a @dfn{manual version backup}. - - All the VC commands that operate on old versions of a file can use -both kinds of version backups. For instance, @kbd{C-x v ~} uses -either an automatic or a manual version backup, if possible, to get -the contents of the version you request. Likewise, @kbd{C-x v =} and -@kbd{C-x v u} use either an automatic or a manual version backup, if -one of them exists, to get the contents of a version to compare or -revert to. If you changed a file outside of Emacs, so that no -automatic version backup was created for the previous text, you can -create a manual backup of that version using @kbd{C-x v ~}, and thus -obtain the benefit of the local copy for Emacs commands. - - The only difference in Emacs's handling of manual and automatic -version backups, once they exist, is that Emacs deletes automatic -version backups when you commit to the repository. By contrast, -manual version backups remain until you delete them. - -@node Local Version Control -@subsubsection Local Version Control -@cindex local version control -@cindex local back end (version control) - -When you make many changes to a file that comes from a remote -repository, it can be convenient to have version control on your local -machine as well. You can then record intermediate versions, revert to -a previous state, etc., before you actually commit your changes to the -remote server. - -VC lets you do this by putting a file under a second, local version -control system, so that the file is effectively registered in two -systems at the same time. For the description here, we will assume -that the remote system is CVS, and you use RCS locally, although the -mechanism works with any combination of version control systems -(@dfn{back ends}). - -To make it work with other back ends, you must make sure that the -``more local'' back end comes before the ``more remote'' back end in -the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By -default, this variable is set up so that you can use remote CVS and -local RCS as described here. - -To start using local RCS for a file that comes from a remote CVS -server, you must @emph{register the file in RCS}, by typing @kbd{C-u -C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a -prefix argument, and specify RCS as the back end.) - -You can do this at any time; it does not matter whether you have -already modified the file with respect to the version in the CVS -repository. If possible, VC tries to make the RCS master start with -the unmodified repository version, then checks in any local changes -as a new version. This works if you have not made any changes yet, or -if the unmodified repository version exists locally as a version -backup (@pxref{Version Backups}). If the unmodified version is not -available locally, the RCS master starts with the modified version; -the only drawback to this is that you cannot compare your changes -locally to what is stored in the repository. - -The version number of the RCS master is derived from the current CVS -version, starting a branch from it. For example, if the current CVS -version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in -the RCS master will be identical to version 1.23 under CVS; your first -changes are checked in as 1.23.1.1. (If the unmodified file is not -available locally, VC will check in the modified file twice, both as -1.23 and 1.23.1.1, to make the revision numbers consistent.) - -If you do not use locking under CVS (the default), locking is also -disabled for RCS, so that editing under RCS works exactly as under -CVS. - -When you are done with local editing, you can commit the final version -back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. -This initializes the log entry buffer -@iftex -(@pxref{Log Buffer,,,emacs, the Emacs Manual}) -@end iftex -@ifnottex -(@pxref{Log Buffer}) -@end ifnottex -to contain all the log entries you have recorded in the RCS master; -you can edit them as you wish, and then commit in CVS by typing -@kbd{C-c C-c}. If the commit is successful, VC removes the RCS -master, so that the file is once again registered under CVS only. -(The RCS master is not actually deleted, just renamed by appending -@samp{~} to the name, so that you can refer to it later if you wish.) - -While using local RCS, you can pick up recent changes from the CVS -repository into your local file, or commit some of your changes back -to CVS, without terminating local RCS version control. To do this, -switch to the CVS back end temporarily, with the @kbd{C-x v b} command: - -@table @kbd -@item C-x v b -Switch to another back end that the current file is registered -under (@code{vc-switch-backend}). - -@item C-u C-x v b @var{backend} @key{RET} -Switch to @var{backend} for the current file. -@end table - -@kindex C-x v b -@findex vc-switch-backend -@kbd{C-x v b} does not change the buffer contents, or any files; it -only changes VC's perspective on how to handle the file. Any -subsequent VC commands for that file will operate on the back end that -is currently selected. - -If the current file is registered in more than one back end, typing -@kbd{C-x v b} ``cycles'' through all of these back ends. With a -prefix argument, it asks for the back end to use in the minibuffer. - -Thus, if you are using local RCS, and you want to pick up some recent -changes in the file from remote CVS, first visit the file, then type -@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m -@key{RET}} to merge the news -@iftex -(@pxref{Merging,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Merging}). -@end ifnottex -You can then switch back to RCS by typing @kbd{C-x v b} again, and -continue to edit locally. - -But if you do this, the revision numbers in the RCS master no longer -correspond to those of CVS. Technically, this is not a problem, but -it can become difficult to keep track of what is in the CVS repository -and what is not. So we suggest that you return from time to time to -CVS-only operation, by committing your local changes back to the -repository using @kbd{C-u C-x v v cvs @key{RET}}. - -@node Revision Tags -@subsection Revision Tags -@cindex tags and version control - - In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS) -@dfn{tag} is a named set of file versions (one for each registered -file) that you can treat as a unit. In a VCS with per-repository -version numbers (Subversion and most later ones) a tag is simply -a symbolic name for a revision. - - One important kind of tag is a @dfn{release}, a (theoretically) -stable version of the system that is ready for distribution to users. - -@menu -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. -@end menu - -@node Making Revision Tags -@subsubsection Making and Using Revision Tags - - There are two basic commands for tags; one makes a -tag with a given name, the other retrieves a named tag. - -@table @code -@kindex C-x v s -@findex vc-create-tag -@item C-x v s @var{name} @key{RET} -Define the working revision of every registered file in or under the -current directory as a tag named @var{name} -(@code{vc-create-tag}). - -@kindex C-x v r -@findex vc-retrieve-tag -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, -retrieve the tagged revision @var{name}. This command will -switch to a branch if @var{name} is a branch name and your VCS -distinguishes branches from tags. -(@code{vc-retrieve-tag}). - -This command reports an error if any files are locked at or below the -current directory, without changing anything; this is to avoid -overwriting work in progress. -@end table - -Tags are inexpensive, so you need not hesitate to create them whenever -they are useful. Branches vary in cost depending on your VCS; in -older ones they may be expensive. - - You can give a tag or branch name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Revisions}). -@end ifnottex -Thus, you can use it to compare a tagged version against the current files, -or two tagged versions against each other. - -@node Revision Tag Caveats -@subsubsection Revision Tag Caveats - - For SCCS, VC implements tags itself; these tags are visible only -through VC. Most later systems (including CVS, Subversion, bzr, git, -and hg) have a native tag facility, and VC uses it where -available; those tags will be visible even when you bypass VC. - - There is no support for VC tags using GNU Arch yet. - - Under older VCSes (SCCS, RCS, CVS, early versions of Subversion), -renaming and deletion could create some difficulties with tags. This is -not a VC-specific problem, but a general design issue in version -control systems that was not solved effectively until the earliest -third-generation systems. - - In a file-oriented VCS, when you rename a registered file you need -to rename its master along with it; the command @code{vc-rename-file} -will do this automatically. If you are using SCCS, you must also -update the records of the tag, to mention the file by its new name -(@code{vc-rename-file} does this, too). An old tag that refers to a -master file that no longer exists under the recorded name is invalid; -VC can no longer retrieve it. It would be beyond the scope of this -manual to explain enough about RCS and SCCS to explain how to update -the tags by hand. - - Using @code{vc-rename-file} makes the tag remain valid for -retrieval, but it does not solve all problems. For example, some of the -files in your program probably refer to others by name. At the very -least, the makefile probably mentions the file that you renamed. If you -retrieve an old tag, the renamed file is retrieved under its new -name, which is not the name that the makefile expects. So the program -won't really work as retrieved. - @node Miscellaneous VC @subsection Miscellaneous Commands and Features of VC @@ -307,52 +12,55 @@ won't really work as retrieved. @menu * Change Logs and VC:: Generating a change log file from log entries. -* Renaming and VC:: A command to rename both the source and master - file correctly. +* VC Delete/Rename:: Deleting and renaming version-controlled files. +* Revision Tags:: Symbolic names for revisions. * Version Headers:: Inserting version control headers into working files. @end menu @node Change Logs and VC @subsubsection Change Logs and VC - If you use RCS or CVS for a program and also maintain a change log -file for it + If you use RCS or CVS for a program with a @file{ChangeLog} file @iftex (@pxref{Change Log,,,emacs, the Emacs Manual}), @end iftex @ifnottex (@pxref{Change Log}), @end ifnottex -you can generate change log entries automatically from the version -control log entries: +you can generate change log entries from the version control log +entries of previous commits. + + Note that this only works with RCS or CVS@. This procedure would be +particularly incorrect on a modern changeset-based version control +system, where changes to the @file{ChangeLog} file would normally be +committed as part of a changeset. In that case, you should write the +change log entries first, then pull them into the @samp{*vc-log*} +buffer when you commit +@iftex +(@pxref{Log Buffer,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Log Buffer}). +@end ifnottex @table @kbd @item C-x v a @kindex C-x v a @findex vc-update-change-log -Visit the current directory's change log file and, for registered files -in that directory, create new entries for versions checked in since the -most recent entry in the change log file. +Visit the current directory's @file{ChangeLog} file and, for +registered files in that directory, create new entries for versions +committed since the most recent change log entry (@code{vc-update-change-log}). -This command works with RCS or CVS only, not with any of the other -back ends. - @item C-u C-x v a As above, but only find entries for the current buffer's file. - -@item M-1 C-x v a -As above, but find entries for all the currently visited files that are -maintained with version control. This works only with RCS, and it puts -all entries in the log for the default directory, which may not be -appropriate. @end table For example, suppose the first line of @file{ChangeLog} is dated 1999-04-10, and that the only check-in since then was by Nathaniel -Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log -messages that start with `#'.}. Then @kbd{C-x v a} visits -@file{ChangeLog} and inserts text like this: +Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore +log messages that start with `#'.}. Then @kbd{C-x v a} inserts this +@file{ChangeLog} entry: @iftex @medbreak @@ -369,17 +77,11 @@ messages that start with `#'.}. Then @kbd{C-x v a} visits @end iftex @noindent -You can then edit the new change log entry further as you wish. - - Some of the new change log entries may duplicate what's already in -ChangeLog. You will have to remove these duplicates by hand. - - Normally, the log entry for file @file{foo} is displayed as @samp{* -foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted -if the text of the log entry starts with @w{@samp{(@var{functionname}): -}}. For example, if the log entry for @file{vc.el} is -@samp{(vc-do-command): Check call-process status.}, then the text in -@file{ChangeLog} looks like this: +If the version control log entry specifies a function name (in +parenthesis at the beginning of a line), that is reflected in the +@file{ChangeLog} entry. For example, if a log entry for @file{vc.el} +is @samp{(vc-do-command): Check call-process status.}, the +@file{ChangeLog} entry is: @iftex @medbreak @@ -395,221 +97,191 @@ if the text of the log entry starts with @w{@samp{(@var{functionname}): @medbreak @end iftex - When @kbd{C-x v a} adds several change log entries at once, it groups -related log entries together if they all are checked in by the same -author at nearly the same time. If the log entries for several such -files all have the same text, it coalesces them into a single entry. -For example, suppose the most recent check-ins have the following log -entries: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} -@end flushleft + When @kbd{C-x v a} adds several change log entries at once, it +groups related log entries together if they all are checked in by the +same author at nearly the same time. If the log entries for several +such files all have the same text, it coalesces them into a single +entry. -@noindent -They appear like this in @file{ChangeLog}: +@node VC Delete/Rename +@subsubsection Deleting and Renaming Version-Controlled Files +@cindex renaming version-controlled files -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch +@table @kbd +@item M-x vc-delete-file +Prompt for a file name, delete the file from the working tree, and +schedule the deletion for committing. - * vc.texinfo: Fix expansion typos. +@item M-x vc-rename-file +Prompt for two file names, @var{var} and @var{old}, rename them in the +working tree, and schedule the renaming for committing. +@end table - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample +@findex vc-delete-file + If you wish to delete a version-controlled file, use the command +@kbd{M-x vc-delete-file}. This prompts for the file name, and deletes +it via the version control system. The file is removed from the +working tree, and in the VC Directory buffer @iftex -@medbreak +(@pxref{VC Directory Mode,,, emacs, the Emacs Manual}), @end iftex +@ifnottex +(@pxref{VC Directory Mode}), +@end ifnottex +it is displayed with the @samp{removed} status. When you commit it, +the deletion takes effect in the repository. - Normally, @kbd{C-x v a} separates log entries by a blank line, but you -can mark several related log entries to be clumped together (without an -intervening blank line) by starting the text of each related log entry -with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label -itself is not copied to @file{ChangeLog}. For example, suppose the log -entries are: - -@flushleft -@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} -@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} -@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} -@end flushleft - -@noindent -Then the text in @file{ChangeLog} looks like this: +@findex vc-rename-file + To rename a version-controlled file, type @kbd{M-x vc-rename-file}. +This prompts for two arguments: the name of the file you wish to +rename, and the new name; then it performs the renaming via the +version control system. The renaming takes effect immediately in the +working tree, and takes effect in the repository when you commit the +renamed file. + + On modern version control systems that have built-in support for +renaming, the renamed file retains the full change history of the +original file. On CVS and older version control systems, the +@code{vc-rename-file} command actually works by creating a copy of the +old file under the new name, registering it, and deleting the old +file. In this case, the change history is not preserved. -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch +@node Revision Tags +@subsubsection Revision Tags +@cindex revision tag +@cindex tags for version control - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex + Most version control systems allow you to apply a @dfn{revision tag} +to a specific version of a version-controlled tree. On modern +changeset-based version control systems, a revision tag is simply a +symbolic name for a particular revision. On older file-based systems +like CVS, each tag is added to the entire set of version-controlled +files, allowing them to be handled as a unit. Revision tags are +commonly used to identify releases that are distributed to users. - A log entry whose text begins with @samp{#} is not copied to -@file{ChangeLog}. For example, if you merely fix some misspellings in -comments, you can log the change with an entry beginning with @samp{#} -to avoid putting such trivia into @file{ChangeLog}. + There are two basic commands for tags; one makes a tag with a given +name, the other retrieves a named tag. -@node Renaming and VC -@subsubsection Renaming VC Work Files and Master Files +@table @code +@kindex C-x v s +@findex vc-create-tag +@item C-x v s @var{name} @key{RET} +Define the working revision of every registered file in or under the +current directory as a tag named @var{name} +(@code{vc-create-tag}). -@findex vc-rename-file - When you rename a registered file, you must also rename its master -file correspondingly to get proper results. Use @code{vc-rename-file} -to rename the source file as you specify, and rename its master file -accordingly. It also updates any tags (@pxref{Revision Tags}) that -mention the file, so that they use the new name; despite this, the -tag thus modified may not completely work (@pxref{Revision Tag Caveats}). +@kindex C-x v r +@findex vc-retrieve-tag +@item C-x v r @var{name} @key{RET} +For all registered files at or below the current directory level, +retrieve the tagged revision @var{name}. This command will switch to a +branch if @var{name} is a branch name and your VCS distinguishes +branches from tags. (@code{vc-retrieve-tag}). - Some back ends do not provide an explicit rename operation to their -repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} -on the original and renamed buffers and provide the necessary edit -log. +This command reports an error if any files are locked at or below the +current directory, without changing anything; this is to avoid +overwriting work in progress. +@end table - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. + You can give a tag or branch name as an argument to @kbd{C-x v =} or +@kbd{C-x v ~} +@iftex +(@pxref{Old Revisions,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Old Revisions}). +@end ifnottex +Thus, you can use it to compare a tagged version against the current files, +or two tagged versions against each other. -@node Version Headers -@subsubsection Inserting Version Control Headers + On SCCS, VC implements tags itself; these tags are visible only +through VC@. Most later systems (including CVS, Subversion, bzr, git, +and hg) have a native tag facility, and VC uses it where available; +those tags will be visible even when you bypass VC. - Sometimes it is convenient to put version identification strings -directly into working files. Certain special strings called -@dfn{version headers} are replaced in each successive version by the -number of that version, the name of the user who created it, and other -relevant information. All of the back ends that VC supports have such -a mechanism, except GNU Arch. - - VC does not normally use the information contained in these headers. -The exception is RCS---with RCS, version headers are sometimes more -reliable than the master file to determine which version of the file -you are editing. Note that in a multi-branch environment, version -headers are necessary to make VC behave correctly + In file-based version control systems, when you rename a registered +file you need to rename its master along with it; the command +@code{vc-rename-file} will do this automatically @iftex -(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). +(@pxref{VC Delete/Rename,,,emacs, the Emacs Manual}). @end iftex @ifnottex -(@pxref{Multi-User Branching}). +(@pxref{VC Delete/Rename}). @end ifnottex +If you are using SCCS, you must also update the records of the tag, to +mention the file by its new name (@code{vc-rename-file} does this, +too). An old tag that refers to a master file that no longer exists +under the recorded name is invalid; VC can no longer retrieve it. It +would be beyond the scope of this manual to explain enough about RCS +and SCCS to explain how to update the tags by hand. Using +@code{vc-rename-file} makes the tag remain valid for retrieval, but it +does not solve all problems. For example, some of the files in your +program probably refer to others by name. At the very least, the +makefile probably mentions the file that you renamed. If you retrieve +an old tag, the renamed file is retrieved under its new name, which is +not the name that the makefile expects. So the program won't really +work as retrieved. + +@node Version Headers +@subsubsection Inserting Version Control Headers - Searching for RCS version headers is controlled by the variable -@code{vc-consult-headers}. If it is non-@code{nil} (the default), -Emacs searches for headers to determine the version number you are -editing. Setting it to @code{nil} disables this feature. + On Subversion, CVS, RCS, and SCCS, you can put certain special +strings called @dfn{version headers} into a work file. When the file +is committed, the version control system automatically puts the +revision number, the name of the user who made the commit, and other +relevant information into the version header. - Note that although CVS uses the same kind of version headers as RCS -does, VC never searches for these headers if you are using CVS, -regardless of the above setting. +@vindex vc-consult-headers + VC does not normally use the information in the version headers. As +an exception, when using RCS, Emacs uses the version header, if there +is one, to determine the file version, since it is often more reliable +than the RCS master file. To inhibit using the version header this +way, change the variable @code{vc-consult-headers} to @code{nil}. @kindex C-x v h @findex vc-insert-headers - You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to -insert a suitable header string. - -@table @kbd -@item C-x v h -Insert headers in a file for use with your version-control system. -@end table - @vindex vc-@var{backend}-header - The default header string is @samp{@w{$}Id$} for RCS and -@samp{@w{%}W%} for SCCS. You can specify other headers to insert by -setting the variables @code{vc-@var{backend}-header} where -@var{backend} is @code{rcs} or @code{sccs}. - - Instead of a single string, you can specify a list of strings; then -each string in the list is inserted as a separate header on a line of -its own. - - It may be necessary to use apparently-superfluous backslashes when -writing the strings that you put in this variable. For instance, you -might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra -backslash prevents the string constant from being interpreted as a -header, if the Emacs Lisp file containing it is maintained with -version control. - -@vindex vc-comment-alist - Each header is inserted surrounded by tabs, inside comment delimiters, -on a new line at point. Normally the ordinary comment -start and comment end strings of the current mode are used, but for -certain modes, there are special comment delimiters for this purpose; -the variable @code{vc-comment-alist} specifies them. Each element of -this list has the form @code{(@var{mode} @var{starter} @var{ender})}. + To insert a suitable header string into the current buffer, type +@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on +Subversion, CVS, RCS, and SCCS@. The variable +@code{vc-@var{backend}-header} contains the list of keywords to insert +into the version header; for instance, CVS uses @code{vc-cvs-header}, +whose default value is @code{'("\$Id\$")}. (The extra backslashes +prevent the string constant from being interpreted as a header, if the +Emacs Lisp file defining it is maintained with version control.) The +@kbd{C-x v h} command inserts each keyword in the list on a new line +at point, surrounded by tabs, and inside comment delimiters if +necessary. @vindex vc-static-header-alist The variable @code{vc-static-header-alist} specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form @code{(@var{regexp} . @var{format})}. Whenever -@var{regexp} matches the buffer name, @var{format} is inserted as part -of the header. A header line is inserted for each element that matches -the buffer name, and for each string specified by -@code{vc-@var{backend}-header}. The header line is made by processing the -string from @code{vc-@var{backend}-header} with the format taken from the -element. The default value for @code{vc-static-header-alist} is as follows: - -@example -@group -(("\\.c$" . - "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ -#endif /* lint */\n")) -@end group -@end example - -@noindent -It specifies insertion of text of this form: - -@example -@group - -#ifndef lint -static char vcid[] = "@var{string}"; -#endif /* lint */ -@end group -@end example - -@noindent -Note that the text above starts with a blank line. - - If you use more than one version header in a file, put them close -together in the file. The mechanism in @code{revert-buffer} that -preserves markers may not handle markers positioned between two version -headers. +@var{regexp} matches the buffer name, @var{format} is also inserted as +part of the version header. A @samp{%s} in @var{format} is replaced +with the file's version control type. @node Customizing VC @subsection Customizing VC @vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version + The variable @code{vc-handled-backends} determines which version control systems VC should handle. The default value is @code{(RCS CVS SVN SCCS Bzr Git Hg Mtn Arch)}, so it contains all the version systems that are currently supported. If you want VC to ignore one or more of -these systems, exclude its name from the list. To disable VC entirely, -set this variable to @code{nil}. - -The order of systems in the list is significant: when you visit a file -registered in more than one system (@pxref{Local Version Control}), VC -uses the system that comes first in @code{vc-handled-backends} by -default. The order is also significant when you register a file for -the first time, see +these systems, exclude its name from the list. To disable VC +entirely, set this variable to @code{nil}. + + The order of systems in the list is significant: when you visit a +file registered in more than one system, VC uses the system that comes +first in @code{vc-handled-backends} by default. The order is also +significant when you register a file for the first time @iftex -@ref{Registering,,,emacs, the Emacs Manual}, +(@pxref{Registering,,,emacs, the Emacs Manual}). @end iftex @ifnottex -@ref{Registering}, +(@pxref{Registering}). @end ifnottex -for details. @menu * General VC Options:: Options that apply to multiple back ends. @@ -626,47 +298,27 @@ maintained with version control. If you want to make backup files even for files that use version control, set the variable @code{vc-make-backup-files} to a non-@code{nil} value. -@vindex vc-keep-workfiles - Normally the work file exists all the time, whether it is locked or -not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking -in a new version with @kbd{C-x v v} deletes the work file; but any -attempt to visit the file with Emacs creates it again. (With CVS, work -files are always kept.) - @vindex vc-follow-symlinks - Editing a version-controlled file through a symbolic link can be -dangerous. It bypasses the version control system---you can edit the -file without locking it, and fail to check your changes in. Also, -your changes might overwrite those of another user. To protect against -this, VC checks each symbolic link that you visit, to see if it points -to a file under version control. - - The variable @code{vc-follow-symlinks} controls what to do when a -symbolic link points to a version-controlled file. If it is @code{nil}, -VC only displays a warning message. If it is @code{t}, VC automatically -follows the link, and visits the real file instead, telling you about -this in the echo area. If the value is @code{ask} (the default), VC -asks you each time whether to follow the link. +@cindex symbolic links (and version control) + Editing a version-controlled file through a symbolic link may cause +unexpected results, if you are unaware that the underlying file is +version-controlled. The variable @code{vc-follow-symlinks} controls +what Emacs does if you try to visit a symbolic link pointing to a +version-controlled file. If the value is @code{ask} (the default), +Emacs asks for confirmation. If it is @code{nil}, Emacs just displays +a warning message. If it is @code{t}, Emacs automatically follows the +link and visits the real file instead. @vindex vc-suppress-confirm If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} and @kbd{C-x v i} can save the current buffer without asking, and -@kbd{C-x v u} also operates without asking for confirmation. (This -variable does not affect @kbd{C-x v c}; that operation is so drastic -that it should always ask for confirmation.) +@kbd{C-x v u} also operates without asking for confirmation. @vindex vc-command-messages VC mode does much of its work by running the shell commands for the -appropriate backend. If @code{vc-command-messages} is non-@code{nil}, VC -displays messages to indicate which shell commands it runs, and -additional messages when the commands finish. - -@vindex vc-path - You can specify additional directories to search for version control -programs by setting the variable @code{vc-path}. These directories -are searched before the usual search path. It is rarely necessary to -set this variable, because VC normally finds the proper files -automatically. +appropriate version control system. If @code{vc-command-messages} is +non-@code{nil}, VC displays messages to indicate which shell commands +it runs, and additional messages when the commands finish. @node RCS and SCCS @subsubsection Options for RCS and SCCS @@ -708,81 +360,88 @@ changed erroneously, set @code{vc-mistrust-permissions} to @code{t}. Then VC always checks the master file to determine the file's status. VC determines the version control state of files under SCCS much as -with RCS. It does not consider SCCS version headers, though. Thus, +with RCS@. It does not consider SCCS version headers, though. Thus, the variable @code{vc-mistrust-permissions} affects SCCS use, but @code{vc-consult-headers} does not. @node CVS Options @subsubsection Options specific for CVS -@cindex locking (CVS) - By default, CVS does not use locking to coordinate the activities of -several users; anyone can change a work file at any time. However, -there are ways to restrict this, resulting in behavior that resembles -locking. - -@cindex CVSREAD environment variable (CVS) - For one thing, you can set the @env{CVSREAD} environment variable -(the value you use makes no difference). If this variable is defined, -CVS makes your work files read-only by default. In Emacs, you must -type @kbd{C-x v v} to make the file writable, so that editing works -in fact similar as if locking was used. Note however, that no actual -locking is performed, so several users can make their files writable -at the same time. When setting @env{CVSREAD} for the first time, make -sure to check out all your modules anew, so that the file protections -are set correctly. - -@cindex cvs watch feature -@cindex watching files (CVS) - Another way to achieve something similar to locking is to use the -@dfn{watch} feature of CVS. If a file is being watched, CVS makes it -read-only by default, and you must also use @kbd{C-x v v} in Emacs to -make it writable. VC calls @code{cvs edit} to make the file writable, -and CVS takes care to notify other developers of the fact that you -intend to change the file. See the CVS documentation for details on -using the watch feature. +@vindex vc-cvs-global-switches + You can specify additional command line options to pass to all CVS +operations in the variable @code{vc-cvs-global-switches}. These +switches are inserted immediately after the @code{cvs} command, before +the name of the operation to invoke. @vindex vc-stay-local @vindex vc-cvs-stay-local @cindex remote repositories (CVS) - When a file's repository is on a remote machine, VC tries to keep + When using a CVS repository on a remote machine, VC can try keeping network interactions to a minimum. This is controlled by the variable @code{vc-cvs-stay-local}. There is another variable, @code{vc-stay-local}, which enables the feature also for other back -ends that support it, including CVS. In the following, we will talk +ends that support it, including CVS@. In the following, we will talk only about @code{vc-cvs-stay-local}, but everything applies to @code{vc-stay-local} as well. -If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses -only the entry in the local CVS subdirectory to determine the file's -state (and possibly information returned by previous CVS commands). -One consequence of this is that when you have modified a file, and -somebody else has already checked in other changes to the file, you -are not notified of it until you actually try to commit. (But you can -try to pick up any recent changes from the repository first, using -@kbd{C-x v m @key{RET}}, + If @code{vc-cvs-stay-local} is @code{only-file} (the default), VC +determines the version control status of each file using only the +entry in the local CVS subdirectory and the information returned by +previous CVS commands. As a consequence, if you have modified a file +and somebody else has checked in other changes, you will not be +notified of the conflict until you try to commit. + + If you change @code{vc-cvs-stay-local} to @code{nil}, VC queries the +remote repository @emph{before} it decides what to do in +@code{vc-next-action} (@kbd{C-x v v}), just as it does for local +repositories. + + You can also set @code{vc-cvs-stay-local} to a regular expression +that is matched against the repository host name; VC then stays local +only for repositories from hosts that match the pattern. + +@cindex automatic version backups + When using a remote repository, Emacs normally makes @dfn{automatic +version backups} of the original versions of each edited file. These +local backups are made whenever you save the first changes to a file, +and they are removed after you commit your changes to the repository. +(Note that these are not the same as ordinary Emacs backup files; @iftex -@pxref{Merging,,,emacs, the Emacs Manual}). +@pxref{Backup,,,emacs, the Emacs Manual}.) @end iftex @ifnottex -@pxref{Merging}). +@pxref{Backup}.) @end ifnottex +Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic +version backups, if possible, to avoid having to access the network. - When @code{vc-cvs-stay-local} is @code{t}, VC also makes local -version backups, so that simple diff and revert operations are -completely local (@pxref{Version Backups}). + Setting @code{vc-cvs-stay-local} to @code{nil} disables the making +of automatic version backups. - On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, -then VC queries the remote repository @emph{before} it decides what to -do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local -repositories. It also does not make any version backups. - - You can also set @code{vc-cvs-stay-local} to a regular expression -that is matched against the repository host name; VC then stays local -only for repositories from hosts that match the pattern. +@cindex manual version backups + Automatic version backups have names of the form +@w{@code{@var{file}.~@var{version}.~}}. This is similar to the name +that @kbd{C-x v ~} saves old versions to +@iftex +(@pxref{Old Revisions,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{Old Revisions}), +@end ifnottex +except for the additional dot (@samp{.}) after the version. The +relevant VC commands can use both kinds of version backups. The main +difference is that the ``manual'' version backups made by @kbd{C-x v +~} are not deleted automatically when you commit. -@vindex vc-cvs-global-switches - You can specify additional command line options to pass to all CVS -operations in the variable @code{vc-cvs-global-switches}. These -switches are inserted immediately after the @code{cvs} command, before -the name of the operation to invoke. +@cindex locking (CVS) + CVS does not use locking by default, but there are ways to enable +locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; +see the CVS documentation for details. If that case, you can use +@kbd{C-x v v} in Emacs to toggle locking, as you would for a +locking-based version control system +@iftex +(@pxref{VC With A Locking VCS,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{VC With A Locking VCS}). +@end ifnottex