Using CVS

Here are some pointers of what a CVS session on the baselabs CVS server might look like. I have added this page to my web site, as I'm using CVS from time to time, and I always have forgotten how to use it. I hope this page will help me get back on the road when I need CVS the next time, but have forgotten how to do it. Thank god for one-click-copy/paste.

Logging in

To start a CVS session, you need to log on to your CVS server.

Export the CVSROOT environment variable, e.g. export CVSROOT=:pserver:login@baselabs.org:/home/cvs. In this, pserver denotes we're about to use a CVS server with a password login. /home/cvs denotes the root directory of the CVS server.
Execute a cvs login in order to start your CVS session

Changing the editor

By default, cvs uses vi as its standard text editor when editing changelog entries. I usually don't want to use vi but my favourite editor joe as I'm more familiar with it than with vi. You can set your favourite editor (joe in this case) with export EDITOR=joe.

Starting a new CVS project

This section discusses how to import a new project into the CVS server.

Go into the source directory you'd like to "import" into the CVS
Make sure that the directory contains the source of your project only. You don't want object files or postscript files and the such being in your repository, as they will change upon every change you make to the sources. As a bonus, they're binary so pretty useless for storing and versioning anyways. Get rid of these, and provide scripts that can build the goals from these sources.
Execute cvs -z3 import repository project releasetag. The repository will be the directory in which your project will be imported in the CVS home directory, project is the name of the project (do not use version numbers in the name), and the releasetag is usually "initial". Note: The import command of CVS is usually made for import other projects into one of your projects, but it can also be used to add new projects to your CVS repository.
Your editor will pop up and you'll have to give some explanation on what you are doing. Say something like "- Initial check in". Exit from the editor such that your new project becomes imported by the repository.
You may want to go to a different directory now, check out the source from the CVS (next section), and make sure that everything needed to work has correctly been added to the CVS repository, and can easily be checked out.

Checking out source code from the CVS server

In order to obtain a project from the CVS repository, do the following

Execute cvs -z3 co project where project is the name of the project.

Committing changes

Everytime you want to commit changes to the CVS repository, make sure that your code compiles, before checking it into the repository! Also try to keep your changes as small as possible. This gives you a couple of pluses. You can manage to document your changes. Chances to have merge conflicts with other people commiting the same lines of code become smaller. Then do the following:

cvs -z3 update: This checks with the repository whether anybody else has been committing changes since the last time you have checked out the project, so they can be merged into your local source tree. Always run this before committing changes! The cvs will also show you what files differ from the files in the CVS repository. It'll also show the files that you have (e.g. compiled object files) that are not in the CVS repository. Make sure to add new files where needed (see below).
cvs -z3 commit: This command will merge your changes into the CVS repository. your editor will pop up and you have to enter a useful changelog for the changes you've made. Always fill out something usefill so you, or others, will easily be able to figure out what you've been doing. I usually use lines that styart with "- " as these turn up nicely in changelogs which you can generate later on from your CVS repository.

Important: read that last paragraph again, get your commit comments clean and useful as a reference. Think again about making your commits as small as possible, but viable, such that the documentation clarifies your changes.

Adding or deleting files

Adding files

New files that need to go into the CVS repository are added with the following commands:

cvs add file where file is the file, or files (you may want to use ?, *, and []) that need to be added to the repository. The files are now scheduled to be added.
cvs -z3 commit in order to actually commit the changes to the repository.

Adding directories

New directories can be added in a similar fashion to files. However, when updating the local copy of a machine that isn't aware of the new directories yet, supply the -d parameter to the update command, as follows: cvs -z3 update -d.

Deleting files

If you want to remove files from the repository, issue the following commands:

rm file: you need to remove the file from your local source tree before deleting it from the repository.
cvs delete file where file is the file, or files (you may want to use ?, *, and []) that need to be removed from the repository. The files are now scheduled to be removed.
cvs -z3 commit in order to actually commit the changes to the repository.

A note on compression levels

In this overview, I'm always using compression level 3 with -z3. I have discussed this in a seperate page on CVS compression levels