[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r106710: More updates for VC document
|
From: |
Chong Yidong |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r106710: More updates for VC documentation. |
|
Date: |
Wed, 21 Dec 2011 16:39:32 +0800 |
|
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 106710
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Wed 2011-12-21 16:39:32 +0800
message:
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.
modified:
doc/emacs/ChangeLog
doc/emacs/emacs.texi
doc/emacs/files.texi
doc/emacs/maintaining.texi
doc/emacs/programs.texi
doc/emacs/vc1-xtra.texi
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog 2011-12-20 16:00:47 +0000
+++ b/doc/emacs/ChangeLog 2011-12-21 08:39:32 +0000
@@ -1,3 +1,27 @@
+2011-12-21 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* programs.texi (Motion in C): Update the description of C-M-a and
=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi 2011-12-20 03:00:10 +0000
+++ b/doc/emacs/emacs.texi 2011-12-21 08:39:32 +0000
@@ -747,7 +747,6 @@
* 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 @@
* 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
=== modified file 'doc/emacs/files.texi'
--- a/doc/emacs/files.texi 2011-12-03 16:17:29 +0000
+++ b/doc/emacs/files.texi 2011-12-21 08:39:32 +0000
@@ -1498,6 +1498,7 @@
If @var{new} is not an existing directory, it copies all the contents
of @var{old} into a new directory named @var{new}.
address@hidden 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 @@
applies to all the remaining commands in this section. All of them
ask for confirmation when the new file name already exists, too.
address@hidden
+ 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}.
address@hidden ifnottex
+
@findex add-name-to-file
@cindex hard links (creation)
@kbd{M-x add-name-to-file} adds an additional name to an existing
=== modified file 'doc/emacs/maintaining.texi'
--- a/doc/emacs/maintaining.texi 2011-12-20 03:00:10 +0000
+++ b/doc/emacs/maintaining.texi 2011-12-21 08:39:32 +0000
@@ -56,8 +56,6 @@
* 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 @@
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 @@
@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}).
-
address@hidden
-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.
-
address@hidden
@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
address@hidden
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
address@hidden iftex
address@hidden
-(@pxref{Local Version Control}).
address@hidden ifnottex
-
+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.
+
address@hidden
+Otherwise, if using CVS or RCS, you can specify a revision ID.
+
+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 @@
this command searches that item for entries matching the file(s) to be
committed, and inserts them.
@ifnottex
address@hidden 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 @@
(@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 @@
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 @@
-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.
=== modified file 'doc/emacs/programs.texi'
--- a/doc/emacs/programs.texi 2011-12-20 16:00:47 +0000
+++ b/doc/emacs/programs.texi 2011-12-21 08:39:32 +0000
@@ -606,12 +606,13 @@
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
address@hidden 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
address@hidden c-guess
address@hidden 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
=== modified file 'doc/emacs/vc1-xtra.texi'
--- a/doc/emacs/vc1-xtra.texi 2011-12-20 03:00:10 +0000
+++ b/doc/emacs/vc1-xtra.texi 2011-12-21 08:39:32 +0000
@@ -5,229 +5,148 @@
@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).
address@hidden Remote Repositories
address@hidden Remote Repositories
address@hidden 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.
address@hidden Miscellaneous VC
address@hidden Miscellaneous Commands and Features of VC
+
+ This section explains the less-frequently-used features of VC.
@menu
-* Version Backups:: Keeping local copies of repository versions.
-* Local Version Control:: Using another version system for local editing.
+* 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
address@hidden Version Backups
address@hidden Version Backups
address@hidden version backups
-
address@hidden 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 address@hidden 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
address@hidden
-(@pxref{Backup,,,emacs, the Emacs Manual}).
address@hidden iftex
address@hidden
-(@pxref{Backup}).
address@hidden 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}).
-
address@hidden manual version backups
- The name of the automatic version backup for version @var{version}
-of file @var{file} is @address@hidden@var{version}.~}. This is
-almost the same as the name used by @kbd{C-x v ~}
address@hidden
-(@pxref{Old Revisions,,,emacs, the Emacs Manual}),
address@hidden iftex
address@hidden
-(@pxref{Old Revisions}),
address@hidden 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
address@hidden 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.
-
address@hidden Local Version Control
address@hidden Local Version Control
address@hidden local version control
address@hidden 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
address@hidden
-(@pxref{Log Buffer,,,emacs, the Emacs Manual})
address@hidden iftex
address@hidden
-(@pxref{Log Buffer})
address@hidden 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
address@hidden 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
address@hidden 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:
-
address@hidden @kbd
address@hidden C-x v b
-Switch to another back end that the current file is registered
-under (@code{vc-switch-backend}).
-
address@hidden C-u C-x v b @var{backend} @key{RET}
-Switch to @var{backend} for the current file.
address@hidden table
-
address@hidden C-x v b
address@hidden vc-switch-backend
address@hidden 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
address@hidden 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
address@hidden v b} to switch to CVS, and finally use @kbd{C-x v m
address@hidden to merge the news
address@hidden
-(@pxref{Merging,,,emacs, the Emacs Manual}).
address@hidden iftex
address@hidden
-(@pxref{Merging}).
address@hidden 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}}.
address@hidden Change Logs and VC
address@hidden Change Logs and VC
+
+ If you use RCS or CVS for a program with a @file{ChangeLog} file
address@hidden
+(@pxref{Change Log,,,emacs, the Emacs Manual}),
address@hidden iftex
address@hidden
+(@pxref{Change Log}),
address@hidden ifnottex
+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
address@hidden
+(@pxref{Log Buffer,,,emacs, the Emacs Manual}).
address@hidden iftex
address@hidden
+(@pxref{Log Buffer}).
address@hidden ifnottex
+
address@hidden @kbd
address@hidden C-x v a
address@hidden C-x v a
address@hidden vc-update-change-log
+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}).
+
address@hidden C-u C-x v a
+As above, but only find entries for the current buffer's file.
address@hidden 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 entry @samp{Ignore
+log messages that start with `#'.}. Then @kbd{C-x v a} inserts this
address@hidden entry:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-05-22 Nathaniel Bowditch <nat@@apn.org>
+
+ * rcs2log: Ignore log messages that start with `#'.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
+
address@hidden
+If the version control log entry specifies a function name (in
+parenthesis at the beginning of a line), that is reflected in the
address@hidden entry. For example, if a log entry for @file{vc.el}
+is @samp{(vc-do-command): Check call-process status.}, the
address@hidden entry is:
+
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
+1999-05-06 Nathaniel Bowditch <nat@@apn.org>
+
+ * vc.el (vc-do-command): Check call-process status.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden 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.
+
address@hidden Renaming and VC
address@hidden Renaming VC Work Files and Master Files
address@hidden renaming version-controlled files
+
address@hidden @kbd
address@hidden M-x vc-rename-file
+Prompt for two file names, @var{VAR} and @var{OLD}, and rename them in
+the version-controlled working tree.
address@hidden table
+
address@hidden 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.
@node Revision Tags
address@hidden Revision Tags
address@hidden tags and version control
-
- In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS)
address@hidden 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.
-
address@hidden
-* Making Revision Tags:: The tag facilities.
-* Revision Tag Caveats:: Things to be careful of when using tags.
address@hidden menu
-
address@hidden Making Revision Tags
address@hidden 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.
address@hidden Revision Tags
address@hidden revision tag
address@hidden tags for version control
+
+ 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.
+
+ 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
@@ -241,20 +160,15 @@
@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}).
+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
@@ -266,21 +180,10 @@
Thus, you can use it to compare a tagged version against the current files,
or two tagged versions against each other.
address@hidden Revision Tag Caveats
address@hidden Revision Tag Caveats
-
- For SCCS, VC implements tags itself; these tags are visible only
+ 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.
-
- 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.
+and hg) have a native tag facility, and VC uses it where available;
+those tags will be visible even when you bypass VC.
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}
@@ -290,197 +193,13 @@
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.
-
address@hidden Miscellaneous VC
address@hidden Miscellaneous Commands and Features of VC
-
- This section explains the less-frequently-used features of VC.
-
address@hidden
-* 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.
-* Version Headers:: Inserting version control headers into working files.
address@hidden menu
-
address@hidden Change Logs and VC
address@hidden Change Logs and VC
-
- If you use RCS or CVS for a program and also maintain a change log
-file for it
address@hidden
-(@pxref{Change Log,,,emacs, the Emacs Manual}),
address@hidden iftex
address@hidden
-(@pxref{Change Log}),
address@hidden ifnottex
-you can generate change log entries automatically from the version
-control log entries:
-
address@hidden @kbd
address@hidden C-x v a
address@hidden C-x v a
address@hidden 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.
-(@code{vc-update-change-log}).
-
-This command works with RCS or CVS only, not with any of the other
-back ends.
-
address@hidden C-u C-x v a
-As above, but only find entries for the current buffer's file.
-
address@hidden 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.
address@hidden 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
address@hidden and inserts text like this:
-
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
-1999-05-22 Nathaniel Bowditch <nat@@apn.org>
-
- * rcs2log: Ignore log messages that start with `#'.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
-
address@hidden
-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 @address@hidden(@var{functionname}):
-}}. For example, if the log entry for @file{vc.el} is
address@hidden(vc-do-command): Check call-process status.}, then the text in
address@hidden looks like this:
-
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
-1999-05-06 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.el (vc-do-command): Check call-process status.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden 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:
-
address@hidden
address@hidden For @file{vc.texinfo}: @samp{Fix expansion typos.}
address@hidden For @file{vc.el}: @samp{Don't call expand-file-name.}
address@hidden For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
address@hidden flushleft
-
address@hidden
-They appear like this in @file{ChangeLog}:
-
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
-1999-04-01 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.texinfo: Fix expansion typos.
-
- * vc.el, vc-hooks.el: Don't call expand-file-name.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
-
- 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 @address@hidden@address@hidden@} }}. The label
-itself is not copied to @file{ChangeLog}. For example, suppose the log
-entries are:
-
address@hidden
address@hidden For @file{vc.texinfo}: @address@hidden@} Fix expansion typos.}
address@hidden For @file{vc.el}: @address@hidden@} Don't call expand-file-name.}
address@hidden For @file{vc-hooks.el}: @address@hidden@} Don't call
expand-file-name.}
address@hidden flushleft
-
address@hidden
-Then the text in @file{ChangeLog} looks like this:
-
address@hidden
address@hidden
address@hidden iftex
address@hidden
address@hidden
-1999-04-01 Nathaniel Bowditch <nat@@apn.org>
-
- * vc.texinfo: Fix expansion typos.
- * vc.el, vc-hooks.el: Don't call expand-file-name.
address@hidden group
address@hidden smallexample
address@hidden
address@hidden
address@hidden iftex
-
- A log entry whose text begins with @samp{#} is not copied to
address@hidden 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}.
-
address@hidden Renaming and VC
address@hidden Renaming VC Work Files and Master Files
-
address@hidden 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.
-
- You cannot use @code{vc-rename-file} on a file that is locked by
-someone else.
+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 @@
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 @@
@node CVS Options
@subsubsection Options specific for CVS
address@hidden 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.
-
address@hidden 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.
-
address@hidden cvs watch feature
address@hidden watching files (CVS)
- Another way to achieve something similar to locking is to use the
address@hidden 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.
address@hidden 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 @@
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
address@hidden v m @key{RET}},
address@hidden
address@hidden,,,emacs, the Emacs Manual}).
address@hidden iftex
address@hidden
address@hidden).
address@hidden ifnottex
-
- 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}).
-
- 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.
+ 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
address@hidden (@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.
address@hidden 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.
address@hidden 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;
address@hidden
address@hidden,,,emacs, the Emacs Manual}.)
address@hidden iftex
address@hidden
address@hidden)
address@hidden 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.
+
+ Setting @code{vc-cvs-stay-local} to @code{nil} disables the making
+of automatic version backups.
+
address@hidden manual version backups
+ Automatic version backups have names of the form
address@hidden@address@hidden@var{version}.~}}. This is similar to the name
+that @kbd{C-x v ~} saves old versions to
address@hidden
+(@pxref{Old Revisions,,,emacs, the Emacs Manual}),
address@hidden iftex
address@hidden
+(@pxref{Old Revisions}),
address@hidden 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.
+
address@hidden 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
address@hidden v v} in Emacs to toggle locking, as you would for a
+locking-based version control system (@pxref{VC With A Locking VCS}).
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r106710: More updates for VC documentation.,
Chong Yidong <=