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