Go to the previous, next section.

The Repository

Figure 3 below shows a typical setup of a repository. Only directories are shown below. 

/usr
 |
 +--local
 |   |
 |   +--cvsroot
 |   |    | 
 |   |    +--CVSROOT
          |      (administrative files) 
          | 
          +--gnu
          |   | 
          |   +--diff
          |   |   (source code to GNU diff) 
          |   | 
          |   +--rcs
          |   |   (source code to RCS)
          |   | 
          |   +--cvs
          |       (source code to CVS) 
          | 
          +--yoyodyne
              | 
              +--tc
              |    |
              |    +--man
              |    |
              |    +--testing
              | 
              +--(other Yoyodyne software)

There are a couple of different ways to tell CVS where to find the repository. You can name the repository on the command line explicitly, with the -d (for "directory") option: 

cvs -d /usr/local/cvsroot checkout yoyodyne/tc

Or you can set the $CVSROOT environment variable to an absolute path to the root of the repository, `/usr/local/cvsroot' in this example. To set $CVSROOT, all csh and tcsh users should have this line in their `.cshrc' or `.tcshrc' files: 

setenv CVSROOT /usr/local/cvsroot

sh and bash users should instead have these lines in their `.profile' or `.bashrc': 

CVSROOT=/usr/local/cvsroot
export CVSROOT

A repository specified with -d will override the $CVSROOT environment variable. Once you've checked a working copy out from the repository, it will remember where its repository is (the information is recorded in the `CVS/Root' file in the working copy).

The -d option and the `CVS/Root' file both override the $CVSROOT environment variable; however, CVS will complain if the `-d' argument and the `CVS/Root' file disagree.

There is nothing magical about the name `/usr/local/cvsroot'. You can choose to place the repository anywhere you like. See section Remote repositories to learn how the repository can be on a different machine than your working copy of the sources.

The repository is split in two parts. `$CVSROOT/CVSROOT' contains administrative files for CVS. The other directories contain the actual user-defined modules.

User modules

  $CVSROOT
    |
    +--yoyodyne
    |   |
    |   +--tc
    |   |   |
            +--Makefile,v
            +--backend.c,v
            +--driver.c,v
            +--frontend.c,v
            +--parser.c,v
            +--man
            |    |
            |    +--tc.1,v
            |     
            +--testing
                 |
                 +--testpgm.t,v
                 +--test2.t,v

The figure above shows the contents of the `tc' module inside the repository. As you can see all file names end in `,v'. The files are history files. They contain, among other things, enough information to recreate any revision of the file, a log of all commit messages and the user-name of the person who committed the revision. CVS uses the facilities of RCS, a simpler version control system, to maintain these files. For a full description of the file format, see the man page rcsfile(5).

File permissions

All `,v' files are created read-only, and you should not change the permission of those files. The directories inside the repository should be writable by the persons that have permission to modify the files in each directory. This normally means that you must create a UNIX group (see group(5)) consisting of the persons that are to edit the files in a project, and set up the repository so that it is that group that owns the directory.

This means that you can only control access to files on a per-directory basis.

CVS tries to set up reasonable file permissions for new directories that are added inside the tree, but you must fix the permissions manually when a new directory should have different permissions than its parent directory.

Since CVS was not written to be run setuid, it is unsafe to try to run it setuid. You cannot use the setuid features of RCS together with CVS.

The administrative files

The directory `$CVSROOT/CVSROOT' contains some administrative files. See section Reference manual for the Administrative files, for a complete description. You can use CVS without any of these files, but some commands work better when at least the `modules' file is properly set up.

The most important of these files is the `modules' file. It defines all modules in the repository. This is a sample `modules' file. 

CVSROOT         -i mkmodules CVSROOT
modules         -i mkmodules CVSROOT modules
cvs             gnu/cvs
rcs             gnu/rcs
diff            gnu/diff
tc              yoyodyne/tc

The `modules' file is line oriented. In its simplest form each line contains the name of the module, whitespace, and the directory where the module resides. The directory is a path relative to $CVSROOT. The last for lines in the example above are examples of such lines.

Each module definition can contain options. The `-i mkmodules' is an example of an option. It arranges for CVS to run the mkmodules program whenever any file in the module CVSROOT is committed. That program is responsible for checking out read-only copies from the RCS history files of all the administrative files. These read-only copies are used internally by CVS. You should never edit them directly.

The line that defines the module called `modules' uses features that are not explained here. See section The modules file, for a full explanation of all the available features.

Editing administrative files

You edit the administrative files in the same way that you would edit any other module. Use `cvs checkout CVSROOT' to get a working copy, edit it, and commit your changes in the normal way.

It is possible to commit an erroneous administrative file. You can often fix the error and check in a new revision, but sometimes a particularly bad error in the administrative file makes it impossible to commit new revisions.

Multiple repositories

In some situations it is a good idea to have more than one repository, for instance if you have two development groups that work on separate projects without sharing any code. All you have to do to have several repositories is to set $CVSROOT to the repository you want to use at the moment.

There are disadvantages to having more than one repository. In CVS 1.3 you must make sure that $CVSROOT always points to the correct repository. If the same filename is used in two repositories, and you mix up the setting of $CVSROOT, you might lose data. CVS 1.4 solves this problem by saving the repository information in the local `CVS' administration files. If you try to use the wrong repository, CVS will warn you of the attempt and then exit.

Notwithstanding, it can be confusing to have two or more repositories.

All examples in this manual assume that you have a single repository.

Creating a repository

See the instructions in the `INSTALL' file in the CVS distribution.

Remote repositories

The repository and your working copy of the sources can be on different machines. To access a remote repository, use the following format for its name: 

        user@hostname:/path/to/repository

(The `user@' can be omitted if it's the same on both the local and remote hosts.)

CVS uses the `rsh' protocol to perform these operations, so the remote user host needs to have a `.rhosts' file which grants access to the local user.

For example, suppose you are the user `mozart' on the local machine `anklet.grunge.com'. You want to access the module `foo' in the repository `/usr/local/sources/', on machine `chainsaw.brickyard.com'.

If your username is also `bach' on `chainsaw.brickyard.com', then you need only type 

cvs -d bach@chainsaw.brickyard.com:/user/local/sources checkout foo

Remember, for this to work, `bach''s `.rhosts' file must contain the line: 

anklet.grunge.com  mozart

Once the working copy is checked out, it is not necessary to specify the repository explicitly for every subsequent operation -- the working copy records it in the `CVS/Root' file.

Go to the previous, next section.