CVS is a version control system. You can use it to keep a record of changes to your source files and to share files between multiple people working on a software project. This document is intended to provide a quick overview of how to setup CVS. See section 6 for ways to access additional CVS documentation.

1. Decide where you want the repository to reside - For this example, I will use /u/robh/cvsroot. All we need to do is just create the directory.

   	mkdir /u/robh/cvsroot
   

2. Create the repository - The first step is to create a CVS repository, which is done using the cvs "init" command.

   	cvs -d /u/robh/cvsroot init
   

   This initializes the repository and creates the appropriate administrative files needed by cvs.

3. Setup the new project - For this example, I will setup a new project named "myproject". I assume I have two files named myproject.c and Makefile in a directory /u/robh/src/current and I want to "import" them into the CVS repository into the project "myproject", which resides in a directory also named "myproject":

   	cd /u/robh/src/current
   	cvs -d /u/robh/cvsroot import -m "Imported source" myproject robco start
   

   In this example, "myproject" is the name of the directory in the CVS repository that is created which will be used to store the files which make up the "myproject" project. "robco" and "start" are the "vendor tag" and "release tag". These can be anything you want them to be and are just used for tracking purposes.

   Doing this will create a directory named /u/robh/cvsroot/myproject that will contain the CVS files for "Makefile" and "myproject.c".

4. Access Method - At this point, you have to decide which of the various access methods you will be using. There are three different methods you can use and you must select one of the following methods.
   • Local Filesystem Access - If you will be the only user accessing the repository or everyone that will need access has an account on the same machine or machines on which the repository resides, you can just use the simplest of the access methods, which is local file access. So, for example, if you create the repository in your burrow account and everyone needing access also has a burrow account, then this access method will work. To use this, you will just need to set the CVSROOT environment variable to be the path to the repository. In this example, you could do this by adding the following to your .cshrc file (if you use csh or tcsh as your shell) or .bashrc (if you use bash):

     
          For bash:
     
     	export CVSROOT=:local:/u/robh/cvsroot
     
          For csh or tcsh:
     
     	setenv CVSROOT :local:/u/robh/cvsroot
     
     

     If you are using the local access method and sharing the repository with other users, you must take care to make sure the repository is readable and/or writable by the other users. See section 7 below for more information.

   • External ssh Access - If you will be accessing the repository from afar but you want to keep the repositoty on a local account, you can use the ext access method. This will only be useful if all users accessing the repository have local accounts. If the users do not have access to the machine upon which the repository resides, you should use the pserver method, described below. To use the ext method, set your CVSROOT and CVS_RSH environment variable as follows:

     
          For bash:
     
             export CVSROOT=:ext:robh@burrow:/u/robh/cvsroot
             export CVS_RSH=ssh
     
          For csh or tcsh:
     
             setenv CVSROOT :ext:robh@burrow:/u/robh/cvsroot
             setenv CVS_RSH ssh
     

     Using this method, cvs connects to the server (in this case, burrow.cs.indiana.edu) via the secure `ssh` command and prompts the user for their password before logging in (in this case, as user robh). Simply change the username and host name to reflect account to connect to.

     If you are using the ext access method and sharing the repository with other users, you must take care to make sure the repository is readable and/or writable by the other users. See section 7 below for more information.

   • Pserver Access - If you need to access the repository from remote systems and, perhaps, with people who don't have local accounts, then you will have to use the pserver access method. In order to do this, you will have to use a CVSROOT like the following:

          For bash:
     
     	export CVSROOT=:pserver:remoteuser@bobac.cs.indiana.edu:/u/robh/cvsroot
     
          For csh or tcsh:
     
     	setenv CVSROOT :pserver:remoteuser@bobac.cs.indiana.edu:/u/robh/cvsroot
     

     The "remoteuser" is whatever user you configure when setting up your server (see below) and "bobac.cs.indiana.edu" is the name of the machine that is running the cvs server.

     If you want to use this access method, you must now follow the instructions in the next section (Setting up the server).

