Mercurial > emacs

--- a/doc/emacs/maintaining.texi	Sat Nov 01 01:24:33 2008 +0000
+++ b/doc/emacs/maintaining.texi	Sat Nov 01 01:58:13 2008 +0000
@@ -170,7 +170,7 @@
 @cindex git
 @item
 Git is a distributed version control system invented by Linus Torvalds to support
-Linux kernel development.  It supports atomic commits of filesets and
+development of Linux (his kernel).  It supports atomic commits of filesets and
 file moving/renaming.  One significant feature of git is that it
 largely abolishes the notion of a single centralized repository;
 instead, each working copy of a git project is its own repository and
@@ -229,11 +229,10 @@
 integer.

   To go beyond these basic concepts, you will need to understand three
-ways in which version control systems can differ from each other.
+aspects in which version control systems differ.
 They can be locking-based or merging-based; they can be file-based or
 changeset-based; and they can be centralized or decentralized.  VC
-handles all these choices, but they lead to differing behaviors which
-you will need to understand as you use it.
+handles all these modes of operation, but it cannot hide the differences.

 @cindex locking versus merging
   A version control system typically has some mechanism to coordinate
@@ -263,21 +262,21 @@
 conflicts} happen when you check in a change to a file that conflicts
 with a change checked in by someone else after your checkout.  Both
 kinds of conflict have to be resolved by human judgment and
-communication.
+communication.  Experience has shown that merging is superior to
+locking, both in convenience to developers and in minimizing the
+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
-Mercurial, are exclusively merging-based.  Experience has shown that
-merging is superior to locking, both in convenience to developers and
-in minimizing the number and severity of conflicts that actually
-occur.  Sometimes, however, newer version control systems may have
-locks retrofitted onto them for reasons having nothing to do with
-technology@footnote{Usually the control-freak instincts of managers.}.
+Mercurial, are exclusively merging-based.

-  VC mode supports both locking and merging version control and tries
-to hide the differences between them as much as possible.
+  VC mode supports both locking and merging version control.  The
+terms ``checkin'' and ``checkout'' come from locking-based version
+control systems; newer version control systems have slightly different
+operations usually called ``commit'' and ``update'', but VC hides the
+differences between them as much as possible.

 @cindex files versus changesets.
   On SCCS, RCS, CVS, and other early version control systems, version
@@ -292,33 +291,21 @@
   Changeset-based version control is more flexible and powerful than
 file-based version control; usually, when a change to multiple files
 has to be reversed, it's good to be able to easily identify and remove
-all of it.  But it took some years for designers to figure that out,
-and while file-based systems are passing out of use, there are lots of
-legacy repositories still to be dealt with as of this writing (2008).
-
-  Prior to Emacs 23, VC supported only file-based systems, leading to
-unhappy results when it was used to drive changeset-based
-systems---the Subversion support, for example, used to break up
-changesets into multiple per-file commits.  This has been fixed, but
-it has left a mark in VC's terminology.  The terms ``checkin'' and
-``checkout'' are associated with file-based and locking-based systems
-and a bit archaic; nowadays those operations are usually called
-``commit'' and ``update''.
+all of it.

 @cindex centralized vs. decentralized version control
   Early version control systems were designed around a
 @dfn{centralized} model in which each project has only one repository
 used by all developers.  SCCS, RCS, CVS, and Subversion share this
-kind of model.  One problem with this approach is that a single
-repository is a single point of failure---if the repository server is
-down, all work stops.
+kind of model.  One of its drawbacks is that the repository is a choke
+point for reliability and efficiency.

-  Newer version control systems like GNU Arch, git, Mercurial, and
-Bazaar are @dfn{decentralized}.  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.  At the
-limit, each developer has his/her own repository, and repository
-merges replace checkin/commit operations.
+  GNU Arch pioneered the concept of @dfn{decentralized} version
+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.  At the limit, each developer has his/her own
+repository, and repository merges replace checkin/commit operations.

   VC's job is to help you manage the traffic between your personal
 workfiles and a repository.  Whether that repository is a single
