i-scream documentation viewer
cvs-1.txt
Using CVS (part 1)
==================
Contents
--------
- Overview
- CVS Repository Structure
- Setting up CVS on Raptor
- Setting up CVS on a Public PC (with WinCVS)
- Setting up CVS from off campus
- How to use CVS
- See "Using CVS (part 2)" for information on binaries,
branching, tagging and keywords.
tdb1, 18/10/2000
Overview
--------
CVS means "Concurrent Versioning System" and is used to keep
version control on plain text files - usually source code,
or html, but can be anything that has a plain text
structure. It can store binaries, but doesn't offer the
same version comparison features for obvious reasons.
CVS also offers many features for group working, and doesn't
lock the files when someone starts editing them. Instead it
works by each user having their own "checked out" local copy
of the source code (or a portion of it). The user then works
on this code until they are happy with it, then runs an
update command. This checks to see if someone else has
updated the version in the repository, and if so brings
their changes down into the users local copy. This can cause
conflicts if both users change the same bit, but this
shouldn't really happen - unless group communication is
lacking. CVS will do it's best to merge these new changes
in, but occasionaly it will need help from the user. This is
just a case of reviewing the file with conflicts and
manually resolving them. When CVS is happy that any updates
in the repository have been merged it will allow a commit.
This puts the users changes into the repository for all to
access.
In essence, that's CVS. Checkout, update, commit. That's all
there really is to it.
I think CVS would be very beneficial in writing the code for
our project for two reasons. Firstly CVS will help us to
maintain a control on all of our code for QA purposes, and
make it easy for us to keep track of our "phases". We can
tag the code at the end of each phase, and then continue
development. At the same time, another group member could be
testing the code at the tagged point. Finally, the group
work features make it ideal for this situation.
CVS Repository Structure
------------------------
I am proposing the following structure for the CVS
Repository. I suggest that we keep it the same from the word
go, although we can add more into the hierachy it's not
usually a good idea to move things around.
ROOT
documentation
minutes
misc
papers
plan
presentation
specification
user
experimental
client
host
misc
server
misc
source
client
host
misc
server
web
client
website
cgi-bin
www
We may need to expand that a bit, but it's a start.
Setting up CVS on Raptor
------------------------
Setting up CVS on raptor to use our "repository" takes a bit
of effort. This is because the cs-sysadmin guys have been
setting up CVS to run from marble, but it's not ready yet.
All we have to do is override some of their default
environment variables. Right, so add the following lines to
your .cshrc file (presuming you are using csh, which I think
you are).
unsetenv CVSROOT
unsetenv CVSREAD
unsetenv CVS_RSH
unsetenv CVSIGNORE
setenv CVSROOT /usr/local/proj/co600_10/cvs
A quick explanation of what this actually means. Firstly the
CVSROOT is the root directory of the CVS repository. I've
set it up as a directory called 'cvs' in our project space.
Next the CVS_RSH variable tells CVS to use something like
SSH, which we don't need to do locally. CVSREAD makes CVS
mark the files it checks-out be read-only, which is meant to
make you use the cvs edit command... but it's just a
complete pain in the arse. Last of all CVSIGNORE tells CVS
not to add certain files, but I think we've got enough sense
to be able to do that ourselves... but by all means leave
that line out if you feel happier.
Setting up CVS on a Public PC (with WinCVS)
-------------------------------------------
WinCVS is (obviously) a Windows frontend to CVS. The command
line thing is far easier to use if you're doing stuff
directly on raptor (or any other unix box), but under
windows it's nice to be able to get at files much more
easily. It's also got the familiar "point-n-click" style
interface, but I personally find that confusing.
WinCVS can be found at the following location;
\\drogo\packages\gnu\wincvs\wincvs.exe
It's not under Install Packages, so you might want to make
your own shortcut on the desktop, which is what I've done.
Setting up is easy. First map a drive to \\raptor\grproj (go
for grproj to help keep the permissions happy). Then when
the preferences pop up bung in m:\co600_10\cvs (assuming you
used m: like I did...) and select "Local mounted directory"
under Authentication. The only other bits to change are
unticking the "Checkout read-only" under Globals (it's just
a damn pain), and under WinCVS you might want to change the
"HOME folder" to your Z: drive.
Then you're ready to go with doing usual CVS stuff. Oh, it
took me ages to figure how to change which drive/directory
is viewed in the main windows... it's hidden at the bottom
of the View menu.
Finally, it might be possible to get it working with SSH
straight onto raptor, but I'm not sure of the exact process,
and even if it'll work. I may add this as an errata in part2
of this documentation.
Setting up CVS from off campus
------------------------------
Using CVS from off campus is much trickier. We have no
"proper" CVS facilities on raptor for remote access (it can
run a server specifically for this task). However, as the
command line CVS will make use of SSH we can connect through
the firewall. This is fine if you have a Unix box at home,
but I'm not sure (again) if this will work from Windows.
From any Unix box (that has SSH and CVS installed) you just
need to setup the following environment variables. These are
best put in a file such as .cshrc (for the csh shell).
CVS_RSH =
ssh
CVSROOT =
:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
Every shell has it's own way of setting up environment
variables, for example csh using the setenv command. Consult
the man pages for more details.
With this done you can use the command line facilities as
usual, and you will be prompted for your raptor password
each time a connection is made.
How to use CVS
--------------
There are three main CVS operations that you'll use on a
regular basis; checkout, update and commit. Then there's the
smaller commands such as add, delete, and export. I'll
describe them, then give an example. This all assumes you've
setup the CVSROOT environment variable as described above.
These commands are for the command line version of CVS, but
the ideas can be applied to any version, including WinCVS.
A full list of commands can be found by typing;
cvs --help-commands
A quick mention of the version numbers first. Each file has
a unique version number starting at 1.1 and incrementing to
1.2, 1.3 and so on. It never becomes 2.x, unless you
manually change it. These version numbers are independant
for every single file, and have no overall bearing on any
"release versions" that go out to the public.
Firstly, the 'checkout' command. This extracts a copy of a
section of the CVS Repository to a local working copy. All
work (editing) is then carried out on this local copy. The
local copy can be changed, completely deleted, or
whatever... it'll have no effect on the database. The
command has the following format;
cvs checkout <module>
eg.
cvs checkout source/server
This would extract a copy of all the files in server/source
and all subdirectories below this. Note that CVS control
files will be created in 'CVS' subdirectories all over the
place, they're best ignored.
Next the 'update' command. This command ensures that the
local copy is up-to-date with the database. If the checkout
was done a few days ago it's possible someone else may have
updated something in the main repository since the original
checkout. After issuing the update the local copy will be
updated. The command is very simple;
cvs update
The exception to this is if the user has changed the local
copy in some way. In this case the update still takes place,
but any changes are merged into the local copy. No updates
are sent to the repository, this is important to remember!
This could of course cause problems if the update on the
repository and the local update are on the same bit of code.
Usually CVS can merge updates, but in this instance it will
give a conflict error and the user will have to manually
resolve them. This is a simple case of checking the code the
problem areas will be marked out. After the conflicts have
been resolved another update could be done to verify it's
all OK.
The update command also lets you know the state of files. If
it puts an 'M' next to a file (when it lists them) it means
you've modified it. If it's got a '?' it means the file is
new or not part of the CVS (you have to add new files). A
'C' means a conflicting file, and I think maybe 'A' means
the file is scheduled to be added. There are probably
others, check "man cvs" :)
Right, the last main command is 'commit'. This puts local
changes back into the repository and updates the version
number. You should run an update first, though, and commit
will complain if you haven't done when you need to. You will
need to enter a comment, and it's good practice to describe
roughly the reason for the commit - it helps keep a good
audit trail, and lets other users know why you did what you
did. In Unix it'll probably load up vi, which is ugly... I
think if you change the EDITOR enviroment variable you can
set it to use pico. The commit command is as easy as;
cvs commit
That's all there is to the everyday CVS commands. Next the
occasional commands. Now on to the less used ones.
Lets start with the 'add' command. Say you've done a
checkout of source/server and you've added a file called
main.java into the directory. Now lets add it to the
repository.
cd source/server
cvs add main.java
The add command will tell you that it's scheduled to be
added at the next commit. Simply run an update then commit
for the file to be added.
The 'remove' command works in a similar way I think. I'm not
sure whether you have to delete the file first, you'll have
to try it. Again you'll need to update then commit. A note
about deleted. The file obviously won't be deleted
completely, that would defeat the point in a versioning
system. Instead it's moved to an Attic subdirectory in the
CVS so you can still review it's revisions in the future,
and even resurrect it.
Next there's the 'release' command. This is used as a tidy
way of cleaning up the local files when you've finished with
them. To remove the above example you'd do the following;
cvs release source/server
This will ensure that you don't accidently delete any local
changes by informing you first of any non-commited files. If
you add the -d switch it will actually delete the files too;
cvs release -d source/server
This is much safer than typing "rm..." :)
Finally, the 'export' command. This has almost the same
effect as the checkout command, but it doesn't create any of
the CVS control files. The aim of this command is to extract
sources for public release, so you can zip them up and send
them out to the client. For example;
cvs export source
tar -cvf source.tar source
gzip -v9 source.tar
That's just about it for basic CVS. I'll probably produce
another document on tagging at some point in the future.
About
-----
This document was written by Tim Bishop [tdb@i-scream.org] for
use by the team working on a 3rd year Computer Science
project called "i-scream". More details can be found on the
project website;
http://www.i-scream.org
