CVS Usage

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 firstwalk up to it. The CVS manual is very useful -- after youalready understand CVS. So, to spare other neophytes thevarious startup woes I experienced, here's the minimalset of CVS incantations you need to know, to get started.(Note that word minimal: there is much, much more toCVS than what you will read here.)

This doc was promised at the SCC in November 96; the final version willgo 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 rememberthat RCS is a pre-requisite and that the commands ci andco have to be on your PATH for CVS to work.

 

---

CREATE a REPOSITORY

First off, you need to create a repository directoryon some stable, trustworthy host. This directory isprobably 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 thatdirectory. For now, let's not worry about multiplerepositories; we'll just note that by changing theenvar you can make CVS look in one or another ofseveral repositories, should you happen to have several.

There's a script cvsinit that came with CVS. You shoulduse 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, andthat 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) isa target or targets for the command. Thus you willsee

        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 commandsyou can be productive with CVS, without knowing about therest of its very rich and interesting feature set.

---

IMPORT EXISTING SOURCE

Let's say you have a directory tree somewhere with a lot ofsource 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 theauthorship 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 confirmingmessage 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 [e-mail] 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 fromthe repository. What we have found clean and useful isfor each programmer to make a private directory calledcvs or CVS, or named after the repository if youhave 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/Pathwher Dir/Path is the relative pathname I provided in theoriginal cvs import command.

Note: checkout is a synonym for get.

 

CHECKIN

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

 
        cvs commit ?filename?

If I omit all arguments, CVS will commit all changes itdetects in the current directory. If I give a filenameargument, 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 adda line of commentary to the text file; when I exit theeditor, CVS completes the commit operation.

 

UPDATE

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

 
        cvs update

I will get a list of the states of various files inthe current directory. Each line of output startswith 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 tothe repository; files marked Deleted will be deleted;files marked Modified will be analyzed (diffed) and the versionnow in the current directory will be checked in (ifpossible) as the latest version.

If CVS detects that someone has committed changes to a filesince you last checked it out, the update command will replaceyour 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 unableto merge the diffs properly.

If CVS tried to merge and had problems, it will leave both versionsof the troublesome section of code in the output file, delimited byrows of < and > signs. It will note the version numbers ofthe competing versions of each troublesome section. You can usuallystraighten out the trouble and finish the merge yourself in amatter of seconds.

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

 

ADD/DELETE files

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

 
        cvs add FileName

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

 
        cvs delete FileName

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

 

LOGS

Just as in RCS on which it is based, CVS will show you log filesfor 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 currentdirectory.

---

Armed with this minimal knowledge of CVS, you can manage yourcode development process quite effectively. CVS is relativelyfriendly 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 towhet your appetite, I will describe a couple that we have foundvery 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 atthe revisions they had when you tagged them. This is tremendously usefulfor projects where a stable version of the software is released, butdevelopment 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 donot yet have a Rel4_3 to ship, the Rel4_2 code can proceed along abugfix-only development path of its own until the next major releaseappears.
• You can force email notification to designated recipients whenany commit is done to selected directories. This is very useful whenN programmers are hacking on one set of code, and they all need toknow when anyone else has been changing things; or when one programmeris responsible for one directory and wants to know if anyone elsedares to touch it :-)
• CVS can be used remotely, with the repository on a different hostfrom your working host. Furthermore, parts of the same CVS workingdirectory tree can be derived from different repositories. Thedirectory remembers which repository it came from, and performsupdates and commits appropriately.
• All the mechanisms of CVS are visible. Its configuration files arehuman-readable. It can, in other words, be hacked; if you need todo something extraordinary, to subvert for a moment the normalmechanisms of the product, usually you can do so.

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

 

 

[e-mail]
[e-mail]
De Clarke
UCO/Lick Observatory
University of California
Santa Cruz, CA 95064
Tel: [phone]
Fax: [phone]