Commit b981e2c6 authored by Eric S. Raymond's avatar Eric S. Raymond
Browse files

Update manual for 2007 conditions. None of these changes are

specific to new VC, that wil come later.
parent 0d0e9356
2007-10-06 Eric S. Raymond <esr@snark.thyrsus.com>
* files.texi: Update the section on version control for 2007
conditions. None of these changes are new-VC-specific; that
will come later.
2007-09-15 Glenn Morris <rgm@gnu.org> 2007-09-15 Glenn Morris <rgm@gnu.org>
* calendar.texi (Holidays): Change all instances of `holiday-list' back * calendar.texi (Holidays): Change all instances of `holiday-list' back
......
...@@ -1248,9 +1248,12 @@ customizable variable @code{vc-handled-backends} to @code{nil} ...@@ -1248,9 +1248,12 @@ customizable variable @code{vc-handled-backends} to @code{nil}
@subsection Introduction to Version Control @subsection Introduction to Version Control
VC allows you to use a version control system from within Emacs, VC allows you to use a version control system from within Emacs,
integrating the version control operations smoothly with editing. VC integrating the version control operations smoothly with editing.
provides a uniform interface to version control, so that regardless of Though VC cannot completely bridge the gaps between version-control
which version control system is in use, you can use it the same way. systems with widely differing capabilities, it does provide
a uniform interface to many version control operations. Regardless of
which version control system is in use, you will be able to do basic
operations in much the same way.
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
...@@ -1268,7 +1271,7 @@ you want to use. ...@@ -1268,7 +1271,7 @@ you want to use.
@subsubsection Understanding the problems it addresses @subsubsection Understanding the problems it addresses
Version control systems provide you with three important capabilities: Version control systems provide you with three important capabilities:
reversibility, concurrency, and history. @dfn{reversibility}. @dfn{concurrency}, and @dfn{history}.
The most basic capability you get from a version-control system is The most basic capability you get from a version-control system is
reversibility, the ability to back up to a saved, known-good state when reversibility, the ability to back up to a saved, known-good state when
...@@ -1292,15 +1295,16 @@ become a vitally important form of communication among developers. ...@@ -1292,15 +1295,16 @@ become a vitally important form of communication among developers.
``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. ``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.
@cindex CVS @cindex CVS
CVS is a free version control system that is used for the majority CVS is the free version control system that was until recently (as of
of free software projects today. It allows concurrent multi-user 2007) used for the majority of free software projects, though it is now
development either locally or over the network. Some of its being superseded by other systems. It allows concurrent
shortcomings, corrected by newer systems such as GNU Arch, are that it multi-user development either locally or over the network. Some of its
lacks atomic commits or support for renaming files. VC supports all shortcomings, corrected by newer systems such as Subversion or GNU Arch,
basic editing operations under CVS, but for some less common tasks you are that it lacks atomic commits or support for renaming files. VC
still need to call CVS from the command line. Note also that before supports all basic editing operations under CVS, but for some less
using CVS you must set up a repository, which is a subject too complex common tasks you still need to call CVS from the command line. Note
to treat here. also that before using CVS you must set up a repository, which is a
subject too complex to treat here.
@cindex GNU Arch @cindex GNU Arch
@cindex Arch @cindex Arch
...@@ -1315,62 +1319,50 @@ the command line, or use a specialized module. ...@@ -1315,62 +1319,50 @@ the command line, or use a specialized module.
@cindex RCS @cindex RCS
RCS is the free version control system around which VC was initially RCS is the free version control system around which VC was initially
built. The VC commands are therefore conceptually closest to RCS. built. Almost everything you can do with RCS can be done through VC. You
Almost everything you can do with RCS can be done through VC. You cannot use RCS over the network, though, and it only works at the level
cannot use RCS over the network though, and it only works at the level
of individual files, rather than projects. You should use it if you of individual files, rather than projects. You should use it if you
want a simple, yet reliable tool for handling individual files. want a simple, yet reliable tool for handling individual files.
@cindex SVN @cindex SVN
@cindex Subversion @cindex Subversion
Subversion is a free version control system designed to be similar Subversion is a free version control system designed to be similar to
to CVS but without CVS's problems. Subversion supports atomic commits, CVS but without CVS's problems, and is now (2007) rapidly superseding
and versions directories, symbolic links, meta-data, renames, copies, CVS. Subversion supports atomic commits, and versions directories,
and deletes. It can be used via http or via its own protocol. symbolic links, meta-data, renames, copies, and deletes. It can be used
via http or via its own protocol.
@cindex MCVS
@cindex Meta-CVS
Meta-CVS is another attempt to solve problems arising in CVS. It
supports directory structure versioning, improved branching and
merging, and use of symbolic links and meta-data in repositories.
@cindex SCCS @cindex SCCS
SCCS is a proprietary but widely used version control system. In SCCS was the first version-control system ever built, and was long ago
terms of capabilities, it is the weakest of the six that VC supports. superseded by later and more advanced ones; Emacs supports it only for
VC compensates for certain features missing in SCCS (snapshots, for backward compatibility and historical reasons. VC compensates for
example) by implementing them itself, but some other VC features, such certain features missing in SCCS (snapshots, for example) by
as multiple branches, are not available with SCCS. Since SCCS is implementing them itself, but some other VC features, such as multiple
non-free, not respecting its users freedom, you should not use it; branches, are not available with SCCS. Since SCCS is non-free you
use its free replacement CSSC instead. But you should use CSSC only should not use it; use its free replacement CSSC instead. But you
if for some reason you cannot use RCS, or one of the higher-level should use CSSC only if for some reason you cannot use a more
systems such as CVS or GNU Arch. recent and better-designed version-control system.
In the following, we discuss mainly RCS, SCCS and CVS. Nearly
everything said about CVS applies to GNU Arch, Subversion and Meta-CVS
as well.
@node VC Concepts @node VC Concepts
@subsubsection Concepts of Version Control @subsubsection Concepts of Version Control
@cindex master file @cindex repository
@cindex registered file @cindex registered file
When a file is under version control, we also say that it is When a file is under version control, we also say that it is
@dfn{registered} in the version control system. Each registered file @dfn{registered} in the version control system. The system has a
has a corresponding @dfn{master file} which represents the file's @dfn{repository} which stores both the file's present state plus its
present state plus its change history---enough to reconstruct the change history---enough to reconstruct the current version or any
current version or any earlier version. Usually the master file also earlier version. The repository will also contain a @dfn{log entry} for
records a @dfn{log entry} for each version, describing in words what was each change to the file, describing in words what was modified in that
changed in that version. revision.
@cindex work file @cindex work file
@cindex checking out files @cindex checking out files
The file that is maintained under version control is sometimes called A file checked out of a version-control repository is sometimes called
the @dfn{work file} corresponding to its master file. You edit the work the @dfn{work file}. You edit the work file and make changes in it, as
file and make changes in it, as you would with an ordinary file. (With you would with an ordinary file. After you are done with a set of
SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) changes, you @dfn{check the file in}, which records the changes in the
After you are done with a set of changes, you @dfn{check the file in}, repository, along with a log entry for them.
which records the changes in the master file, along with a log entry for
them.
To go beyond these basic concepts, you will need to understand three To go beyond these basic concepts, you will need to understand three
ways in which version-control systems can differ from each other. They ways in which version-control systems can differ from each other. They
...@@ -1427,7 +1419,7 @@ both locking and merging version control and tries to hide the differences ...@@ -1427,7 +1419,7 @@ both locking and merging version control and tries to hide the differences
between them as much as possible. between them as much as possible.
@cindex files versus changesets. @cindex files versus changesets.
On SCCS, RCS, CVS, and other early version-control systems, checkins On SCCS. RCS, CVS, and other early version-control systems, checkins
and other operations are @dfn{file-based}; each file has its own and other operations are @dfn{file-based}; each file has its own
@dfn{master file} with its own comment- and revision history separate @dfn{master file} with its own comment- and revision history separate
from that of all other files in the system. Later systems, beginning from that of all other files in the system. Later systems, beginning
...@@ -1439,14 +1431,18 @@ one file, but is attached to the changeset itself. ...@@ -1439,14 +1431,18 @@ one file, but is attached to the changeset itself.
Changeset-based version control is in general both more flexible and Changeset-based version control is in general both more flexible and
more powerful than file-based version control; usually, when a change to more powerful than file-based version control; usually, when a change to
multiple files has to be backed out, it's good to be able to easily multiple files has to be backed out, it's good to be able to easily
identify and remove all of it. 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 at time of
writing in 2007.
@cindex centralized vs. decentralized @cindex centralized vs. decentralized
Early version-control systems were designed around a @dfn{centralized} Early version-control systems were designed around a @dfn{centralized}
model in which each project has only one repository used by all model in which each project has only one repository used by all
developers. SCCS, RCS, CVS, and Subversion share this kind of model. developers. SCCS, RCS, CVS, and Subversion share this kind of model.
It has two important problems. One is that a single repository is a It has two important problems. One is that a single repository is a
single point of failure---if the repository server is down all work single point of failure--if the repository server is down all work
stops. The other is that you need to be connected live to the server to stops. The other is that you need to be connected live to the server to
do checkins and checkouts; if you're offline, you can't work. do checkins and checkouts; if you're offline, you can't work.
...@@ -1478,7 +1474,7 @@ version-control system is invisible to VC mode. ...@@ -1478,7 +1474,7 @@ version-control system is invisible to VC mode.
@cindex version control log @cindex version control log
Projects that use a revision control system can have @emph{two} Projects that use a revision control system can have @emph{two}
types of log for changes. One is the per-file log maintained by the types of log for changes. One is the log maintained by the
revision control system: each time you check in a change, you must revision control system: each time you check in a change, you must
fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This
kind of log is called the @dfn{version control log}, also the kind of log is called the @dfn{version control log}, also the
...@@ -1491,10 +1487,22 @@ A small program would use one @file{ChangeLog} file; a large program ...@@ -1491,10 +1487,22 @@ A small program would use one @file{ChangeLog} file; a large program
may well merit a @file{ChangeLog} file in each major directory. may well merit a @file{ChangeLog} file in each major directory.
@xref{Change Log}. @xref{Change Log}.
A project maintained with version control can use just the per-file Actually, the fact that both kinds of log exist is partly a legacy from
log, or it can use both kinds of logs. It can handle some files one file-based version control. Changelogs are a GNU convention, later
way and some files the other way. Each project has its policy, which more widely adopted, that help developers to get a changeset-based
you should follow. 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 mostly redundant. The only advantage ChangeLogs retain is that
it may be 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 files one way and some files the other way. Each project
has its policy, which you should follow.
When the policy is to use both, you typically want to write an entry When the policy is to use both, you typically want to write an entry
for each change just once, then put it into both logs. You can write for each change just once, then put it into both logs. You can write
...@@ -1509,7 +1517,6 @@ to copy it to @file{ChangeLog} ...@@ -1509,7 +1517,6 @@ to copy it to @file{ChangeLog}
(@pxref{Change Logs and VC}). (@pxref{Change Logs and VC}).
@end ifnottex @end ifnottex
@node VC Mode Line @node VC Mode Line
@subsection Version Control and the Mode Line @subsection Version Control and the Mode Line
......
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