An introduction to CVS

CVS is the version control system we (well, some of us) use around the ILRT. It manages source code and other projects that fit into the text-document mold.

It's pretty straightforward, once you get to grips with it, but the "getting to grips with" can sometimes prove problematical.

I'm offering a short session introducing the command-line tools for CVS for those who've not seen it before: the target audience is technical developers who haven't used CVS before.

Prerequisites will be some familiarity with a unix command line, a unix account, and I'll need names beforehand so that we can set up access to the repository for people. I'm not going to go into advanced esoterica but I might run a followup later on if it proves popular.

Because the introduction has to be practical, there's a maximum limit of 6 people for this.

I'll also try to present some guidelines about how to get the most out of CVS (a "CVS patterns" guide, if you will).

Prerequisites - please read

The following are things you need to check or do prior to turning up for the session. Please, please get in touch with me on or before the 4th July 2003 if you are having trouble with any of these.

You need a Unix shell account with access to the ssh and cvs command-line tools. You almost certainly already have this with our mail server. To confirm this, use the "Secure Shell" tool to connect to mail.ilrt and type the following at your prompt:
```
> ssh
Usage: ssh [options] host [command]
Options:
  -l user     Log in using this user name.
[... rest of command help elided ...]
> cvs
Usage: cvs [cvs-options] command [command-options-and-arguments]
  where cvs-options are -q, -n, etc.
[... rest of command help elided ...]
```
If you cannot connect or see
```
cvs: Command not found.
```
then you should contact me for help.
I assume some familiarity with the basic Unix command line. You should know how to create, rename and remove directories and files, and should know what basic Unix file permissions are. I'm not giving an introduction to Unix course - ISER offers these on a regular basis and I consider such a course (or equivalent experience) a prerequisite to this session.
You need to familiarise yourself with a text-editor on the system. vi will be fine if you already know it. Otherwise you will probably be OK using pico. Both of these are available on mail.ilrt.
On your own machine, you'll have a raft of more convenient and pretty text editors to use, so this requirement may seem a little archaic. This is unfortunately out of my hands: we're going to be in the Computer Centre Training Room (TR-F) and the software provision on those machines doesn't include an appropriate text editor. (There's a CVS "gotcha" here that I'll explain on the day.)
You need to get an account on our CVS server. If you already have one of these, you'll know! Otherwise get in touch with me and I'll help you acquire one.
You need to generate a private/public keypair for the CVS server (this is merely a convenience). I've written instructions on how to do this but if you have trouble, please contact me before July 4th 2003 and I'll be able to give you a hand.
You need to ensure that a couple of environment variables are set up on your unix account. You can do this by testing out your text-editing skills on two files in your home directory.
To your .profile file, append these two lines:
```
CVSROOT=:ext:$USER@cvs.ilrt.org:/usr/local/cvsroot export CVSROOT
CVS_RSH=ssh export CVS_RSH
```
and to your .cshrc file, append these two lines:
```
setenv CVSROOT :ext:$USER@cvs.ilrt.org:/usr/local/cvsroot
setenv CVS_RSH ssh
```

Once you've done this, you're ready to go. I'm sorry if this list seems daunting, but if everyone is going to get the most benefit out of the session I'd like to get the debugging done prior to the day.

What we'll cover on the day

The following are pretty much what I'm intending to cover. This should run to no more than a couple of hours (depending on how fast we whizz through it) including time for coffee in the middle. I'm going to concentrate on the hands-on aspects rather than the theory.

Questions are invited at any time.

Basic CVS operation
- Checking out a module
- Adding directories and files
- Making changes
- Binary files
- Renaming files (renaming directories)
Multi-user CVS operation - introduction
- Organisation (CVS and yours!)
- Getting updates
- Conflicts, and how to avoid them
- Tags; checking out a particular version
Coffee will probably come here
Other stuff we can do with CVS here
- Commit lists
- CVSWeb
- Anonymous CVS
- Automatic checkout
Things to plan ahead for
- Laying out a module directory structure
- Automation
Miscellaneous
- Getting a CVS module for your project
- Getting the latest copy (HEAD) of a third-party piece of software
- Line end conventions / binary files
- Renaming part two
- Troubleshooting working copy problems
- CVS on a Windows desktop

What I'm not going to cover

The use of branches with CVS, while quite often important, is not necessarily vital for small projects. If people have a need for this I can do a followup session.
For work use, we'd encourage you to house your work-related CVS projects on our maintained CVS server. I'm not intending to go into the options for running your own CVS server in any depth.