Using a Concurrent Versions System

This page will cover using a Concurrent Versions System (CVS) on a Linux server.  CVS comes standard with practically every modern Linux/Unix distribution.  The Linux distribution being used in this example is SuSE 7.2, but any distribution with CVS will work. 

This HowTo is meant to be used after setting up a CVS server, but can be used to access any CVS server where the user has an account.  The examples provided here will show how to log in to a CVS server, create a new project, download the project, and make updates to the project.

1. Logging into a CVS server only has to be done once (a file called .cvspass is created in the home directory to verify user authentication), but the repository has to be specified every time.  The following shows how to specify the CVSROOT repository and log in to set the user's password (this will be the default repository unless one is specified with -d ): 

    CVSROOT=:pserver:USERNAME@HOSTNAME:/path/to/repository
    export CVSROOT
   

   These two lines allow a user to use the same repository every time without specifying it.  These two lines can be set in .bashrc if the user is using a bash shell (try echo $SHELL to determine the shell type).

2. To log in to a CVS server for the first time, you will need to run the CVS login command.  The following command is an example of a log in to a local server: 

    # cvs -d :pserver:USERNAME@HOSTNAME:/path/to/repository login
    (Logging in to USERNAME@HOSTNAME)
    CVS password:
    # (returns nothing for successful log in)
   

3. Logging into a remote server can be done with an external connection method such as rsh or ssh.  I would recommend using ssh as it is more secure, but will have to be installed and configured if not already installed on the system.  In the following commands, the first line sets the ext method to ssh (these commands can also be added to .bashrc), while the second command can be used to run CVS commands (in place of CVS_COMMAND) on a remote server (ext access doesn't require an authenticated log in as pserver does, just a system log in -i.e. a valid user account): 

    # CVS_RSH=ssh; export CVS_RSH
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository CVS_COMMAND
    USERNAME@HOSTNAME's password:
   

   When using ssh as the ext (external) access method, the user will have to log in via ssh every time a CVS command is run on a remote system.

1. The following command will import a project into a local repository.  The -d option isn't used since the repository to use has already been specified and exported as CVSROOT in the user's .bashrc file in their home directory. 

    # cvs import -m "Initial message" PROJECTNAME USERNAME start
   

   Note that the -m (message) option is mandatory for importing a project into the repository and is associated with the action in the log file.

2. If a project is to be imported onto a remote CVS server, use the second line from number three in logging into a CVS server above.  Just the -d option from the command will go in the cvs command between cvs and import as in the following: 

    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository import \
     -m "message" PROJECTNAME USERNAME start
    USERNAME@HOSTNAME's password:
    --importing files will commence upon successful login--
   

1. To check out a working copy of the project, the CVS checkout command will be used.  This command does just what it implies -downloads (checks out) a working copy of the project, which can be edited with necessary changes.  You should be in the directory where you want the files to be stored before running the checkout command.  The next section will cover uploading the changes you make, but the command to download a working copy is: 

    # cvs checkout PROJECTNAME
   

   This is assuming that the -d (CVSROOT) option is set in the user's .bashrc file and that the project to be checked out is named PROJECTNAME.  Therefore, if you want to download a project, you will have to specify the repository with the -d option.

1. Before changes are uploaded to the repository, any changes in the repositories project should be synchronized with your checked-out copy to ensure that everything is updated.  The CVS update command does this synchronization; it not only gets updates from the repository and merges them into your copy, but it can also notify you of which local files have changed. 

     # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository update
     USERNAME@HOSTNAME's password:
     cvs server: Updating .
     U README22.txt
     cvs server: Updating docs
     cvs server: Updating docs/scripts
     cvs server: Updating source
     cvs server: Updating source/images
     #
   

   This output shows that no changes have occurred.

2. In the next step a file named README.txt is modified and the update command is run again; the M in the margin signifies that the file has been modified locally.  After updating, the file is the changes are then committed to the repository along with a message of the changes. 

    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository update
    USERNAME@HOSTNAME's password:
    cvs server: Updating .
    M README.txt
    cvs server: Updating docs
    cvs server: Updating docs/scripts
    cvs server: Updating source
    cvs server: Updating source/images
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository commit \
     -m "Fixed line spacing" README.txt
    USERNAME@HOSTNAME's password:
    Checking in README.txt;
    /usr/local/cvs/soar/README.txt,v  <--  README.txt
    new revision: 1.2; previous revision: 1.1
    done
    #
   

   Now the README.txt file has been changed locally and its changes have been merged into the master copy in the repository.  Other developers can get these modifications to the README.txt file by running the update command.

1. In this section, a new file and directory will be added to the project and the repository.  A file called testfile and a directory called test/ will be added.  The commands to add the test/ directory locally and to the project are as follows: 

    # mkdir test
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository add test
    USERNAME@HOSTNAME's password:
    Directory /usr/local/cvs/soar/test added to the repository
   

   The commands to add testfile locally and to the project are as follows: 

    # touch testfile
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository add  testfile
    cvs server: scheduling file `testfile' for addition
    cvs server: use 'cvs commit' to add this file permanently
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository commit \
     -m "added testfile" testfile
    USERNAME@HOSTNAME's password:
    RCS file: /usr/local/cvs/soar/testfile,v
    done
    Checking in testfile;
    /usr/local/cvs/soar/testfile,v  <--  testfile
    initial revision: 1.1
    done
   

   The first block of commands creates a directory, named test, locally and adds it to the project in the repository.  The next block of commands creates a blank file called testfile, adds it to the repository, and then commits the change.

1. To remove a file from the repository, the file must first be removed from the local file system and then removed from the repository with the CVS remove command.  Once the file has been removed from the local file system and from the repository, the changes have to be committed.  The following commands show how to remove a file named testfile from a project. 

    # rm testfile
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository remove testfile
    USERNAME@HOSTNAME's password:
    cvs server: scheduling `testfile' for removal
    cvs server: use 'cvs commit' to remove this file permanently
    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository commit \
     -m "removed testfile" testfile
    USERNAME@HOSTNAME's password:
    Removing testfile;
    /usr/local/cvs/soar/testfile,v  <--  testfile
    new revision: delete; previous revision: 1.1
    done
   

   Through three commands, file testfile is removed locally and in the CVS repository.

2. Directories are removed slightly differently as CVS doesn't use version control for them.  The steps to remove a directory are to remove all the files in it locally and then to remove all the corresponding files in the directory in the repository by using the CVS commands remove and commit.  Then the CVS update command is run with the -P (pruning) option to remove empty directories in the local working copy.  The empty directory will stay in the CVS repository, but will not be added in future plain updates as CVS doesn't automatically send new directories in updates.  In the following example, the update with -P option is run and the test/ directory is removed from the local file system: 

    # cvs -d :ext:USERNAME@HOSTNAME:/path/to/repository update -P
    USERNAME@HOSTNAME's password:
    cvs server: Updating .
    cvs server: Updating docs
    cvs server: Updating docs/scripts
    cvs server: Updating source
    cvs server: Updating source/images
    cvs server: Updating test
   

1. Fogel, Karl and Moshe Bar.  2001.  Open Source Development with CVS.  2^nd ed.   Scottsdale, AZ: The Coriolis Group, LLC.