Using CVS to manage your files
CVS stands for 'Concurrent Versions System', which is another
way of saying that multiple users can check out private copies of files from a
central repository, each can work on them at the same time (this is the
'Concurrent'), and when they're finished, check them back into the central
repository, where they are assigned a unique version number (this is the
'Versions' part of it). Any other CVS user can then integrate those changes into
his/her own version by using a simple command (this is why it's called a
'System'!). If two or more users happen to have modified the same section of
the file, CVS is often able to figure out how to combine them all. If it can't,
it tells you, so you can do it by hand.
However, it's useful for more than just sharing files with
other people. Each time you check a file in, CVS remembers the differences
between that version and the one that came before it. At a later time, you may
want to go back to a previous version (perhaps several revisions ago), and CVS
provides a very simple way to do that. So, it's really a pretty easy system for
keeping track of all the changes you made since you start working on the
project. Think of it as a safety net.
Below are some steps necessary to start using the CVS system
in the Roth Lab.
How to become a CVS user.
- You
must be a member of the cvs group, to have access to the central
CVS repository. At the command line, type 'groups'. If you don't see 'cvs'
there, you're not in the group. Ask the system administrator to add you to
this group.
- You
need to make sure that the cvs executable is in your path. At the
command-line prompt, type 'which cvs'. It should come back with
'/usr/local/bin/cvs', or something similar. If it gives you an error
message, then the cvs executable is not in your path, and you may need to
modify it.
- You
need to tell CVS where to find the central repository, which you do by setting
the environment variable $CVSROOT. It should be
'/usr/local/cvsroot'. It's advisable to set in your .profile or .bashrc or
other script that's run when your shell starts up.
- That's
it! Now you're ready to start checking things out.
- Most
people find it's a good idea to keep all the files under CVS control
together, so they create a 'cvs' directory in their home, and check out
all the CVS there.
- But
wait! There's more.
- Talk
to the owner of the project before you start checking changes back in. After
all, this is CVS, not ESP. There's no substitute for talking to each
other.
- Read
the manual. There's a printed copy available (ask Frank), and it's always
available online at http://www.cvshome.org/docs
. It's a complicated piece of software, nobody knows all the answers.
- You'll
notice that CVS creates a sub-directory called 'CVS', containing a few
extra files, and there's one in each directory of each project. These are
used by CVS to keep things organized. Except in the direst emergency, it
is unwise to edit these files.
How to create a new CVS project.
(Note, this does not discuss how to set up the CVS
repository in the first place. This should only need to be done once in the
life of a computer system, and it's already been taken care of. See the CVS
manual for details.)
- First,
you need to read 'How to become a CVS user.' Only if that works can you
start thinking about starting new projects.
- Projects
are started by using the 'import' command. You can't start an empty
project. The idea is that you already have a collection of files (or even
just a single one) that you would like to put under CVS control. It
doesn't have to work properly (if it's code), and it doesn't matter who
wrote it (you or someone else). To CVS it's just a bunch of files (they
can be perl files, Word documents, html, whatever). The project can
consist of sub-directories, nested arbitrarily deeply.
- To
start the new project (assume it's located in the directory 'wdir'), issue
the following command:
cd wdir
cvs import –m “Imported
sources” GOFish GOFish start
The '-m' specifies a message to associate with the
very first version you check in (the version number will be 1.1.1.1 – I don't
know why). You could put something different, but “Imported sources” seems good
enough.
The first 'GOFish' above specifies the name of the
directory under which all the files will appear; that is, when someone checks
it out, they will say 'cvs checkout GOFish', and CVS will create, in their
current working directory, a sub-directory called GOFish containing all the
files associated with that project.
The second GOFish is what CVS calls a 'vendor tag'.
The word 'start' is a 'release tag'. Both of these are pretty redundant – I've
never had a use for them.
- Think
carefully about how you will name the project, since it is difficult to
change project names once they have been set up. It's not a good idea to
put your name in there. It's probably also not a good idea to
include things like 'perl', 'java', 'html' in the name of a project
either. The name should be an abstract representation of the project's
function, not a description of the implementation. Talk to somebody who's
done this before, to learn from their experience. Right now (09/2001),
we've decided that we'll just organize things under scientific project
names, so for example, all the files related to the GOFish project will be
checked in as cvs/GOFish, ditto for ClusterJudge, etc.
- Once
you're done importing it, don't forget to check it back out. Until you've
done so, all you've told CVS is that there's a new project, but you
haven't given it a chance to realize that this directory from which you
just checked it in is a working copy of that project. (Confusing, but
true.) Checking it out (and you can check it out either 'on top of' the
existing version, or somewhere else) gives CVS a chance to create those
little auxiliary files that help it stay organized.
- You're
done. Any other CVS user is now free to check out your project. By
default, no permissions are set (i.e., the 'access list' is empty), but it
is possible to turn on a permission system, so that the project's owner
can control access to the project, in a manner very similar to the UNIX
filesystem privileges: users may have any combination of read (allowed to
check out), write (allowed to check in) or create (allowed to create new
files) permissions.
- There's
lots more to learn – RTFM!
This document likely contains errors and oversights. It can
be improved by emailing its author.