Homepage of Ingo Klöckl
 Home
 Programmieren
 - Toolbox
 - Java
 - PostScript
 - Perl
 - Assembler
 - Links
 - Download
Ingo Klöckl
i.kloeckl@2k-software.de

Using CVS

CVS is a powerful and free tool for synchronizing access to a shared code base. Due to its tagging capabilities, it is also very suitable for single developers.

Preliminaries, setting up CVS

Before you can use CVS, you must install a CVS server (downloadable from here), of course. Then, you must create a repository in an arbitrary directory, and call it cvsroot. This is the location where CVS will store all files you check in. You can create one repository of your own in your home directory, or a shared repository in a public directory, just as you want. To let CVS know where the repository is, you set an environment variable named CVSROOT, pointing to the repository directory. The final preparation step is to populate the repository with some files the CVS server needs for administration. A simple example is the following: 

*U*X                                Windows
---------------------------         -----------------------------
$ mkdir ~/repos                     mkdir d:/repos
$ export CVSROOT = ~/repos          set CVSROOT = d:/repos
$ cvs init                          cvs init
or, more generally said, 
$ mkdir <yourDirectory>/<yourRepositoryName>
$ export CVSROOT = <yourDirectory>/<yourRepositoryName>
$ cvs init

Here, a short form of the location string CVSROOT is used, simply pointing to your repository. Below you will hear more about this string.

It is not absolutely required to set the CVSROOT environment variable; you can always execute CVS commands using the -d option to specify the repository location: 

$ cvs -d ~/repos checkout ochem      cvs -d d:/repos checkout ochem
I suppose you prefer the implicit specification using the environment variable to save key strokes. (If you checked out a local copy of a module, it remembers where its repository is; it is therefore not necessary to use the -d option for further commands, concerning this local copy.)

Location strings

Since the repository is not limited to be stored on your local computer, but can be located on any computer in your network, the CVSROOT normally contain a host specification just before the actual repository path. Furthermore, you can protect the repository with a password (normally specified during the CVS server installation) so that additional authentication information must be included in the CVS root. The general form of the location string can be denoted as follows: 

$ export CVSROOT = 
    [:<method>:][[<username>][:<password>]@][<host>:]
    <yourDirectory>/<yourRepositoryName>
Users who wants to work with a protected repository have to login before working with the CVS. To authenticate and to transfer the login information, several protocols or methods can be used, the pserver is a popular one.

Keywords

CVS can identity some special tags in your source code and replace themy by current values. These keywords are: 

$Author$  $Date$  $Header$  $Id$
$Name$  (name of the tag, if checked out with tag)
$Log$
$RCSfile$
$Revision$ $Source$

A network example

The following steps should be performed to set up a CVS server on host dione, using ingo as user and the popular pserver as protocol: 

$ cd /usr/local/ingo
$ mkdir cvsroot
$ export CVSROOT = :pserver:ingo@dione:/usr/local/ingo/cvsroot
$ cvs init
Other specifications may be the following, using local Unix and Windows pathes: 
:local:/usr/local/ingo/cvsroot
/usr/local/ingo/cvsroot
:local:c:/backup/repository
For Unix pathes, the :local: specification can be omitted; this is NOT true for Windows pathes. TODO: really?

Working with CVS

Create a new project in CVS

A CVS project or module is a collection of files belonging to one project. To create a new one in CVS, you can change into the directory where your project resides, and import the complete directory tree: 

$ cd <yourProjectDir>
$ cvs import [-m <message>] <moduleName> <vendor> <release>
The project files will appear under CVSROOT/<moduleName>. After importing the project into CVS, you may want to check if the import was successful: 
$ cd ..
$ cvs checkout <moduleName> [-d <outdir>]
$ diff -r <dir> <moduleName>
  [diff -r <dir> <outdir>]
$ rm -r <dir>
  rm -r <moduleName> | <outdir>

Working on a project

To actually work with the project, you have to create a working copy of it by checking it out. You may denote a target directory or let CVS create the working copy in a subdirectory which is named like the module you checkout: 

$ cvs checkout [-d <targetDir>] [-r <tag>] <moduleName>
$ cd <moduleName> | <targetDir>
Now you can work with the project files: 
$ cvs add [<file>|<dir> ...]
$ cvs add -kb [<binaryFile> ...]
$ cvs remove [<file>|<dir> ...]

$ cvs update [<file> ...]

$ cvs diff [<file> ...]
$ cvs status [<file>|<dir> ...]

$ cvs commit [-m <message>] [<file> ...]

$ cvs tag <tag> <module>

$ cd ..
$ cvs release -d <moduleName> | <targetDir>
Note that you generally can specify one or more individual files, directories or nothing. In the latter case, CVS tries to find out which files are to be added or removed or have just changed. To add or remove files or directories, you first create them in the local directory or remove them from there, then notify CVS about this by using the add or delete command. All changes must be committed before they are stored in the CVS! The update command is used to update your local copy of the module by synchronizing it with the actual CVS content.

Example

Say you have a project residing in the ochem subdirectory under your home, and you want to create a CVS project for it. Then you use these commands: 

$ cd /usr/local/ingo/ochem
$ cvs import -m "initial checkin" ochem IK 1.0
$ cd ..
$ cvs checkout -d newcopy ochem
$ diff -r ochem newcopy
$ rm -r ochem
$ rm -r newcopy
Note that as soon as you have imported the project in CVS, you will no longer need the local copy of the project. Therefore, you delete the ochem directory. If you want the module give another name than ochem, let's say chemie/structure, just specify it: 
$ cd /usr/local/ingo/ochem
$ cvs import -m "initial checkin" chemie/structure IK 1.0
$ cd ..
$ cvs checkout chemie/structure
$ diff -r ochem chemie/structure
$ rm -r ochem
$ rm -r chemie/structure

To continue working on the project, you will have to check it out first. While checking out a module, CVS create a subdirectory of the same name, where the files will be placed: 

$ cd /tmp
$ cvs checkout ochem
$ cd ochem
start working ...
$ cvs add
$ cvs ci -m "something has changed"
The change to /tmp/ochem is done so that CVS can find out by itself which files have changed or are to be added or removed. Alternatively, you can mark all changed files manually: 
start working, delete file1.c, add file2.c ...
$ cvs remove [file1.c]
$ cvs add [file2.c]
$ cvs ci -m "something has changed"

To continue working on the already checked-out module, you have to update your local copy first: 

$ cd /tmp/ochem
$ cvs update
start working ...
$ cvs ci -m "something has changed"
If you have committed your last change, you are done and can remove the local copy of the updated project, since all changes are now stored in the CVS. But before doing this, you may want to tag the status quo and let CVS check if really all changed are committed. The -d option removes the local copy after all checks are done: 
$ cvs tag v1.1 ochem
$ cd ..
$ cvs release -d ochem
To checkout exactly this version, you perform the following checkout: 
cvs checkout -r v1.1 ochem

back to toolbox page