i-scream documentation viewer

cvs-2.txt

Using CVS (part 2)
==================

Contents
--------
 - Errata to "Using CVS (part 1)"
   - Setting up CVS on a Public PC (with WinCVS/SSH)
   - Setting up CVS off campus/SSB (with WinCVS/SSH)
  
 - How CVS handles binary files
 - Tagging the Repository
 - Branching in CVS
 - Keyword Expansion
 - Online CVS Resources

 - See "Using CVS (part 1)" for basic information on setting
   up and using CVS at UKC.

   tdb1, 29/10/00.

Errata to "Using CVS (part 1)"
------------------------------
Setting up CVS on a Public PC (with WinCVS/SSH)
-----------------------------------------------
Assuming you already have WinCVS working we just need to
make a few modifications to get the same thing working with
SSH. This will only work on a public PC, although with some
careful copying of files you might be able to get it to work
on a normal SSB machine.

Firstly we need to get SSH working. As it is SSH does work,
but it will keep prompting for a password, which is a pain
when it's hidden in a cmd window somewhere. We'll start by
tweaking the SSH setup, and then we'll setup a key pair to
remove the need for a password.

[adapted from instructions given by jc]

First thing is to setup a few environment variables. This is
done in the System part of Control Panel. Under the User
Variables section add the following;

HOME =
   z:\username
CVS_RSH =
   ssh
CVSROOT =
   :ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs

Next we need to go about setting up the key pair. This is
done by two batch files called getkey.bat and copy-key.bat
which are already on the public PC's. Unfortunately you need
to modify getkey.bat to make it work with raptor, so copy it
from the C: drive (c:\winnt\system32 I believe) to your
desktop (or anywhere else). Edit it so that the third line
reads;

set HOST=raptor

Then run it. You'll be prompted for your raptor password
three times, and then the key is setup. Next you need to run
copy-key.bat. Just go to "Start -> Run -> copy-key raptor"
to make it do it's stuff.

Now, we're pretty much all set. You should be able to type
"ssh -l <user> raptor" into a command window and log
straight in without the need for a password. If not,
something has gone wrong !

Finally, a quick alteration to WinCVS and we're done. In the
preferences set the CVS Root to be;

:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs

Then set the Authentication type to "SSH server". Assuming
you've already done the rest of the setup from the last
document you should be able to do a checkout as normal, but
this time without the need for a mapped drive - which is a
much neater way of doing things.

Setting up CVS off campus/SSB (with WinCVS/SSH)
-----------------------------------------------
To do this you'll need two packages. Firstly, and most
obviously WinCVS. The latest version of WinCVS (1.1b16) can
be downloaded from the "WinCvs 1.1 *BETA* / Client + Local /
Binaries" on the following page;

http://www.wincvs.org/download.html

Secondly you'll require SSH. I'm not sure where this package
orginated, but there is a current version on raptor at;

/usr/local/proj/co600_10/sshwin32/ssh-1.2.14-win32bin.zip

Armed with those two files you're ready to go. To get
started we need to get ssh installed, and a key setup with
raptor.

Installing ssh is easy. Simply extract the contents of the
zip file in to your windows\system32 directory (on
winnt/win2k - windows\system on win9x). This will put the
DLL's in place and the binary ssh files.

Next, setting up a key. This requires a few straightforward
steps.

 - setup a directory (on your machine) to be considered your
   "home folder" and then ensure that the environment
   variable HOME is pointed at this directory. Then make a
   directory called .ssh within this.

 - telnet into raptor and run this command;
     ssh-keygen -f ssh-newkey -q -P '' -C '<user> on NT'
  
   make sure you change <user> for your userid, and that you
   notice that there are *only* single quotes like this ' .

 - using ftp (or by any other means) copy the files named
   ssh-newkey and ssh-newkey.pub to the .ssh folder you made
   on your machine. Now rename them to identity and
   identity.pub respectively.

 - Finally we need to get the contents of the identity.pub
   file above into the file ~/.ssh/authorized_keys on
   raptor. The easiest way to do this is to type the
   following;
     cat ssh-newkey.pub >> .ssh/authorized_keys
    
   This assumes you didn't delete the ssh-newkey files, and
   that you are in your home folder. Finally, you can delete
   the ssh-newkey and ssh-newkey.pub files from raptor.

