A Real Beginner's Guide to CVS

De Clarke

UCO / Lick Observatory

Jan 10th 1997 : this is a FIRST DRAFT : please comment, complain, etc. to the address below.

This document is affectionately known as "CVS for dummies".

No offence meant! CVS is a bit intimidating when you first walk up to it. The CVS manual is very useful -- after you already understand CVS. So, to spare other neophytes the various startup woes I experienced, here's the minimal set of CVS incantations you need to know, to get started. (Note that word minimal: there is much, much more to CVS than what you will read here.)

This doc was promised at the SCC in November 96; the final version will go online (HTML) after a few test readers have commented on it.

BUILD and INSTALL CVS

First, I assume you installed CVS 1.7-or-later successfully. The source kit includes lots of instructions. Do remember that RCS is a pre-requisite and that the commands ci and co have to be on your PATH for CVS to work.

CREATE a REPOSITORY

First off, you need to create a repository directory on some stable, trustworthy host. This directory is probably called something like

/opt/CVS /usr/local/CVS

/mnt/CVS

You get the idea. Create this directory.

You need to set the envar CVSROOT to the name of that directory. For now, let's not worry about multiple repositories; we'll just note that by changing the envar you can make CVS look in one or another of several repositories, should you happen to have several.

There's a script cvsinit that came with CVS. You should use this script to help initialize your new repository. As the CVS INSTALL guide says, "There are many ways to customize CVS for your site. Read the cvs(5) manual page when you get the chance." I couldn't put it better myself.

Now we'll assume that you survived all of the above, and that you have a properly configured repository.

CVS LOOK and FEEL

CVS commands are of the form

 
	cvs Verb ?Object?

where Verb is a CVS command, and Object (optional) is a target or targets for the command. Thus you will see

        cvs import args
        cvs get args
        cvs commit args
        cvs update args
        cvs delete args
        cvs add args
        cvs log args

explained below. With this very limited set of commands you can be productive with CVS, without knowing about the rest of its very rich and interesting feature set.

IMPORT EXISTING SOURCE

Let's say you have a directory tree somewhere with a lot of source code in it. You want to CVS-ify it.

NOTE If this code is under RCS or SCCS, I suggest you make a fresh directory tree, check out everything, and copy the checked-out versions of everything into the new tree. For example, suppose I have an SCCS-managed tree /kroot :-) -- I check everything out; I copy everything from /kroot to /my/tmp/kroot, losing the SCCS directories along the way.

You type

 
	cvs import -m "A Message I Feel Like Attaching" Dir/Path Vtag Rtag

where

Dir/Path is a relative path under CVSROOT
Vtag is a "vendor tag" (CVS jargon) which we generally use for the authorship and ownership of the code
Rtag is a Release Tag -- which I generally set to "start".

I therefore would have typed

 
	cvs import -m "KTL kroot tree" Ktng CARA start

which would have imported the entire tree into

 
  	$CVSROOT/Ktng

The import operation is chatty. You will see a confirming message for each successful import of a file or directory.

NOTE : Attaching previous RCS/SCCS logs to the imported files is not a "beginner's" issue. I believe WFL (Lupton) has done this, so write to wlupton@keck.hawaii.edu if you really need to do this. We were content to let SCCS history end with the last checkout, and start the world afresh under CVS.

USING CVS for DEVELOPMENT

CHECKOUT

Now that you have the repository set up, populated with code, N programmers can all get copies of that code from the repository. What we have found clean and useful is for each programmer to make a private directory called cvs or CVS, or named after the repository if you have multiple repositories.

Let's say I have a directory cvs. If I

 
        cd cvs

and then

 
        cvs get Ktng

I will get a copy of the entire Ktng tree which I imported (in the example above). It will be written in ./Dir/Path wher Dir/Path is the relative pathname I provided in the original cvs import command.

Note: checkout is a synonym for get.

CHECKIN

If I modify a source file and want to check it back in with my modifications, I use

 
        cvs commit ?filename?

If I omit all arguments, CVS will commit all changes it detects in the current directory. If I give a filename argument, CVS will commit changes made to that one file. CVS will present me with a log file using a text editor (we use vi as the lowest common denominator). I add a line of commentary to the text file; when I exit the editor, CVS completes the commit operation.

UPDATE

Suppose I would like to know the state of my code before I commit anything. If I type

 
        cvs update

I will get a list of the states of various files in the current directory. Each line of output starts with a 1-character status code:

M modified, will be committed
U file has been updated since you last checked it out
A added, will be added on commit
D deleted, will be deleted on commit
? egregious file not part of CVS record for this dir

On a commit, any files marked Added will be added to the repository; files marked Deleted will be deleted; files marked Modified will be analyzed (diffed) and the version now in the current directory will be checked in (if possible) as the latest version.

If CVS detects that someone has committed changes to a file since you last checked it out, the update command will replace your copy with the latest copy OR (if you have made changes to your copy) attempt to merge your changes with theirs. It is chatty about this and will inform you if it was unable to merge the diffs properly.

If CVS tried to merge and had problems, it will leave both versions of the troublesome section of code in the output file, delimited by rows of < and > signs. It will note the version numbers of the competing versions of each troublesome section. You can usually straighten out the trouble and finish the merge yourself in a matter of seconds.

CVS should never delete or replace a file in your working directory without telling you all about it.

ADD/DELETE files

If you add a new file to your working directory and you want it to become part of the repository (in the corresponding directory, that is), use

 
        cvs add FileName

Conversely, if you decide that a file is no longer needed in the repository, use

 
        cvs delete FileName

In either case, the change will not take place until you issue a cvs commit.

LOGS

Just as in RCS on which it is based, CVS will show you log files for the contents of your working directory.

 
        cvs log FileName

shows you the changelog for that file.

 
        cvs log

will show you all log files for all files in the current directory.

Armed with this minimal knowledge of CVS, you can manage your code development process quite effectively. CVS is relatively friendly and easy to use.

Nevertheless, you can benefit mightily from reading the manual. CVS has more features than you can shake a stick at (and just to whet your appetite, I will describe a couple that we have found very useful) . . .

You can "tag" all the files in a directory with a release tag, like "Rel4_2". Later, you can check out "Rel4_2" and get all the files at the revisions they had when you tagged them. This is tremendously useful for projects where a stable version of the software is released, but development continues between releases.
You can establish "branches" in the code development; for example, if you have released Rel4_2, but your end users report bugs and you do not yet have a Rel4_3 to ship, the Rel4_2 code can proceed along a bugfix-only development path of its own until the next major release appears.
You can force email notification to designated recipients when any commit is done to selected directories. This is very useful when N programmers are hacking on one set of code, and they all need to know when anyone else has been changing things; or when one programmer is responsible for one directory and wants to know if anyone else dares to touch it :-)
CVS can be used remotely, with the repository on a different host from your working host. Furthermore, parts of the same CVS working directory tree can be derived from different repositories. The directory remembers which repository it came from, and performs updates and commits appropriately.
All the mechanisms of CVS are visible. Its configuration files are human-readable. It can, in other words, be hacked; if you need to do something extraordinary, to subvert for a moment the normal mechanisms of the product, usually you can do so.

I hope all of this has made you want to read the manual.

de@ucolick.org
webmaster@ucolick.org
De Clarke
UCO/Lick Observatory
University of California
Santa Cruz, CA 95064
Tel: +1 408 459 2630
Fax: +1 408 454 9863