From f3b316df6114d1b93d3b69c59802148d9656c4d4 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 17 Dec 2011 00:05:59 +0800 Subject: [PATCH] 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. --- doc/emacs/ChangeLog | 8 ++ doc/emacs/building.texi | 6 +- doc/emacs/maintaining.texi | 153 +++++++++++++++++++------------------ 3 files changed, 88 insertions(+), 79 deletions(-) diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index c26f1a7e1ca..412a9cd5a58 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,11 @@ +2011-12-16 Chong Yidong + + * 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 * building.texi (Executing Lisp): Fix xref for C-M-x. diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index ab4a485cb87..47a3329f88d 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -24,9 +24,9 @@ assist in the process of compiling and testing programs. * Executing Lisp:: Various modes for editing Lisp programs, with different facilities for running the Lisp programs. -* Lisp Libraries:: How Lisp programs are loaded into Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. +* Libraries: Lisp Libraries. How Lisp programs are loaded into Emacs. +* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. +* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. * External Lisp:: Communicating through Emacs with a separate Lisp. @end menu diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 354812edc1f..eed14c07216 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -71,7 +71,7 @@ control operations. Some uncommon or intricate version control operations, such as 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 describes the version control systems that VC supports. You can skip @@ -125,7 +125,7 @@ which it refers to as @dfn{back ends}: @item SCCS was the first version control system ever built, and was long ago 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 unavailable. Since SCCS is non-free, we recommend avoiding it. @@ -154,7 +154,7 @@ moving/renaming. VC supports all basic editing operations under CVS. @cindex SVN @cindex Subversion @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 commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes). @@ -189,10 +189,6 @@ both repository-based and distributed versioning. VC supports most basic editing operations under Bazaar. @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 @subsubsection Concepts of Version Control @@ -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 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. -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. 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 point for reliability and efficiency. 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 sort of super-merge between repositories that tries to reconcile their 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 Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (@pxref{VC Directory Mode}). - The principal VC command is an all-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), that performs either registration, locking, -merging or a check-in (depending on the situation) on the current VC -fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a -VC Directory buffer. + On Subversion and on decentralized version control systems, +multi-file VC filesets are handled as a single group by the relevant +version control commands. For example, committing a multi-file VC +fileset generates a single revision, consisting of all the changes to +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 @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 @findex vc-next-action @kindex C-x v v - The precise action of @kbd{C-x v v} depends on the state of the VC -fileset, and whether the version control system uses locking or -merging. This is described in detail in the subsequent sections. - - VC filesets are the way that VC mode bridges the gap between -file-based and changeset-based version control systems. They are, -essentially, a way to pass multiple file arguments as a group to -version control commands. For example, on Subversion, a checkin with -a multi-file VC fileset becomes a joint commit, as though you had -typed @command{svn commit} with those file arguments at the shell -command line. All files in a VC fileset must be under the same -version control system; if they are not, Emacs signals an error when -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. + The principal VC command is an all-purpose command, @kbd{C-x v v} +(@code{vc-next-action}), which performs the ``most appropriate'' +action on the current VC fileset: either registering it with a version +control system, or committing it, or unlocking it, or merging changes +into it. The precise actions are described in detail in the following +subsections. You can use @kbd{C-x v v} either in a file-visiting +buffer or in a VC Directory buffer. + + Note that 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 * VC With A Merging VCS:: Without locking: default mode for CVS. @@ -450,46 +444,41 @@ across sessions. @node VC With A Merging VCS @subsubsection Basic Version Control with Merging - When your version control system is merging-based (the default for -CVS and all newer version control systems), work files are always -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: + On a merging-based version control system (i.e.@: most modern ones; +@pxref{VCS Merging}), @kbd{C-x v v} does the following: @itemize @bullet @item -If the work file is in a directory that is not controlled by any -version control system, prompt for a repository type. Then, create a -version control repository of that type and register the file with it. +If there is more than one file in the VC fileset and the files have +inconsistent version control states, signal an error. @item -If the work file is in a directory that is controlled by a version -control system but not registered with it, register the file. +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 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 -If you have not changed the work file, but some other user has checked -in changes to the repository, merge those changes into the work file. +If each work file in the VC fileset has been modified, commit the +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 -If you have made modifications to the work file, attempt to commit -the changes. To do this, Emacs first reads the log entry for the new -revision (@pxref{Log Buffer}). If some other user has committed -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}. +Finally, if you are using a centralized version control system, check +if each work file in the VC fileset is up-to-date. If any file has +been changed in the repository, offer to update it. @end itemize 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}). @node VC With A Locking VCS @subsubsection Basic Version Control with Locking - Under a locking-based version control system (such as SCCS, and RCS -in its default mode), @kbd{C-x v v} does the following: + On a locking-based version control system (such as SCCS, and RCS in +its default mode), @kbd{C-x v v} does the following: @itemize @bullet @item -If the file is not locked, lock it and make it writable, so that you -can change it. +If there is more than one file in the VC fileset and the files have +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 -If the file is locked by you, and contains changes, commit the -changes. In order to do this, Emacs first reads the log entry for the -new revision. @xref{Log Buffer}. +If each file is locked by you and contains changes, commit the +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}). @item -If the file is locked by you, but you have not changed it since you -locked it, release the lock and makes the file read-only again. +If each file is locked by you, but you have not changed it, release +the lock and make the file read-only again. @item -If the file is locked by some other user, ask whether you want to -``steal the lock'' from that user. If you say yes, the file becomes -locked by you, but a message is sent to the person who had formerly -locked the file, to inform him of what has happened. +If each file is locked by another user, ask whether you want to +``steal the lock''. If you say yes, the file becomes locked by you, +and a warning message is sent to the user who had formerly locked the +file. @end itemize 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 @subsubsection Advanced Control in @kbd{C-x v v} -- 2.39.2