@@ -343,20 +330,14 @@
 portion of a program---typically one directory and its subdirectories.
 A small program would use one @file{ChangeLog} file; a large program
 may have a @file{ChangeLog} file in each major directory.
-@xref{Change Log}.
+@xref{Change Log}.  Programmers have used change logs since long
+before version control systems.

-  Actually, the fact that both kinds of log exist is partly a legacy
-from file-based version control.  Changelogs are a GNU convention,
-later more widely adopted, that help developers to get a
-changeset-based view of a project even when its version control system
-has that information split up in multiple file-based logs.
-
-  Changeset-based version systems, on the other hand, often maintain a
-changeset-based modification log for the entire system that makes
-ChangeLogs somewhat redundant.  One advantage that ChangeLogs retain
-is that it is sometimes useful to be able to view the transaction
-history of a single directory separately from those of other
-directories.
+  Changeset-based version systems typically maintain a changeset-based
+modification log for the entire system, which makes change log files
+somewhat redundant.  One advantage that they retain is that it is
+sometimes useful to be able to view the transaction history of a
+single directory separately from those of other directories.

   A project maintained with version control can use just the version
 control log, or it can use both kinds of logs.  It can handle some
@@ -395,8 +376,7 @@
 indicator to pop up a ``tool-tip'', which displays a more verbose
 description of the version control status.  Pressing @kbd{Mouse-1}
 over the indicator pops up a menu of VC commands.  This menu is
-identical to the @samp{Version Control} menu item, which can be found
-in the @samp{Tools} menu on the menu bar.
+identical to the @samp{Tools / Version Control} menu item.

 @vindex auto-revert-check-vc-info
   When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
@@ -413,25 +393,23 @@
 @node Basic VC Editing
 @subsection Basic Editing under Version Control

-@cindex filesets
+@cindex filesets, VC
    Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
-group of one or more files that are treated as a unit, for the
-purposes of version control.
-
-   If you are visiting a version-controlled file in the current
-buffer, the VC fileset is simply that one file.  If you are visiting a
-VC directory buffer, and some files in it are marked, the VC fileset
+collection of one or more files that a VC operation acts on.  When you
+type VC commands in a buffer visiting a version-controlled file, the
+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 locking, merging or a
-check-in on the current VC fileset, depending on the situation.  You
-can call @kbd{C-x v v} from a version-controlled file, or from the VC
-Directory buffer.
+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.

 @table @kbd
 @itemx C-x v v
-Perform the next logical version control operation on the VC fileset.
+Perform the appropriate next version control operation on the VC fileset.
 @end table

 @findex vc-next-action
@@ -450,15 +428,11 @@
 version control system; if they are not, Emacs signals an error when
 you attempt to execute a command on the fileset.

-  If you are accustomed to previous versions of VC, most of the
-changes to VC in Emacs 23 are found in VC directory mode (@pxref{VC
-Directory Mode}).  When multiple files are marked in the VC directory
-buffer, they are treated as a VC fileset; typing @kbd{C-x v v} in the
-VC directory buffer passes them to the version control backends as a
-single unit.  Other commands in VC directory mode now act on the VC
-fileset, rather than the file on the current line.  These changes
-allow VC to interoperate correctly with changeset-based version
-control systems.
+  Support for VC filesets and changeset-based version control systems
+is the main improvement to VC in Emacs 23.  When you mark multi-file
+VC in a VC Directory buffer, VC operations treat them as a VC fileset,
+and operate on them all at once if the version control system is
+changeset-based.  @xref{VC Directory Mode}

   VC filesets are distinct from the ``named filesets'' used for
 viewing and visiting files in functional groups (@pxref{Filesets}).
@@ -1001,19 +975,26 @@
 @cindex PCL-CVS
 @pindex cvs
 @cindex CVS directory mode
