Section 2.2. Building Your First Repository

2.2. Building Your First Repository

CVS relies on a file-based database called the CVS repository. The repository contains all the historic data about your project, including each change that has been committed to the repository, as well as the user making each change. Your developers work from a sandbox which contains working copies of the files in your project. Changes from your sandbox (and other developer's sandboxes) are committed to the repository, and changes in the repository but not in your sandbox are updated from the repository. Figure 2-3 shows a diagram of the relationship between a repository and sandboxes.

Figure 2-3. Repository/sandbox relationship

The repository must be hosted on a machine with sufficient disk space to store your files and all the change data for your projects. The repository should be accessible to all the users from their workstations. Chapter 6 contains more information on choosing a repository server and setting up a more complex repository.

If the repository is on a remote computer, I recommend that users access the repository via SSH. Ensure that the server is running an SSH server and the workstations have a compatible SSH client. For more information on remote repositories and SSH, see "Accessing Remote Repositories" later in this chapter. Chapter 8 contains a full discussion of remote repositories.

For any one project, ensure there is enough disk space for three times the expected final size of that project. If you intend to store binary files, multiply by at least five. After your first project, you'll have a feel for how much space to allow.

A repository can store many projects. If you are creating a repository that might handle several projects of unknown size, estimate as best you can and ensure that you can add more room later.

Not only can one repository store many projects, but one server can store many repositories. It's usual for a server to have only a single repository, though.

A CVS repository is user data, and it should be on a partition that is backed up and won't shut down the machine if it gets full. Repositories are often stored in /cvsroot, /var/lib/cvsroot, /home/cvsroot, or /usr/local/cvsroot. According to the Filesystem Hierarchy Standard (available at http://www.pathname.com/fhs/), the preferred location for a repository is /var/lib/cvsroot.

Another possibility is to put the repository in /cvsroot. This location is easiest for users to remember.

Example 2-5 illustrates the steps involved in creating a repository. First, create the repository root directory on the CVS server. In Example 2-5, I create the /var/lib/cvsroot directory, and then install the security measures necessary to allow all users in the anthill group to write to the repository directories. (Ubuntu and Debian systems create the initial repository for you when the package is installed. You may need to add users to the default repository group, however.)

You must be root to work in the /var directory on most Unix, Linux, and Mac OS X systems. You can run a command as root on Ubuntu and Mac OS X by prefixing the command with sudo, as in sudo mkdir/var/lib/cvsroot. On other Linux and Unix systems, use the command su - to get a root shell first. A root shell is indicated with the # prompt.

Example 2-5. Creating a repository

 $ su - Password: ****** # mkdir /var/lib/cvsroot # chgrp anthill /var/lib/cvsroot # ls -la /var/lib total 153 drwxr-xr-x    2 root     anthill      4096 Jun 28 16:31 cvsroot . . . # chmod g+srwx /var/lib/cvsroot # ls -la /var/lib total 153 drwxrwsr-x    2 root     anthill      4096 Jun 28 16:33 cvsroot . . . # cvs -d /var/lib/cvsroot init # ls -la /var/lib total 3 drwxrwsr-x    3 root     anthill      4096 Jun 28 16:56 cvsroot # ls -la /var/lib/cvsroot total 12 drwxrwsr-x    3 root     anthill      4096 Jun 28 16:56 . drwxr-xr-x   10 root     staff        4096 Jun 28 16:35 .. drwxrwsr-x    3 root     anthill      4096 Jun 28 16:56 CVSROOT # chown -R cvs /var/lib/cvsroot 

To allow others to use the repository, create a Unix group for CVS users (anthill in the preceding example) and chgrp the repository's root directory to that group. You'll need to add users to that group, using the appropriate command for your system (often gpasswd). Use chmod to set the directory's SGID bit, so that files created in the directory have the same group ID as the directory's group ID (this can prevent trouble later). You should also use chmod to set the directory group-writable, -readable, and -executable (you can do all your chmod work in one command with chmod g+srwx, as shown in Example 2-5).

To minimize security risks, create a user named cvs to own the repository and the administrative files. Use the --system option to adduser, so that cvs is created as a user who can never be logged into. chown the repository's root directory and administrative files to that username. Chapter 6 explains security.

In OS X, you can use the niload command to add a user:

 $ sudo niload passwd . <<EOF > username:*:701:20::0:0:New User:/Users/username:/bin/bash > EOF 

Execute the following command to set up your chosen directory as a CVS repository:

 cvs -d repository_root_directory init 

CVS commands follow the format:

  cvs [cvs-options] command [command-options] 

The CVS options modify the behavior of CVS as a whole, and the command options modify the behavior of a CVS command. This format is explained more fully in Chapter 3.

Example 2-5 illustrates the entire process of creating a directory and then creating a CVS repository within that directory. In this case, the CVS option is -d repository_path, and the command is init. There is no command option. anthill is the name of the group with access to CVS, and cvs is the name of the CVS owner.

Setting up the repository produces a place to store projects and also adds the special CVSROOT directory. The CVSROOT directory contains configuration and metadata files. Chapter 6 explains this directory in more detail. Projects are stored in subdirectories of the repository root directory, which is /var/lib/cvsroot in our example.