Now, to test this setup you should try the following from a
command prompt (on your machine, not raptor);

ssh -l <userid> raptor.ukc.ac.uk

If everything has completed successfully you should now be
looking at a raptor prompt. You should NOT have been asked 
for a password ! If it went wrong... work out why!

Right, now on to WinCVS. This is now a doddle. In the
preferences set the CVSROOT to;

:ext:<user>@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs

Set Authentication to SSH server, and set the RSA identity
to your identity file (not the .pub one). On the ports tab
check the "alternate rsh name" box at the bottom, and make
sure "ssh" is in the text box. You might also like to
uncheck "checkout read-only" and "prune empty directories"
on the globals tab.

Finally set the browser directory to a suitable location and
try checking something out. If all has worked an SSH window
should pop up at the bottom of the screen and the files
should appear.

As a final note, turning TCP/IP compression on may make it
quicker over a modem.

How CVS handles binary files
----------------------------
Basically CVS can't do version management of binary files,
and quite obviously this is because it's not possible to
make version comparisons between two revisions in a logical
way. But, CVS will let you store binary files and will let
you add new versions. However, it will not store "changes"
between them, or allow you to view diffs between them.

IMPORTANT: You must make sure you tell CVS that a file is
           binary, otherwise it will not store it correctly
           and the file will be corrupted.

In WinCVS it's really easy to add a binary file, simply
select "Add selection binary" instead of the usual "Add
selection". WinCVS will display a "binary" icon instead, and
add "-kb" into the Option column. This -kb tells the CVS
command that the file is binary.

This leads nicely into how to do it from the command line.
You simply type the following in place of the usual "cvs
add" command.

cvs add -kb <filename>

Again, the -kb is present. Now, a quick explanation of what
this "-kb" means. Basically it is telling CVS not to do
keyword expansion (turning $Revision$ into $Revision: 1.3 $)
and tell is not to attempt to convert between unix/windows
text formats.

Tagging the Repository
----------------------
Tagging the repository is a way of "marking" all the files
at a particular point in time. For example, when "release 1"
is finished you might want to mark this in the history of
all the files, so you can easily come back to it in the
future. As every file the makes up "release 1" may be on a
different individual revision, it would be tedious to do
without the aid of tagging.

This is the best example I've seen that clearly shows how a
tag is implemented. Imagine the dotted line signfies the
point at which you declared the files were "release 1". As
you can see, work as continued on the files, but you could
easily pull out each file at "release 1".

   File A      File B      File C      File D      File E
   ------      ------      ------      ------      ------
   1.1         1.1         1.1         1.1         1.1
---1.2-.       1.2         1.2         1.2         1.2
   1.3 |       1.3         1.3         1.3         1.3
        \      1.4       .-1.4-.       1.4         1.4
         \     1.5      /  1.5  \      1.5         1.5
          \    1.6     /   1.6   |     1.6         1.6
           \   1.7    /          |     1.7         1.7
            \  1.8   /           |     1.8       .-1.8----->
             \ 1.9  /            |     1.9      /  1.9
              `1.10'             |     1.10    /   1.10
               1.11              |     1.11    |
                                 |     1.12    |
                                 |     1.13    |
                                  \    1.14    |
                                   \   1.15   /
                                    \  1.16  /
                                     `-1.17-'

In fact, if you imagine pulling this line straight, you'd
get the following effect which even more clearly shows where
"release 1" is.

   File A      File B      File C      File D      File E
   ------      ------      ------      ------      ------
                                       1.1
                                       1.2
                                       1.3
                                       1.4
                                       1.5
                                       1.6
                                       1.7
               1.1                     1.8
               1.2                     1.9
               1.3                     1.10        1.1
               1.4                     1.11        1.2
               1.5                     1.12        1.3
               1.6                     1.13        1.4
               1.7         1.1         1.14        1.5
               1.8         1.2         1.15        1.6
   1.1         1.9         1.3         1.16        1.7
