HOWTO - Use CVS

CVS is a project source management system, built on top of RCS. (RCS is a revision control system, that is limited to the file or directory level.) CVS can manage several different projects, and is designed for projects with multiple layers of directories or muliple code maintainer, and can keep a repository on one machine, and the developers can be on other machines.

Create CVS Repository
CVS as a Server
Local or Remote Access
Initialize a Software Project Repository
Check Out Sources
Compare Local Changes
History of Changes
Status of Changes
Remove a File
Add a File
Move a File
Check In Local Changes
Update Local Sources
Tagging Sources
Creating Patches
Backing Out Changes
Using Branches
Sticky Tags!
More Info

Create CVS Repository

To set up a CVS repository, you must define the environment variable CVSROOT to point to the repository directory.

A good choice may be (C-shell example)

setenv CVSROOT /usr/local/src/cvsroot

Once $CVSROOT is defined then you can do

cvs init

to initialize and set-up the CVS repository. This only needs to be done once.

CVS as a server

If you want CVS to work as a server then do the following steps. This only needs to be done if you plan to have developers access your CVS root from off the machine anonymously.

Generally, it's a good idea to set up CVS as it's own user and group:

	groupadd -g 8000 cvsgrp
	useradd -u 8000 -g cvsgrp -d /u/cvs -s /bin/sh \
		-c "CVS Repository" -m cvs

Set the ownership of the $CVSROOT and set the setgid bit on the directory to propagate group ownership to any created files and directories.
```
	chown -R cvs $CVSROOT
	chgrp -R cvsgrp $CVSROOT
	chmod -R g+s $CVSROOT
```

Made sure the cvspserver entry is in the /etc/services file

	grep cvs /etc/services

which should yield the following lines. (If not, then add them yourself.)

cvspserver      2401/tcp                        # CVS client/server operations
cvspserver      2401/udp                        # CVS client/server operations

Add an entry into /etc/inetd.conf to invoke CVS as a server

# CVS server
cvspserver      stream  tcp     nowait  root    /usr/bin/cvs cvs --allow-root=/usr/local/src/cvsroot pserver

and signal the inetd daemon to re-read the configuration file with

	killall -HUP inetd

If xinetd is used instead then create a configuration file in /etc/xinetd.d named cvspserver, (where the last line tells it the names of your repositories):

service cvspserver
{
	socket_type         = stream
	protocol            = tcp
	wait                = no
	user                = root
	passenv             = 
	server              = /usr/bin/cvs
	server_args         = --allow-root=/usr/local/src/cvsroot pserver
}

and signal the xinetd daemon to re-read the configuration file with

	killall -HUP xinetd

	cd /etc/rc.d/init.d
	./xinetd reload

Create or edit the following files in $CVSROOT/CVSROOT
readers
contains a list of pseudo usernames that can read from the CVS repository via cvspserver.
writers
contains a list of pseudo usernames can write via cvspserver ... this is not secure since passwd is passed as clear text.
passwd
create the encrypted passwd string with (htpasswd from apache)
```
        htpasswd -c passwd pseudo_username
```
edit passwd to append ":cvs" to the pseudo_username entry. This is the user it will run as, and this will allow the pseudo user to write to the history file. Note that the cvs user was defined above.

Local or Remote Access

There are several ways to access the CVS repository. The choice depends on how much access should be granted.

anonymous - read only access:
```
cvs -d :pserver:pseudo_username@cvshost.domain:/usr/src/cvsroot login
```
give it the password given above.
```
cvs -d :pserver:pseudo_username@cvshost.domain:/usr/src/cvsroot checkout project_name
```
The purpose of anonymous access is for users to get the most recent sources, but read-only. They can make changes, but can only generate a patch file, which should be sent to one of the developers.
local - read or write access - for active developers.
The user has an account on the CVS host, and they should be listed in the cvsgrp, and they can set
```
setenv CVSROOT  /usr/src/cvsroot
```
However, CVS_RSH does not need to be set. See the example .cvsrc file below.
remote - read or write access - for active developers.
The user should have an account on the CVS host, and they should be listed in the cvsgrp. It is possible to allow anonymous-like access, but it will not be described here, since the password is sent as clear text, and it's not secure at all.
Further discussions will assume that the SSH daemon is working on the CVS host, and that client-side SSH is there for the remote user. The user needs to define the following environment variables, which are necessary, and a couple of helpful C-shell aliases. The definitions are placed in the $HOME/.cvsrc file, which is serving double duty. The lines following the shell exit tells CVS what default flags to use for the given CVS command.
```
#begin .cvsrc
setenv CVSROOT  username@cvshost.domain:/usr/src/cvsroot
setenv CVS_RSH  ssh
alias   cvsstat 'cvs status \!* |& grep Status:'
alias   cvswhat 'cvs status \!* |& grep Status: |& grep -v "to-date"'

exit
# default CVS options
diff -u
cvs -z4
update -d -P
checkout -P
```
Source this file to set the environment variables or aliases with (C-shell)
```
	source $HOME/.cvsrc
```

Initialize a Software Project Repository

To start a source repository:

cd prj_name
cvs import -d prj_name vendor_name initial

