procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

(Types of Log File): Change logs are older than version control.

Browse source 
(VCS Concepts): Simplify and rearrange.
(Version Control Systems): Make it clear that Linux is only the kernel.
(VC Mode Line): Shorten reference to menu item.
(Basic VC Editing): Clarify VC fileset.  Shorten and simplify.
(VC Directory Mode): Minor cleanup.
Unchanged files are hidden, not omitted.
(VC Directory Commands): Shorten and simplify.
(Change Log Commands): New node, split from Change Logs.
(VC Directory Buffer): New node, split from VC Directory Mode.
This commit is contained in:
Richard M. Stallman 2008-11-01 01:58:34 +00:00
parent 6cda144ffe
commit a11d373796
2 changed files with 89 additions and 94 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
doc/emacs/ChangeLog
View file

@ -1,3 +1,17 @@
2008-11-01 Richard M. Stallman <rms@gnu.org>
* maintaining.texi (Types of Log File): Change logs are older than
version control.
(VCS Concepts): Simplify and rearrange.
(Version Control Systems): Make it clear that Linux is only the kernel.
(VC Mode Line): Shorten reference to menu item.
(Basic VC Editing): Clarify VC fileset. Shorten and simplify.
(VC Directory Mode): Minor cleanup.
Unchanged files are hidden, not omitted.
(VC Directory Commands): Shorten and simplify.
(Change Log Commands): New node, split from Change Logs.
(VC Directory Buffer): New node, split from VC Directory Mode.
2008-10-31 Chong Yidong <cyd@stupidchicken.com>
* misc.texi (Document View): Renamed from Document Files, moved here

169
doc/emacs/maintaining.texi
View file

@ -170,7 +170,7 @@ sometimes invoke it from the command line.
@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 @@ on the version control system; in the simplest case, it is just an
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 @@ unable to because it is locked. In merging systems, @dfn{merge
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 @@ but to the changeset itself.
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 @@ Log}). It provides a chronological record of all changes to a large
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 @@ instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
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 @@ system, but is usually not excessive.
@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 @@ 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.
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 @@ window.
@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 @@ need to merge them with the work file before you can check it in.
@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 @@ this includes Version Control subdirectories such as @samp{RCS} and
@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 @@ If the underlying VC supports atomic commits of multiple-file
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 @@ during this particular editing session.
@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 @@ one of its parent directories. A single @file{ChangeLog} file can
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 @@ insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
(@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