Getting Started With CVS

by Rob Ristroph
30 January 2004
This document is just a quick summary of things this document: already covers. It might just as fast to read that whole manual, and mark a few different pages with sticky notes. This guide is meant to be shorter so that people aren't so hesitant about setting up CVS.

I originally wrote this as a sort of cheat sheet to help a group of developers start using CVS. It cannot replace reading other material, particularly Version Management with CVS by Per Cederqvist.

How to Create a Repository

Go to the directory that you want to be the repository; this will often be on a remote machine, this is not the local disk where you will do editing. In there, type "cvs init". This will create a CVSROOT directory with the appropriate files in it.


Make the repository group-writable and group-exec, and have all the people that access it be a member of that group. If someone cannot create a lock file in a directory because someone else owns the directory, then they can't check out files; you may need to set umask for a user, or a sticky bit on the directory, in some cases.

Accessing a Repository Remotely

Set the environment variable CVS_RSH equal to the string "ssh" (no quotes).

Refer to the CVSROOT< in this style:

I usually do not set the $CVSROOT environment variable; I use several different cvs repositories, so I would be changing it, and it isn't needed anyway, because once you are in a checked out working copy of the code, you no longer have to specify the repository with -d.

Importing Files Into the Repository

In your local working directory (not in the repository), collect the files and directory structure you want to add to the repository. (It might be empty if it is the start of a new project).

cd into that directory, then run this command:

cvs import -m "Imported sources" repository-dir/module-dir some-name

The source files will be kept in

. You don't necessarily need a module name, but it's easier to have one even if you have only one module.

If you want to use module names, finish defining the module with these steps:

cvs checkout CVSROOT/modules
       edit the modules file to have a line such as:
       modulename  repository-dir/module-dir
   cvs commit -m "Added the modulename module." modules
   cd ..
   cvs release -d CVSROOT

If you are working from a directory tree with RCS/ directories at every level, consider making a temporary copy without them, so you don't put the RCS directories in the CVS repository.

If files were previously in an RCS repository, and you need to maintain the change history, then after the step above, find the ",v" files in your RCS directory, and directly copy them over to your CVS repository; put them in the same directory as the source file itself (not a sub-dir named RCS), there will probably a ",v" file already there for you to overwrite.

Usually people do not keep non-ascii files in the repository. If you want to, add those separately with the flag "-kb" when you do the "cvs add" command.

Checking Out a Working Copy

On the same machine as the repository:

cvs -d /path/to/cvs-root-of-repository/ co module-name

(if you did not use a module name, use "." )

Checking out a working copy on a remote machine

cvs -d co module-name
"co" is an abbreviation for "checkout", you can spell it out in full.

After initial checkout, you can run CVS commands from inside your working directory without specifying the -d option for the location of the repository.

One person can check out as many working copies (into different places) as they want. Multiple people can check out working copies for each to work on independently. There is a command to "release" a working copy back to the repository, but it's not necessary and no one ever uses it.

Viewing Differences

The command

cvs diff


cvs diff filename

will produce a diff (suitable for making patches) between what you have in your working copy and what is in the repository.

To view a diff of the current working directory against the repository from 3 days ago:

cvs diff -D "3 days"

Most English descriptions of time are accepted and the format of the date as used by the "date" command also works.

Getting other people's changes

From the top level directory of your working copy, which you already checked out and have been making edits to:

cvs up

Updated files will be marked with a "U"
New files (on your side) will be marked with an "A". If you made new files and they aren't marked with an "A", then you need to do the "cvs add" command.
Files you deleted, and that will be deleted from the repository too (the "cvs remove" command was used), will be marked with an "R"
Files you changes will be marked with an "M"
Files that both changed, and were merged, will also be marked with an "M"
Files that both changed, and had a conflict at merge, will be marked with a "C" -- you need to edit these files, and look for the area marked "<<<<<<" before committing
Files cvs doesn't know anything about will be marked with an "?"

Putting Your Changes in the Repository

To commit a specific single file:

cvs commit filename


cvs commit -m "short note about changes" filename

To commit your whole working directory, just do

cvs commit

in the top level of the directory tree.

Marking a certain version in the repository

Each time you ship a particular version of your code it's a good idea to mark it with a text tag so you can easily get it back later if someone reports problems and you need to investigate:

cvs rtag release-4-Jan-2003 .

The "release-4-Jan-2003" can be anything.

General Notes and Other References This manual is short and has examples of everything you might need to do; it is the first place to consult if you have questions. This one is also good, and available in paper. WinCVS is a graphical client that allows you do to all of this from a GUI; it has versions for Windows, Linux, and Mac. Often, when a team is switching to CVS the windows based members (which might be all the non-coders) feel nervous about possibly not being able to track and follow changes in the code. A GUI CVS client for windows can be very reassuring.

Chora is a web front end to CVS that is part of Horde, a package a number of web based applications. There is a demo of it linked to from the Chora page, so you can see what it looks like. If a team of people are switching to CVS, setting this up can be important because it gives even the people who don't know how to use CVS the ability to track what is going on.

There are ways to make CVS automatically send emails or do other things every time there is commit, or on other events; most of the time that's not necessary, and people monitor what is happening by doing a

cvs update

on a regular basis.

You may find that you want to make branches of your code development; in this case you should read the Per Cederqvist manual on that, but the basics is that you just add -b to a tag command, and the working copy is thereafter "stickily" attached to that branch:

cvs tag -b compiles-on-RH7-only .

Robert G. Ristroph
Last modified: Fri Jan 30 21:48:30 CST 2004