5. Setting up the server - If you have chosen to use the local filesystem or external ssh methods of access, you can skip this section. If you have chosen to use the pserver access method, then you will have to first create a CVS password file. This file is named "passwd" and resides in the CVSROOT subdirectory of your repository directory. In the current example, this would be

   	/u/robh/cvsroot/CVSROOT/passwd
   

   This file must contain a single line of the following form for each user account you wish to create:

   	remoteuser:xxxxx:localuser
   

   where "xxxxx" is a password encrypted using the unix crypt(3) facility. The "remoteuser" is the username the CVS user will specify when setting their CVSROOT environment variable and the "localuser" will be the local username that this user will become on the server, which will probably just be the username of the person that owns the repository files.

   The easiest way to generate the encrypted password is to use the cryptit utility. For example, if you wanted to use a password of "foo+bar",

   	burrow% cryptit foo+bar
   	Encrypted version of foo+bar = XD69ZpmCDEGvQ
   

   So, the corresponding entry in the the CVS password file for this example would be:

   	remoteuser:XD69ZpmCDEGvQ:robh
   

   You are encouraged NOT to use your normal unix account password as the CVS account password. Note that you can also create multiple accounts or let multiple users share a single account. I recommend that you create a separate account for reach remote user, each having a unique password, so you can keep better track of who has done what to the repository.

   Once you have the password file in place, you must then setup the server on the machine you have chosen. Unfortunately, I know of no way to do this without having root privileges so you will have to make your request to the systems staff by sending email to sysadm@cs.indiana.edu. In your request, include 1) the name of the machine you want to use as your server and 2) the path to your repository. In this example, this would be "bobac" and "/u/robh/cvsroot". Once we receive your request, we will make the necessary addition to the /etc/inet/inetd.conf file on that machine which will look like the following:

   
       cvspserver stream tcp nowait root /usr/local/gnu/bin/cvs cvs --allow-root=/u/robh/cvsroot pserver
   
   

   Please note that your CVSROOT/passwd file must be readable by root across NFS. The easiest way to accomplish this is to make the passwd file world readable and all the directories leading up to that file world searchable. For example, if the CVSROOT directory is /u/robh/cvsroot/CVSROOT then you could set the proper permissions by running:

   chmod o+x /u/robh /u/robh/cvsroot /u/robh/cvsroot/CVSROOT
   chmod o+r /u/robh/cvsroot/CVSROOT/passwd

   If you don't want to open this file up to the world, then you can use ACLs to more tightly control access. Since the root user becomes the user nobody when going across nfs, you can use ACLs to give this user access to the directories leading up to that file and the passwd file itself. Using the current example, you could do this using setfacl as follows:

   setfacl -m user:nobody:--x,mask:rwx /u/robh/cvsroot /u/robh/cvsroot/CVSROOT
   setfacl -m user:nobody:r--,mask:rwx passwd
   

   Please see the ACL Help Page for more information about using ACLs.

6. Using CVS - Once you have decided on your access method, created your repository, setup your CVSROOT environment variable, and (optionally) setup your CVS server, you should be ready to roll. It is beyond the scope of this document to explain how to use CVS, but here are a couple sample commands to get you started:
   • Login to the server (if using the pserver access method)

     	burrow% cvs login
     

   • Checkout sources for editing

     	burrow% cvs checkout myproject
     

   • Display status information on checked out files

     	burrow% cvs status
     

   • Check files into the repository

     	burrow% cvs commit
     

   To get more information, you can do one of the following:

   • Read the cvs info pages (the main source of CVS documentation)

     	burrow% info cvs
     

   • Get general cvs help information:

     	burrow% cvs --help
     

   • Get a list of cvs commands:

     	burrow% cvs --help-commands
     

   • Get a list of cvs command line options:

     	burrow% cvs --help-options
     

   • Get help for a specific cvs command

     	burrow% cvs -H command_name
     

     For example:

     	burrow% cvs -H commit
     

   • View the CVS manual

     	burrow% ghostview /l/src/gnu/cvs/cvs-1.10/dist/doc/cvs.ps
     

7. Notes about sharing a local repository - If you are going to use a local repository and share it with other users, you must make sure that the other users have read and/or write access to the repository directory. This can be done using normal unix groups or Access Control Lists (ACLs). For information about using ACLs, see http://www.cs.indiana.edu/csg/software/ACL.html.

Special thanks to Clayton Carter for adding information about using ssh and the ext access method and for his expert copy editing skills.

[Return to the FAQ index]