Commit f3b316df authored by Chong Yidong's avatar Chong Yidong

Fixes for Maintaining chapter of Emacs manual.

* doc/emacs/maintaining.texi (Version Control Systems): Drop Meta-CVS.
(Basic VC Editing): Remove redundant descriptions.
(VC With A Merging VCS): Make description more general instead of
CVS-specific.
(VC With A Locking VCS): Use VC fileset terminology.
parent 99a289d9
2011-12-16 Chong Yidong <cyd@gnu.org>
* maintaining.texi (Version Control Systems): Drop Meta-CVS.
(Basic VC Editing): Remove redundant descriptions.
(VC With A Merging VCS): Make description more general instead of
CVS-specific.
(VC With A Locking VCS): Use VC fileset terminology.
2011-12-12 Chong Yidong <cyd@gnu.org> 2011-12-12 Chong Yidong <cyd@gnu.org>
* building.texi (Executing Lisp): Fix xref for C-M-x. * building.texi (Executing Lisp): Fix xref for C-M-x.
......
...@@ -24,9 +24,9 @@ assist in the process of compiling and testing programs. ...@@ -24,9 +24,9 @@ assist in the process of compiling and testing programs.
* Executing Lisp:: Various modes for editing Lisp programs, * Executing Lisp:: Various modes for editing Lisp programs,
with different facilities for running with different facilities for running
the Lisp programs. the Lisp programs.
* Lisp Libraries:: How Lisp programs are loaded into Emacs. * Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs.
* Lisp Eval:: Executing a single Lisp expression in Emacs. * Eval: Lisp Eval. Executing a single Lisp expression in Emacs.
* Lisp Interaction:: Executing Lisp in an Emacs buffer. * Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer.
* External Lisp:: Communicating through Emacs with a separate Lisp. * External Lisp:: Communicating through Emacs with a separate Lisp.
@end menu @end menu
......
...@@ -71,7 +71,7 @@ control operations. ...@@ -71,7 +71,7 @@ control operations.
Some uncommon or intricate version control operations, such as Some uncommon or intricate version control operations, such as
altering repository settings, are not supported in VC. You should altering repository settings, are not supported in VC. You should
perform such tasks outside Emacs, e.g. via the command line. perform such tasks outside Emacs, e.g.@: via the command line.
This section provides a general overview of version control, and This section provides a general overview of version control, and
describes the version control systems that VC supports. You can skip describes the version control systems that VC supports. You can skip
...@@ -125,7 +125,7 @@ which it refers to as @dfn{back ends}: ...@@ -125,7 +125,7 @@ which it refers to as @dfn{back ends}:
@item @item
SCCS was the first version control system ever built, and was long ago SCCS was the first version control system ever built, and was long ago
superseded by more advanced ones. VC compensates for certain features superseded by more advanced ones. VC compensates for certain features
missing in SCCS (e.g., tag names for releases) by implementing them missing in SCCS (e.g.@: tag names for releases) by implementing them
itself. Other VC features, such as multiple branches, are simply itself. Other VC features, such as multiple branches, are simply
unavailable. Since SCCS is non-free, we recommend avoiding it. unavailable. Since SCCS is non-free, we recommend avoiding it.
...@@ -154,7 +154,7 @@ moving/renaming. VC supports all basic editing operations under CVS. ...@@ -154,7 +154,7 @@ moving/renaming. VC supports all basic editing operations under CVS.
@cindex SVN @cindex SVN
@cindex Subversion @cindex Subversion
@item @item
Subversion (SVN) is a free version control system designed to be Subversion (svn) is a free version control system designed to be
similar to CVS but without its problems (e.g., it supports atomic similar to CVS but without its problems (e.g., it supports atomic
commits of filesets, and versioning of directories, symbolic links, commits of filesets, and versioning of directories, symbolic links,
meta-data, renames, copies, and deletes). meta-data, renames, copies, and deletes).
...@@ -189,10 +189,6 @@ both repository-based and distributed versioning. VC supports most ...@@ -189,10 +189,6 @@ both repository-based and distributed versioning. VC supports most
basic editing operations under Bazaar. basic editing operations under Bazaar.
@end itemize @end itemize
Previous versions of VC supported a version control system known as
Meta-CVS. This support was dropped due to limited interest from users
and developers.
@node VCS Concepts @node VCS Concepts
@subsubsection Concepts of Version Control @subsubsection Concepts of Version Control
...@@ -264,7 +260,7 @@ number and severity of conflicts that actually occur. ...@@ -264,7 +260,7 @@ number and severity of conflicts that actually occur.
SCCS always uses locking. RCS is lock-based by default but can be SCCS always uses locking. RCS is lock-based by default but can be
told to operate in a merging style. CVS and Subversion are told to operate in a merging style. CVS and Subversion are
merge-based by default but can be told to operate in a locking mode. merge-based by default but can be told to operate in a locking mode.
Distributed version control systems, such as GNU Arch, git, and Distributed version control systems, such as GNU Arch, Git, and
Mercurial, are exclusively merging-based. Mercurial, are exclusively merging-based.
VC mode supports both locking and merging version control. The VC mode supports both locking and merging version control. The
...@@ -302,7 +298,7 @@ kind of model. One of its drawbacks is that the repository is a choke ...@@ -302,7 +298,7 @@ kind of model. One of its drawbacks is that the repository is a choke
point for reliability and efficiency. point for reliability and efficiency.
GNU Arch pioneered the concept of @dfn{decentralized} version GNU Arch pioneered the concept of @dfn{decentralized} version
control, later implemented in git, Mercurial, and Bazaar. A project control, later implemented in Git, Mercurial, and Bazaar. A project
may have several different repositories, and these systems support a may have several different repositories, and these systems support a
sort of super-merge between repositories that tries to reconcile their sort of super-merge between repositories that tries to reconcile their
change histories. In effect, there is one repository for each change histories. In effect, there is one repository for each
...@@ -409,37 +405,35 @@ VC fileset is simply that one file. When you type them in a VC ...@@ -409,37 +405,35 @@ VC fileset is simply that one file. When you type them in a VC
Directory buffer, and some files in it are marked, the VC fileset Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}). consists of the marked files (@pxref{VC Directory Mode}).
The principal VC command is an all-purpose command, @kbd{C-x v v} On Subversion and on decentralized version control systems,
(@code{vc-next-action}), that performs either registration, locking, multi-file VC filesets are handled as a single group by the relevant
merging or a check-in (depending on the situation) on the current VC version control commands. For example, committing a multi-file VC
fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a fileset generates a single revision, consisting of all the changes to
VC Directory buffer. those files. But on older version control systems which lack support
for group operations, such as CVS, the files in a multi-file VC
fileset are passed individually to version control commands (e.g.@: a
commit generates one revision for each changed file).
@table @kbd @table @kbd
@itemx C-x v v @itemx C-x v v
Perform the appropriate next version control operation on the VC fileset. Perform the next appropriate version control operation on the current
VC fileset.
@end table @end table
@findex vc-next-action @findex vc-next-action
@kindex C-x v v @kindex C-x v v
The precise action of @kbd{C-x v v} depends on the state of the VC The principal VC command is an all-purpose command, @kbd{C-x v v}
fileset, and whether the version control system uses locking or (@code{vc-next-action}), which performs the ``most appropriate''
merging. This is described in detail in the subsequent sections. action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes
VC filesets are the way that VC mode bridges the gap between into it. The precise actions are described in detail in the following
file-based and changeset-based version control systems. They are, subsections. You can use @kbd{C-x v v} either in a file-visiting
essentially, a way to pass multiple file arguments as a group to buffer or in a VC Directory buffer.
version control commands. For example, on Subversion, a checkin with
a multi-file VC fileset becomes a joint commit, as though you had Note that VC filesets are distinct from the ``named filesets'' used
typed @command{svn commit} with those file arguments at the shell for viewing and visiting files in functional groups
command line. All files in a VC fileset must be under the same (@pxref{Filesets}). Unlike named filesets, VC filesets are not named
version control system; if they are not, Emacs signals an error when and don't persist across sessions.
you attempt to execute a command on the fileset.
VC filesets are distinct from the ``named filesets'' used for
viewing and visiting files in functional groups (@pxref{Filesets}).
Unlike named filesets, VC filesets are not named and don't persist
across sessions.
@menu @menu
* VC With A Merging VCS:: Without locking: default mode for CVS. * VC With A Merging VCS:: Without locking: default mode for CVS.
...@@ -450,46 +444,41 @@ across sessions. ...@@ -450,46 +444,41 @@ across sessions.
@node VC With A Merging VCS @node VC With A Merging VCS
@subsubsection Basic Version Control with Merging @subsubsection Basic Version Control with Merging
When your version control system is merging-based (the default for On a merging-based version control system (i.e.@: most modern ones;
CVS and all newer version control systems), work files are always @pxref{VCS Merging}), @kbd{C-x v v} does the following:
writable; you need not do anything special to begin editing a file.
The status indicator on the mode line is @samp{-} if the file is
unmodified; it flips to @samp{:} as soon as you save any changes
(@pxref{VC Mode Line}).
Here is what @kbd{C-x v v} does when using a merging-based system:
@itemize @bullet @itemize @bullet
@item @item
If the work file is in a directory that is not controlled by any If there is more than one file in the VC fileset and the files have
version control system, prompt for a repository type. Then, create a inconsistent version control states, signal an error.
version control repository of that type and register the file with it.
@item @item
If the work file is in a directory that is controlled by a version If each file in the VC fileset is not registered with a version
control system but not registered with it, register the file. control system, register the VC fileset. If the fileset is in a
directory controlled by a version control system, register it with
that system; otherwise, prompt for a repository type, create a new
repository, and register the VC fileset with it.
@item @item
If the work file is the same as in the repository, do nothing. If each work file in the VC fileset is unchanged, do nothing.
@item @item
If you have not changed the work file, but some other user has checked If each work file in the VC fileset has been modified, commit the
in changes to the repository, merge those changes into the work file. changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{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.
@item @item
If you have made modifications to the work file, attempt to commit Finally, if you are using a centralized version control system, check
the changes. To do this, Emacs first reads the log entry for the new if each work file in the VC fileset is up-to-date. If any file has
revision (@pxref{Log Buffer}). If some other user has committed been changed in the repository, offer to update it.
changes to the repository since you last checked it out, the checkin
fails. In that case, type @kbd{C-x v v} again to merge those changes
into your own work file; this puts the work file into a ``conflicted''
state. Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then
regards the file as up-to-date and modified, and you can try to check
it in again.
To pick up any recent changes from the repository @emph{without}
trying to commit your own changes, type @kbd{C-x v m @key{RET}}.
@xref{Merging}.
@end itemize @end itemize
These rules also apply when you use RCS in its ``non-locking'' mode, These rules also apply when you use RCS in its ``non-locking'' mode,
...@@ -506,32 +495,44 @@ its normal locking mode (@pxref{VC With A Locking VCS}). ...@@ -506,32 +495,44 @@ its normal locking mode (@pxref{VC With A Locking VCS}).
@node VC With A Locking VCS @node VC With A Locking VCS
@subsubsection Basic Version Control with Locking @subsubsection Basic Version Control with Locking
Under a locking-based version control system (such as SCCS, and RCS On a locking-based version control system (such as SCCS, and RCS in
in its default mode), @kbd{C-x v v} does the following: its default mode), @kbd{C-x v v} does the following:
@itemize @bullet @itemize @bullet
@item @item
If the file is not locked, lock it and make it writable, so that you If there is more than one file in the VC fileset and the files have
can change it. inconsistent version control states, signal an error.
@item
If each file in the VC fileset is not registered with a version
control system, register the VC fileset. If the fileset is in a
directory controlled by a version control system, register it with
that system; otherwise, prompt for a repository type, create a new
repository, and register the VC fileset with it.
@item
If each file is registed and unlocked, lock it and make it writable,
so that you can begin to edit it.
@item @item
If the file is locked by you, and contains changes, commit the If each file is locked by you and contains changes, commit the
changes. In order to do this, Emacs first reads the log entry for the changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
new revision. @xref{Log Buffer}. desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).
@item @item
If the file is locked by you, but you have not changed it since you If each file is locked by you, but you have not changed it, release
locked it, release the lock and makes the file read-only again. the lock and make the file read-only again.
@item @item
If the file is locked by some other user, ask whether you want to If each file is locked by another user, ask whether you want to
``steal the lock'' from that user. If you say yes, the file becomes ``steal the lock''. If you say yes, the file becomes locked by you,
locked by you, but a message is sent to the person who had formerly and a warning message is sent to the user who had formerly locked the
locked the file, to inform him of what has happened. file.
@end itemize @end itemize
These rules also apply when you use CVS in locking mode, except These rules also apply when you use CVS in locking mode, except
that CVS does not support stealing a lock. that CVS does not support stealing locks.
@node Advanced C-x v v @node Advanced C-x v v
@subsubsection Advanced Control in @kbd{C-x v v} @subsubsection Advanced Control in @kbd{C-x v v}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment