DCVS(7) FreeBSD Miscellaneous Information Manual DCVS(7)
NAME
DCVS -- Distributed Concurrent Versions Systems
DESCRIPTION
DCVS is an extended version of the Concurrent Versions System CVS and the
replication program CVSup suited to CVS repositories with local write
access across wide area networks.
Motivation
CVS is a version control system which is widely used in the open source
community, but as well in commercial enterprises. The deficiencies of CVS
are well known, which may be one of the reasons for choosing it though
there are lots of other options nowadays, some offering more functional-
ity and features.
One of CVS's shortcomings is the pure centralistic organizational model
it is based on. There is one central database, the repository, and very
little support for offline operations. All developers need direct TCP/IP
access for almost all version control operations, and since real software
projects tend to become large very quickly, the network bandwidth should
not be too small. Though the internet has improved very much in this
respect in recent years, fast direct access may still be a problem espe-
cially for world-wide distributed software development efforts. It would
be better if the central CVS repository could be distributed on several
computers local to the development teams, and changes would be distrib-
uted automatically in background by hard-working daemons.
The structure of a CVS repository makes it quite unsuited for real dis-
tribution techniques like those used in transaction-oriented database
systems. In spite of this, it is possible to realize a limited variant of
the ideal solution described above, if modifications to the repository
are limited to certain well-defined lines of development ( branches ) on
every server. (This is the design that has also been implemented in
ClearCase's Multi-Site product.)
Idea and Design
In a DCVS system there are n repositories whose contents are kept equal
or nearly equal by background processes. The program used for this task
is an extended version of the well-known and efficient CVSup(1) developed
by John D. Polstra. The combination of DCVS repository, extended CVSup
server, and DCVS server program (extended CVS server) will be called DCVS
server or simply server in the following paragraphs.
All contents of all development lines can be checked out from any of the
n DCVS servers into a DCVS workspace owned by a developer. All operations
that do not modify the repository, such as diff, patch, log, annotate
etc., will work just like in CVS, but they will always use the local
repository and so be much faster in a distributed scenario.
But what happens when the code in the workspace must be changed? If all
DCVS servers may check-in any changes at any time, there will be con-
flicts soon, and chaos and data loss will result. So every DCVS server
gets assigned a set of development lines (DCVS branches) for which it is
responsible. Modifications to a certain line of development may only be
checked-in to the server which is responsible for this branch. The sepa-
ration of modifications by lines of development makes it possible to
automatically transfer and distribute changes in the DCVS network. Repos-
itory synchronization is performed on the level of single RCS delta ele-
ments by the extended cvsupd processes.
You may now say: "Fine, but what do I do if I want to commit changes for
a development line my local DCVS server is not responsible for?" In this
case you simply create a new development line (branch) and commit the
changes to it. Your local DCVS server will automatically be responsible
for any newly created line of development. If these changes need to be
applied to the original branch, a developer on the reponsible DCVS server
needs to perform a merge operation. Alternatively, you can also contact
the remote server directly over the internet and commit the changes
there, overriding the DCVS repository setting. But generally it will be
easier to follow a change set -oriented style of development model. DCVS
therefore provides the functionality of change sets which enable develop-
ers to produce small sets of changes related to a feature or a defect,
which can then be applied by others.
How can we ensure that deltas on a certain line of development can be
identified as belonging to a certain DCVS server? In order to understand
this, a certain amount of knowledge about the RCS file format, which is
used by the CVS versioning mechanism, is needed. CVS uses so-called magic
branch numbers, which are revision numbers with an even number of ele-
ments and the number 0 at the last-but-one position. Let's take 1.34.0.4
as an example. Deltas belonging to this line of development will be
labeled 1.34.4.1, 1.34.4.2, 1.34.4.3, etc. To separate lines of develop-
ment on different servers, we must ensure that the branch numbers (4 in
our example) chosen to represent the branch are different for every
server. This concerns as well the creation of new branches (tags) as the
creation of new RCS deltas.
In order to achieve this, DCVS assigns a unique range of branch numbers
to every (server, collection) pair. All ranges for all servers and col-
lections must be mutually exclusive. The definitions for servers, collec-
tions, and ranges are read from a single configuration file, which must
be the same on all DCVS servers. By consulting the contents of this file,
every DCVS server can decide if it is responsible for a certain branch or
delta of a given file. If so, all modifying operations are allowed; if
not, modifying operations are only possible on the appropriate remote
server.
Another problem when working with distributed DCVS repositories are the
actual names of configurations (tags). These must be uniquely assignable
to exactly one DCVS server, too. DCVS solves this problem in a very sim-
ple fashion by extending all tags with a server-specific suffix like
_at_dcvs_mydomain_org, so that no conflicts in the tag name space may
arise.
IMPLEMENTATION
Currently the core of DCVS consists of three programs: the extended CVS
executable dcvs, the extended CVSup server dcvsupd, and a (still very
incomplete) administration program called cvsupadm.
DCVS CONFIGURATION
Central for all DCVS programs is the DCVS configuration file, which is
either named dcvs_config and searched for in the conventional /etc direc-
tories, or dcvsupd.servers and looked for in the CVSup server base direc-
tory (/usr/local/etc/dcvsup by default). Currently the default ans only
supported setup is to install everything under /usr/local/dcvs, with the
configuration file named /usr/local/dcvs/etc/dcvs_config.
An example for a DCVS configuration file can be found in the
dcvs_config(5) man page.
COMMANDS AND DAEMONS
dcvsupd has been extended to serve only deltas and tags the local
DCVS server is responsible for. (Additional ranges may be
specified, too.) Together with the dcvsup client and cron a
distribution strategy based on CVSup's pull model can be
realized.
Additionally CVSup has been enhanced to provide combined
push/pull modell. This has been done by modifying the cvsup
client program to be able to instanciate a server and making
the server fork a client program on demand. After pull-repli-
cation has finished, the established TCP connection can be
reused for push-replication.
There are also some scripts that may be useful for proper
DCVS setup (see below).
dcvs is an extended CVS program (based on CVS 1.12.12). All envi-
ronment variables, file and directory names that tardition-
ally begin with CVS have been replaced by DCVS. DCVS has
been extended to check the server's responsibility for all
operations modifying the repository. Additionally automatic
extensions for configuration names (tags) have been imple-
mented for several operations.
Both dcvs and dcvsup have been extended by proper posix file
locking to ensure mutual exclusion of their operations.
cvsupadm is a small administration program, which currently supports
creation and editing of DCVS configurations and DCVS collec-
tions. It also supports locking of repositories against dcvs
and dcvsup operations. Future versions will be able to lock
single collections and transfer the responsibility for a
(server, collection) range from one server to another.
SCRIPTS
Several scripts have been added to facilitate the automation and adminis-
tration of DCVS:
dcvsupd.sh starts the dcvsup server with correct arguments according to
the DCVS configuration file
dcvsup.sh starts a DCVS update for a given server with correct settings
extracted from the DCVS configuration file
sdcvsup.sh starts a DCVS update for a given server with correct settings
extracted from the DCVS configuration file over a secure
channel
dcvsup_push.sh
pushes changes from the local server to all other servers
over unsecured channels via ssh
sdcvsup_push.sh
pushes changes from the local server to all other servers
over secure channels via ssh
dcvs_sync.sh
performs a two-way replication between the local server and
the server specified as the first argument. ssh is not
needed.
sdcvs_sync.sh
performs a two-way replication between the local server and
the server specified as the first argument. The connection is
encrypted by ssh.
dcvs_locks.sh
list, checks, or creates DCVS lock directories and files
dcvs_getconfig
is not a script, but an m3 program that can be used to
extract information from a DCVS configuration file and very
useful for script writing.
ENVIRONMENT
DCVSROOT specifies the DCVS repository and access mode used for dcvs
checkout and init commands.
DCVS_RSH specifies the remote shell to be used (default: ssh).
DCVS_SERVER
specifies the DCVS server program to be started by dcvs.
DCVS_CONFIG
may be used to override the default location of the
dcvs_config file.
FILES
dcvs_config
the central DCVS configuration file
SEE ALSO
dcvs(1), dcvs_config(5), dcvsupd(8), dcvsup(1), cvsupadm(1)
July 31, 2005