From d3098e1ec618fc043568be481b487f3bf7689bad Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 21 Dec 2011 16:39:32 +0800 Subject: [PATCH] More updates for VC documentation. * files.texi (Misc File Ops): Mention vc-rename-file. * maintaining.texi (Advanced C-x v v): Use fileset terminology. (VC With A Merging VCS, VC Change Log): Add xref to VC Pull node. (VC Pull): Mention vc-log-incoming. (Log Buffer): Add CVS/RCS only disclaimer. * vc1-xtra.texi (Remote Repositories): Update introduction. (Local Version Control): Node deleted (obsolete with DVCSes). (Remote Repositories, Version Backups): Node deleted. Move documentation of vc-cvs-stay-local to CVS Options. (CVS Options): Reduce verbosity of description of obscure CVS locking feature. (Making Revision Tags, Revision Tag Caveats): Merge into Revision Tags node. (Revision Tags): Move under Miscellaneous VC subsection. (Change Logs and VC): Note that this is wrong for DVCSs. De-document log entry manipulating features. (Renaming and VC): Describe how it works on modern VCSes. * programs.texi (Custom C Indent): Add index entries. --- doc/emacs/ChangeLog | 24 ++ doc/emacs/emacs.texi | 12 +- doc/emacs/files.texi | 8 + doc/emacs/maintaining.texi | 76 ++--- doc/emacs/programs.texi | 11 +- doc/emacs/vc1-xtra.texi | 627 ++++++++++--------------------------- 6 files changed, 250 insertions(+), 508 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index 22f9a4ae7cc..8e2b278f84b 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,27 @@ +2011-12-21 Chong Yidong + + * maintaining.texi (Advanced C-x v v): Use fileset terminology. + (VC With A Merging VCS, VC Change Log): Add xref to VC Pull node. + (VC Pull): Mention vc-log-incoming. + (Log Buffer): Add CVS/RCS only disclaimer. + + * vc1-xtra.texi (Remote Repositories): Update introduction. + (Local Version Control): Node deleted (obsolete with DVCSes). + (Remote Repositories, Version Backups): Node deleted. Move + documentation of vc-cvs-stay-local to CVS Options. + (CVS Options): Reduce verbosity of description of obscure CVS + locking feature. + (Making Revision Tags, Revision Tag Caveats): Merge into Revision + Tags node. + (Revision Tags): Move under Miscellaneous VC subsection. + (Change Logs and VC): Note that this is wrong for DVCSs. + De-document log entry manipulating features. + (Renaming and VC): Describe how it works on modern VCSes. + + * files.texi (Misc File Ops): Mention vc-rename-file. + + * programs.texi (Custom C Indent): Add index entries. + 2011-12-20 Alan Mackenzie * programs.texi (Motion in C): Update the description of C-M-a and diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index d3caf4e63df..b12cdf6ddd1 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -747,7 +747,6 @@ Version Control * VC Undo:: Canceling changes before or after committing. * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. -* Remote Repositories:: Efficient access to remote CVS servers. * Revision Tags:: Symbolic names for revisions. * Miscellaneous VC:: Various other commands and features of VC. * Customizing VC:: Variables that change VC's behavior. @@ -780,21 +779,12 @@ Multiple Branches of a File * Merging:: Transferring changes between branches. * Creating Branches:: How to start a new branch. -Remote Repositories - -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. - -Revision Tags - -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. - Miscellaneous Commands and Features of VC * 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. +* Revision Tags:: Symbolic names for revisions. * Version Headers:: Inserting version control headers into working files. Customizing VC diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index e3da0ca44e6..96c38f4190e 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1498,6 +1498,7 @@ it creates a copy of the @var{old} directory and puts it in @var{new}. If @var{new} is not an existing directory, it copies all the contents of @var{old} into a new directory named @var{new}. +@cindex renaming files @findex rename-file @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using the minibuffer, then renames file @var{old} as @var{new}. If @@ -1512,6 +1513,13 @@ RET /tmp RET} renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all the remaining commands in this section. All of them ask for confirmation when the new file name already exists, too. +@ifnottex + Note that if a file is under version control (@pxref{Version +Control}), you normally ought to rename it via the version control +system instead, using @kbd{M-x vc-rename-file}. @xref{Renaming and +VC}. +@end ifnottex + @findex add-name-to-file @cindex hard links (creation) @kbd{M-x add-name-to-file} adds an additional name to an existing diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 8bf7d74f9b6..488bdf87320 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -56,8 +56,6 @@ variable @code{vc-handled-backends} to @code{nil} * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. @ifnottex -* Remote Repositories:: Efficient access to remote CVS servers. -* Revision Tags:: Symbolic names for revisions. * Miscellaneous VC:: Various other commands and features of VC. * Customizing VC:: Variables that change VC's behavior. @end ifnottex @@ -482,10 +480,11 @@ commit. @xref{Log Buffer}. If committing to a shared repository, the commit may fail if the repository that has been changed since your last update. In that -case, you must perform an update before trying again. If using a -decentralized version control system, use @kbd{C-x v +} or @kbd{C-x v -m} (@pxref{Merging}). If using a centralized version control system, -type @kbd{C-x v v} again to merge in the repository changes. +case, you must perform an update before trying again. On a +decentralized version control system, use @kbd{C-x v +} (@pxref{VC +Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version +control system, type @kbd{C-x v v} again to merge in the repository +changes. @item Finally, if you are using a centralized version control system, check @@ -557,31 +556,27 @@ to do the operation. @itemize @bullet @item -If the file is modified (or locked), you can specify the revision ID -to use for the new version that you commit. This is one way to create -a new branch (@pxref{Branches}). +@cindex specific version control system +You can specify the name of a version control system. This is useful +if the fileset can be managed by more than one version control system, +and Emacs fails to detect the correct one. @item -If the file is not modified (and unlocked), you can specify the -revision to select; this lets you start working from an older -revision, or on another branch. If you do not enter any revision, -that takes you to the highest (``head'') revision on the current -branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to -get the latest version of a file from the repository. +Otherwise, if using CVS or RCS, you can specify a revision ID. -@item -@cindex specific version control system -Instead of the revision ID, you can also specify the name of a -version control system. This is useful when one file is being managed -with two version control systems at the same time -@iftex -(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs -Features}). -@end iftex -@ifnottex -(@pxref{Local Version Control}). -@end ifnottex +If the fileset is modified (or locked), this makes Emacs commit with +that revision ID. You can create a new branch by supplying an +appropriate revision ID (@pxref{Branches}). +If the fileset is unmodified (and unlocked), this checks the specified +revision into the working tree. You can also specify a revision on +another branch by giving its revision or branch ID (@pxref{Switching +Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}}) +checks out the latest (``head'') revision on the current branch. + +This signals an error on a decentralized version control system. +Those systems do not let you specify your own revision IDs, nor do +they use the concept of ``checking out'' individual files. @end itemize @node Log Buffer @@ -646,8 +641,9 @@ the @samp{*vc-log*} buffer. If the topmost item in each this command searches that item for entries matching the file(s) to be committed, and inserts them. @ifnottex -@xref{Change Logs and VC}, for the opposite way of -working---generating ChangeLog entries from the Log Edit buffer. +If you are using CVS or RCS, see @ref{Change Logs and VC}, for the +opposite way of working---generating ChangeLog entries from the Log +Edit buffer. @end ifnottex To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that @@ -935,13 +931,13 @@ revision at point. A second @key{RET} hides it again. (@code{vc-log-incoming}) command displays a log buffer showing the changes that will be applied, the next time you run the version control system's ``pull'' command to get new revisions from another -repository. This other repository is the default one from which -changes are pulled, as defined by the version control system; with a -prefix argument, @code{vc-log-incoming} prompts for a specific -repository. Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows -the changes that will be sent to another repository, the next time you -run the ``push'' command; with a prefix argument, it prompts for a -specific destination repository. +repository (@pxref{VC Pull}). This other repository is the default +one from which changes are pulled, as defined by the version control +system; with a prefix argument, @code{vc-log-incoming} prompts for a +specific repository. Similarly, @kbd{C-x v O} +(@code{vc-log-outgoing}) shows the changes that will be sent to +another repository, the next time you run the ``push'' command; with a +prefix argument, it prompts for a specific destination repository. In the @samp{*vc-change-log*} buffer, you can use the following keys to move between the logs of revisions and of files, and to examine and @@ -1339,8 +1335,8 @@ command to use, which lets you specify where to pull changes from. Otherwise, it pulls from a default location determined by the version control system. - Amongst decentralized version control systems, @kbd{C-x v +} -currently supports only Bazaar, Git, and Mercurial. On Bazaar, it + Amongst decentralized version control systems, @kbd{C-x v +} is +currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it calls @command{bzr pull} for ordinary branches (to pull from a master branch into a mirroring branch), and @command{bzr update} for a bound branch (to pull from a central repository). On Git, it calls @@ -1349,6 +1345,10 @@ it into the current branch. On Mercurial, it calls @command{hg pull -u} to fetch changesets from the default remote repository and update the working directory. + Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming}) +to view a log buffer of the changes to be applied. @xref{VC Change +Log}. + On a centralized version control system like CVS, @kbd{C-x v +} updates the current VC fileset from the repository. diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index 892c574734b..e2051a93c60 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -606,12 +606,13 @@ information on customizing indentation for C and related modes, including how to override parts of an existing style and how to define your own styles. - As an alternative to specifying a style, you can get Emacs to -@dfn{guess} the style by scanning a code buffer which is already -formatted. To do this, call @kbd{M-x c-guess} in your sample buffer. -You can then apply this guessed style to other buffers with @kbd{M-x +@findex c-guess +@findex c-guess-install + As an alternative to specifying a style, you can tell Emacs to guess +a style by typing @kbd{M-x c-guess} in a sample code buffer. You can +then apply the guessed style to other buffers with @kbd{M-x c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode -Manual}, for more details about this mechanism. +Manual}, for details. @node Parentheses @section Commands for Editing with Parentheses diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index c4a4b351cac..700003db58a 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -5,301 +5,6 @@ @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 @@ -309,50 +14,54 @@ won't really work as retrieved. * 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. +* 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 +78,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,92 +98,108 @@ 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: + 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. -@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 +@node Renaming and VC +@subsubsection Renaming VC Work Files and Master Files +@cindex renaming version-controlled files -@noindent -They appear like this in @file{ChangeLog}: +@table @kbd +@item M-x vc-rename-file +Prompt for two file names, @var{VAR} and @var{OLD}, and rename them in +the version-controlled working tree. +@end table -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch +@findex vc-rename-file + If you wish to rename a registered file in a version-controlled +working tree, use the command @kbd{M-x vc-rename-file}. This prompts +for two arguments: the file you wish to rename, followed by the new +name; then it performs the renaming through the version control +system. + + On modern version control systems that have built-in support for +renaming, the renaming operation takes effect immediately in the +working tree, and takes effect in the repository when you commit the +renamed file. 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. - * vc.texinfo: Fix expansion typos. +@node Revision Tags +@subsubsection Revision Tags +@cindex revision tag +@cindex tags for version control - * 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. - 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: + There are two basic commands for tags; one makes a tag with a given +name, the other retrieves a named tag. -@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 +@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}). -@noindent -Then the text in @file{ChangeLog} looks like this: +@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}). -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch +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 - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample + You can give a tag or branch name as an argument to @kbd{C-x v =} or +@kbd{C-x v ~} @iftex -@medbreak +(@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. - 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}. - -@node Renaming and VC -@subsubsection Renaming VC Work Files and Master Files - -@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}). - - 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. + 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. - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. + 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 Version Headers @subsubsection Inserting Version Control Headers @@ -592,10 +311,9 @@ 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 +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, see @iftex @ref{Registering,,,emacs, the Emacs Manual}, @end iftex @@ -708,37 +426,16 @@ the variable @code{vc-mistrust-permissions} affects SCCS use, but @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 @@ -746,36 +443,58 @@ 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{t} (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 (@pxref{VC With A Locking VCS}). -- 2.39.2