where prj_name is a descriptive name for the project vendor_name can be anything, and "initial" is what I use to tag the initial set of sources. If everything worked OK, then you can remove the original sources. (Don't try to "check-out" the repository sources into the original source directory ... this usually causes endless problems.)

Check Out Sources

Check out the sources from the CVS repository with the following command:

cvs co -P prj_name

which will create a sub-directory named prj_name with the sources and each directory will have a sub-directory named CVS that contains info about the repository sources. Once you've checked-out the sources, you need not define $CVSROOT to work within the local sources. All the cvs commands will work, if they're invoked within the local source directories, and it's local host access.

Compare Local Changes

Suppose you modified any of the checked-out or local sources. To compare the changes you've made to the repository sources:

cvs diff [source_file]

where you can give one or more optional source_file names, else cvs will compare all files in the current directory and all subdirectories.

However, be aware that this will not give any information about changes between the local source file and any changes that have been checked in by others. Only changes that have been made to the local source file and it's original source.

History of Changes

To look at the history of changes:

cvs log [source_file]

Status of Changes

To check the current status of a source_file or all the files:

cvs status [source_file]

A couple of useful C-shell aliases to create are:

cvsstat

shows just the status of all files

alias   cvsstat 'cvs status \!* |& grep Status:'

cvswhat

shows the status of files that are not "Up-to-date"

alias   cvswhat 'cvs status \!* |& grep Status: |& grep -v "to-date"'

Remove a File

To remove a file from the repository:

rm source_file             # must first remove it locally
cvs rm source_file         # schedules it for removal

Add a File

To add a file to the repository

vi source_file             # create the file first
cvs add source_file        # schedules it to be added

Move a File

This can not be done cleanly at the local level. The best way to do this with CVS is to go to the cvsroot repository and move the file or directory within the repository there (if you are interested in keeping the history of changes). The cvsroot repository keeps all files in their RCS form of filename,v . The next cvs update will manifest the file move.

Check In Local Changes

Once you've made all the changes you care to for the current batch then:

cvs ci [source_file]

which checks-in the changes and updates the repository sources. CVS will pop-up an editor session where you can describe the changes made, which appears in the source_file log for each file affected.

Update Local Sources

If many people are working on the repository, you can obtain any changes in the repository that have been made since you've checked out the sources with:

cvs update [source_file]

and if there are conflicts, then CVS will notify you and flag it in the sources. On the Crays, I've noticed that CVS can't use the "patch" facility hence it will default to copying, which is not a problem, so ignore such messages.

Tagging Sources

You can "tag" the current set of changes (revisions) with:

cvs tag tag_name

then this set of local sources can be recovered with this "tag_name"

Another option is to tag the repository sources with

cvs rtag tag_name prj_name

which you want to do for each "release" of the code, so you can always backtrack any bugs to the version released to the users.

Creating Patches

You can create a "patch" file of changes with

cvs rdiff -u -r tag_name -r initial prj_name > patch_file

which will have all the changes you've made between the "tag_name" version and the "initial" version. You can also create patch files between any two tags.

You can also create a "patch" file of your local changes with:

cvs diff -N -u -r tag_name > patch_file

Backing Out Changes

Suppose you modify a file, but don't want to keep the changes:

rm source_file                  # remove it from local sources
cvs update source_file          # get a new copy from the repository

Using Branches

Working with branches is one of the more difficult concepts to master with CVS, but it is one of the most useful for an active development project.

The concept is that the software project has made a release, say version 3.1.0, and work is now progressing on version 3.2. However, a bug was discovered in the released 3.1.0 version, which you want to fix. Suppose that the project was tagged with prj_3_1_0. Also, it will be assumed that it wasn't marked as a branch (-b).

Need to tag the current tag sources as a branch with

cvs rtag -b -r prj_3_1_0 prj_3_1_0_branch project_name

Check out the given tagged version into a directory named prj.3.1.0 with
```
cvs checkout -d prj.3.1.0 -r prg_3_1_0_branch project_name
```
Get into the prj.3.1.0 directory for further work.
Make whatever changes to the sources, which will be identified as version 3.1.1
Check in changes for this branch as
```
cvs commit
```
Tag this version with
```
cvs tag -r prj_3_1_1
```
Make a tar ball for distribution, and remove the branch project directory, which is no longer needed.
If there are any fixes that can be merged into the main development branch. (This only works if the differences between this branch and the development branch are fairly small.) Get into a checked-out project directory (not the branch directory which should have been removed).
Merge the branch changes with the main development branch with
```
cvs update -j prj_3_1_1
```
Carefully, note the output, and resolve any conflicts, and test changes.
Note that merges can be incorporated into other branches by applying them to whatever checked-out version.

Sticky Tags!

Generally, what happens when a tagged version is checked out:

cvs checkout -d prj.3.1.0 -r prg_3_1_0 project_name

Something in the CVS directories makes the tag "sticky" and no changes can be updated or checked in. An attempt to cvs commit any local changes usually results in a message saying the "sticky" tag is not a branch!

The tag needs to be made into a branch with
```
cvs tag -b -r prj_3_1_0 prj_3_1_0_branch
```
Where the -b is the key here to making a branch.
Update the current working version as a branch with:
```
cvs update -r prj_3_1_0_branch
```
This will not affect the source files, only the CVS/Entries files will be updated to a different "sticky" tag ... a branch in this case.
The changes can now be checked in to that branch with
```
cvs commit
```
Changes in this branch can be merged into the development branch. (See the latter part of "Using Branches" for more details.)

More Info

To get more usage info:

cvs --help                      # usage info and general cvs-options
cvs --help-commands             # list & description of commands
cvs --help-options              # general cvs-options
cvs --help command              # command specific usage & command options

and

man cvs                         # gives an overview

Brought to you by: R.K. Owen,Ph.D.
This page is http://rkowen.owentrek.com/howto/cvs.html