---1.2---------1.10--------1.4---------1.17--------1.8----->
   1.3         1.11        1.5         1.17        1.9
                           1.6         1.17        1.10

Tagging is actually remarkably easy to do. All you do is
issue a single command to tag the files at the current point
in time. You should make sure all development stops whilst
you do it, otherwise a bit of new code could sneak in.
Here's how to do it;

cvs tag public-release_1

This would mark the files with the tag "public-release_1".
You can then continue with developement, knowing that all
those files can easily be retrieved. It's again suprisingly
easy to do. Instead of typing "cvs checkout source" you
would type;

cvs checkout -r public-release_1 source

Which would checkout the source module at the point which
you tagged. Alternatively the following would update (or
downdate ?) your working copy to the tagged point;

cvs update -r public-release_1

Finally, a quick mention of why this would be useful.
Imagine the development team was split into two groups, one
working on coding, another working on testing. When the
coding group have finished "release 1" they can tag it and
carry on developing for "release 2". At the same time, the
testing team can checkout "release 1" and test it, reporting
bugs back to the coding team for fixing in "release 2". It
could also mean the a customer could still get hold of the
first release whilst you're busy coding for the second.

Branching in CVS
----------------
So far I've only talked about a single CVS branch, the
trunk. There is only ever one "current" revision of each
file, and everyone is working on the same files. However, it
is possible to branch this out into more than one copy of
the same files. A good example of why this is useful is
continuing the idea at the end of the last section.

Imagine the coding team are now busy working on "release 2"
and the testing team come up with a major flaw in
the older "release 1". Customers have already got this
version installed, so it needs fixing straight away. The
trick is to make a branch at the point where "release 1" was
tagged, and then fix the bugs on this branch. This branch
need not carry on, it could just have the few bugs fixed,
whilst the main branch (the trunk) has development of
"release 2" carrying on. This diagram shows this;

                |
                |    -- tag "release_1"
                |\
                | \
                | |
                | |
                | -  -- tag "release_1-fixed"
                |
                |
                |    -- tag "release_2"

As you can see the customer could then get a copy of
"release_1-fixed" and not worry about the unstable code in
"release_2".

Branches can get much more complicated than this, but it's
beyond the scope of our requirements. Further info can be
found on the web.

Keyword Expansion
-----------------
CVS allows you to put certain keywords into a file which CVS
will expand when you check files in and out of the
repository. There are quite a few, and they're all pretty
useful in places. Here's a quick summary;

$Author$
  The author of the latest change.
    eg. $Author: tdb1 $

$Date$
  The date/time of the latest change.
    eg. $Date: 2000/10/30 13:10:04 $

$Header$
  Various useful bits of information.
    eg. $Header: /usr/local/proj/co600_10/cvs/file.txt,v \
        1.1 2000/10/30 13:00:00 tdb1 Exp tdb1 $

$Id$
  Simliar to $Header$, but without that wieldy path.
    eg.
     $Id: cvs-2.txt,v 1.3 2000/10/30 13:10:04 tdb1 Exp $

$Log$
  Puts the latest log message in.

$Locker$
  Name of the person who has a lock (usually no-one).
    eg. $Locker: tdb1 $

$Name$
  Name of the tag.
    eg. $Name: release_1 $

$RCSfile$
  Name of the RCS file.
    eg. $RCSfile: cvs-2.txt,v $

$Revision$
  Revision number of the file.
    eg. $Revision: 1.3 $

$Source$
  Full path to the file in the repository.
    eg. $Source: /usr/local/proj/co600_10/cvs/file.txt,v $

$State$
  State of the file (?).
    eg. $State: Exp $

The keywords are automatically replaced by CVS, even if it's
already been expanded. You just put it in and leave it be!

Online CVS Resources
--------------------
That about concludes my guide on the basics of CVS for the
development work in the project. However, further resources
can be found on the following webpage. I've learnt an awful
lot from this "online book", and I'd recommend it to anyone
wanting to get to grips with CVS.

http://cvsbook.red-bean.com

Also, the "home" of CVS, if there is such a thing.

http://www.cvshome.org

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