NetBSD CVS HOWTO

Introduction and Purpose

Getting Started

Using CVS

Other Useful CVS Operations

Other Sources of Information

Introduction and Purpose

What is CVS?

CVS stands for Concurrent Versions System. CVS is a Source Control or Revision Control tool designed to keep track of source changes made by groups of developers working on the same files, allowing them to stay in sync with each other as each individual chooses. In particular, CVS is the tool used by The NetBSD Project to manage its source tree.

It is important to note that thanks to the concurrent part of CVS, several people can work on things at the same time. There is no locking of files as with RCS.

Getting Started

This section shows the basic steps for installing CVS on your system.

Install CVS

You need to install CVS on your local machine. It is your machine that you will do all your work on, not the CVS server. If you don't already have CVS installed on your machine, then install CVS from the package collection .

Configure your environment for CVS

On your local machine that you plan to use CVS on, add the following to your .cshrc file if you use csh or tcsh as your shell. 

setenv CVSEDITOR vi
setenv CVSROOT yourusername@cvs.NetBSD.org:/cvsroot
setenv CVS_RSH ssh

Add the following to your .profile file if you use sh or bash. 

CVSEDITOR=vi
CVSROOT=yourusername@cvs.NetBSD.org:/cvsroot
CVS_RSH=ssh
export CVSEDITOR
export CVSROOT
export CVS_RSH

Make a directory for CVS work

I keep all my CVS related work in /usr/cvs on my machine, but this is just personal preference. In the rest of this document I will assume that you have created a /usr/cvs directory on your machine. Once again, this is your local machine, not the CVS server.

Using CVS

This section shows the basic steps involved with using CVS.

An Example

This section shows how to start with an empty /usr/cvs directory, add the htdocs/people/ module, make a change and then commit the change. The basic steps involved are: 

cd /usr/cvs
cvs checkout htdocs/people
cd htdocs/people
vi developers.xml
make
cvs ci developers.xml developers.html

A more detailed explanation of these steps follows. 

cvs checkout htdocs/people

This line told CVS to check out the directory htdocs/people to our local machine. This means that the most recent version of the files in htdocs/people are copied from the CVS server to our local machine. In addition, CVS directories were created in /usr/cvs, /usr/cvs/htdocs, and /usr/cvs/htdocs/people. It is important to keep in mind that unlike a checkout in RCS, a CVS checkout doesn't lock the file. Ie, other developers can still access the checked out file.

Once we have checked out a directory to our local machine, we don't need to do a cvs co, or equivalently cvs checkout, again for this directory. If we want to update a previously checked out directory to the most recent version, we would simply do, for example, cvs update htdocs/people.

The next step after checking out the directory (or updating if we had already checked out the desired module before) was to edit a file. After all our edits were complete, we did: 

  make

This regenerated the developers.html file from the developers.xml. We then did: 

cvs ci developers.xml developers.html

This command uploaded our changes to the CVS server and updated the RCS header in the files to reflect the new version. When you checkin (commit) a change, you will be prompted to enter a short description of your changes.

It should be noted that within the source tree adding new entries and regenerating files is normally done as two commits.

CVS Modules

In CVS a module can refer to a single file, a directory with several files, or even an entire directory tree. A list of NetBSD top level CVS modules details the top level CVS modules in the NetBSD tree. A couple of other top level modules of particular interest are:

htdocs
The NetBSD WWW pages.
othersrc
Related code that is not part of NetBSD itself.

For each of the top level modules, you can check out (and later update) the entire top level, or you can check out (and update) lower level modules. For example, to check out the entire htdocs module, we would do: 

cd /usr/cvs
cvs checkout htdocs

We could also only get the htdocs/people subdirectory with 

cd /usr/cvs
cvs checkout htdocs/people

In these examples, don't forget that you only need to check out a module once. For example, if you have already checked out the htdocs module but want to bring it all up to date, you would do: 

cd /usr/cvs
cvs update htdocs

Importing a new package

This section has a few supplements to the Importing a New Package instructions.

Here is an example of adding a newly created package. This example assumes that your CVS stuff is kept in /usr/cvs and pkgsrc is a subdirectory from there. The new package, foo/bar in this case, is in the directory /usr/cvs/pkgsrc/foo/bar.work. The steps to import this package into the source tree are: 


cd /usr/cvs/pkgsrc/foo/bar.work
	
# do the usual testing, pkglint, etc. 
# don't forget to do 'make makepatchsum' to generate the
# files/patch-sum file.

grep TNF /usr/pkgsrc/doc/pkgsrc.txt

# this command tells me the correct syntax for "cvs import". 
# (/usr/pkgsrc is a symlink to /usr/cvs/pkgsrc).

cvs import pkgsrc/foo/bar TNF pkgsrc-base 

# note it's "bar", not "bar.work"

cd ../../..
cvs checkout pkgsrc/foo/bar 

# this checks out the newly imported package to 
# see if everything went ok

cd pkgsrc/foo
cvs update Makefile
vi Makefile 

# add bar to the pkgsrc/foo/Makefile

cvs ci -m 'add & enable bar' Makefile

# check in the changes to pkgsrc/foo/Makefile

cd /usr/cvs/pkgsrc/doc
cvs update CHANGES-YYYY

# this makes sure you have the most up to date CHANGES-YYYY

vi CHANGES-YYYY

# make a note of your changes to the foo/bar package

cvs ci -m 'Added foo/bar version 17.42' CHANGES-YYYY

# check in CHANGES-YYYY

Other Useful CVS Operations

CVS output

When you perform various CVS tasks, you will see a list of each file which is involved. The filename will be preceeded with a single letter code. A quick summary of the letters is here:

  • Updated
  • Patched
  • Conflict
  • Modified (locally)
  • Added
  • Removed
  • ? (not under CVS control)

Other Sources of Information

NetBSD specific

CVS specific