mirror of
git://git.sv.gnu.org/emacs.git
synced 2026-02-17 10:27:41 +00:00
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.
This commit is contained in:
Chong Yidong
parent
204ee57fa0
commit
d3098e1ec6
6 changed files with 260 additions and 518 deletions
|
|
@ -1,3 +1,27 @@
|
|||
2011-12-21 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* 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 <acm@muc.de>
|
||||
|
||||
* programs.texi (Motion in C): Update the description of C-M-a and
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
@ -556,32 +555,28 @@ operation, but accepts additional arguments to specify precisely how
|
|||
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}).
|
||||
|
||||
@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.
|
||||
|
||||
@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
|
||||
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
|
||||
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 @@ 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
@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
|
||||
|
||||
@noindent
|
||||
They appear like this in @file{ChangeLog}:
|
||||
|
||||
@iftex
|
||||
@medbreak
|
||||
@end iftex
|
||||
@smallexample
|
||||
@group
|
||||
1999-04-01 Nathaniel Bowditch <nat@@apn.org>
|
||||
|
||||
* vc.texinfo: Fix expansion typos.
|
||||
|
||||
* vc.el, vc-hooks.el: Don't call expand-file-name.
|
||||
@end group
|
||||
@end smallexample
|
||||
@iftex
|
||||
@medbreak
|
||||
@end 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 @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:
|
||||
|
||||
@iftex
|
||||
@medbreak
|
||||
@end iftex
|
||||
@smallexample
|
||||
@group
|
||||
1999-04-01 Nathaniel Bowditch <nat@@apn.org>
|
||||
|
||||
* vc.texinfo: Fix expansion typos.
|
||||
* vc.el, vc-hooks.el: Don't call expand-file-name.
|
||||
@end group
|
||||
@end smallexample
|
||||
@iftex
|
||||
@medbreak
|
||||
@end iftex
|
||||
|
||||
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}.
|
||||
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.
|
||||
|
||||
@node Renaming and VC
|
||||
@subsubsection Renaming VC Work Files and Master Files
|
||||
@cindex renaming version-controlled files
|
||||
|
||||
@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
|
||||
|
||||
@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}).
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
You cannot use @code{vc-rename-file} on a file that is locked by
|
||||
someone else.
|
||||
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
|
||||
@subsubsection Revision Tags
|
||||
@cindex revision tag
|
||||
@cindex 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
|
||||
@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
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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}},
|
||||
@iftex
|
||||
@pxref{Merging,,,emacs, the Emacs Manual}).
|
||||
@end iftex
|
||||
@ifnottex
|
||||
@pxref{Merging}).
|
||||
@end ifnottex
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
@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 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{Backup,,,emacs, the Emacs Manual}.)
|
||||
@end iftex
|
||||
@ifnottex
|
||||
@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.
|
||||
|
||||
Setting @code{vc-cvs-stay-local} to @code{nil} disables the making
|
||||
of automatic version backups.
|
||||
|
||||
@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.
|
||||
|
||||
@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}).
|
||||
|
|
|
|||
Loading…
Reference in a new issue