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.


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.


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

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 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.


Let's say you have a directory tree somewhere with a lot of source code in it. You want to CVS-ify it. You type
	cvs import -m "A Message I Feel Like Attaching" Dir/Path Vtag Rtag
where I therefore would have typed
	cvs import -m "KTL kroot tree" Ktng CARA start 
which would have imported the entire tree into
The import operation is chatty. You will see a confirming message for each successful import of a file or directory.



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.


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.


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: 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.


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.


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) . . .

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

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