-  The VC Directory buffer described here works with all the version
-control systems that VC supports.  Another more powerful facility,
-designed specifically for CVS, is called PCL-CVS.  @xref{Top, , About
-PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+  The VC Directory buffer works with all the version control systems
+that VC supports.  For CVS, Emacs also offers a more powerful facility
+called PCL-CVS.  @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The
+Emacs Front-End to CVS}.
+
+@menu
+* Buffer: VC Directory Buffer.      What the buffer looks like and means.
+* Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
+@end menu
+
+@node VC Directory Buffer
+@subsubsection The VC Directory Buffer

   The VC Directory buffer contains a list of version-controlled files
 in the current directory and its subdirectories.  Files which are
 up-to-date (have no local differences from the repository copy) are
-omitted; if all files in a directory are up-to-date, the directory is
-omitted as well.  (However, the directory in which @code{vc-dir} was
-run will always be shown as @file{./}.)  There is an exception to this
-rule: if VC mode detects that a file has changed to an up-to-date
-state since you last looked at it, that file and its state are shown.
+usually hidden; if all files in a subdirectory are up-to-date, the
+subdirectory is hidden as well.  There is an exception to this rule:
+if VC mode detects that a file has changed to an up-to-date state
+since you last looked at it, that file and its state are shown.

   If a directory uses more that one version control system, you can
 select which system to use for the @code{vc-dir} command by invoking
@@ -1043,7 +1024,7 @@
 @vindex vc-cvs-stay-local
   In the above, if the repository were on a remote machine, VC only
 contacts it when the variable @code{vc-stay-local} (or
-@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}).  This is
+@code{vc-cvs-stay-local}) is @code{nil} (@pxref{CVS Options}).  This is
 because access to the repository may be slow, or you may be working
 offline and not have access to the repository at all.  As a
 consequence, VC would not be able to tell you that @samp{file3.c} is
@@ -1064,10 +1045,6 @@
 @samp{CVS}; you can customize this by setting the variable
 @code{vc-directory-exclusion-list}.

-@menu
-* VC Directory Commands:: Commands to use in a VC directory buffer.
-@end menu
-
 @node VC Directory Commands
 @subsubsection VC Directory Commands

@@ -1134,12 +1111,12 @@
 changesets, @kbd{C-x v v} with a selected set of modified but not
 committed files will commit all of them at once as a single changeset.

-  When @kbd{C-x v v} (@code{vc-next-action}) operates on a set of files,
-it requires that all of those files must be either in the same state or
-in compatible states; otherwise it will throw an error (added,
-modified and removed states are considered compatible).  Note that this
-differs from the behavior of older versions of VC, which did not have
-fileset operations and simply did @code{vc-next-action} on each file
+  When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple
+files, all of those files must be either in the same state or in
+compatible states (added, modified and removed states are considered
+compatible).  Otherwise it signals an error.  This differs from the
+behavior of older versions of VC, which did not have fileset
+operations and simply did @code{vc-next-action} on each file
 individually.

   If any files are in a state that calls for commit, @kbd{C-x v v} reads a
@@ -1365,6 +1342,7 @@
 @node Change Log
 @section Change Logs

+@cindex change log
   A change log file contains a chronological record of when and why you
 have changed a program, consisting of a sequence of entries describing
 individual changes.  Normally it is kept in a file called
@@ -1373,7 +1351,14 @@
 record changes for all the files in its directory and all its
 subdirectories.

-@cindex change log
+@menu
+* Change Log Commands:: Commands for editing change log files.
+* Format of ChangeLog:: What the change log file looks like.
+@end menu
+
+@node Change Log Commands
+@subsection Change Log Commands
+
 @kindex C-x 4 a
 @findex add-change-log-entry-other-window
   The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
@@ -1440,10 +1425,6 @@
 (@pxref{Change Logs and VC}).
 @end ifnottex

-@menu
-* Format of ChangeLog:: What the change log file looks like.
-@end menu
-
 @node Format of ChangeLog
 @subsection Format of ChangeLog