documentation/papers/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
Revision:	1.6
Committed:	Sun Aug 1 10:39:54 2004 UTC (20 years, 3 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.5:	+2 -2 lines
Log Message:	Catch a lot of old URL's and update them. Also remove a couple of old files that aren't used.
#	User	Rev	Content
1	tdb	1.1	Using CVS (part 2)
2			==================
3
4	tdb	1.2	Contents
5			--------
6			- Errata to "Using CVS (part 1)"
7			- Setting up CVS on a Public PC (with WinCVS/SSH)
8	tdb	1.3	- Setting up CVS off campus/SSB (with WinCVS/SSH)
9	tdb	1.5
10	tdb	1.2	- How CVS handles binary files
11			- Tagging the Repository
12			- Branching in CVS
13			- Keyword Expansion
14			- Online CVS Resources
15	tdb	1.5
16			- See "Using CVS (part 1)" for basic information on setting
17	tdb	1.2	up and using CVS at UKC.
18
19			tdb1, 29/10/00.
20	tdb	1.1
21			Errata to "Using CVS (part 1)"
22			------------------------------
23			Setting up CVS on a Public PC (with WinCVS/SSH)
24			-----------------------------------------------
25	tdb	1.5	Assuming you already have WinCVS working we just need to
26			make a few modifications to get the same thing working with
27			SSH. This will only work on a public PC, although with some
28			careful copying of files you might be able to get it to work
29	tdb	1.1	on a normal SSB machine.
30
31	tdb	1.5	Firstly we need to get SSH working. As it is SSH does work,
32			but it will keep prompting for a password, which is a pain
33			when it's hidden in a cmd window somewhere. We'll start by
34			tweaking the SSH setup, and then we'll setup a key pair to
35	tdb	1.1	remove the need for a password.
36
37			[adapted from instructions given by jc]
38
39	tdb	1.5	First thing is to setup a few environment variables. This is
40			done in the System part of Control Panel. Under the User
41	tdb	1.1	Variables section add the following;
42
43			HOME =
44			z:\username
45			CVS_RSH =
46			ssh
47			CVSROOT =
48			:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
49
50	tdb	1.5	Next we need to go about setting up the key pair. This is
51			done by two batch files called getkey.bat and copy-key.bat
52			which are already on the public PC's. Unfortunately you need
53			to modify getkey.bat to make it work with raptor, so copy it
54			from the C: drive (c:\winnt\system32 I believe) to your
55			desktop (or anywhere else). Edit it so that the third line
56	tdb	1.1	reads;
57
58			set HOST=raptor
59
60	tdb	1.5	Then run it. You'll be prompted for your raptor password
61			three times, and then the key is setup. Next you need to run
62			copy-key.bat. Just go to "Start -> Run -> copy-key raptor"
63	tdb	1.1	to make it do it's stuff.
64
65	tdb	1.5	Now, we're pretty much all set. You should be able to type
66			"ssh -l <user> raptor" into a command window and log
67			straight in without the need for a password. If not,
68	tdb	1.4	something has gone wrong !
69	tdb	1.1
70	tdb	1.5	Finally, a quick alteration to WinCVS and we're done. In the
71	tdb	1.1	preferences set the CVS Root to be;
72
73			:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
74
75	tdb	1.5	Then set the Authentication type to "SSH server". Assuming
76			you've already done the rest of the setup from the last
77			document you should be able to do a checkout as normal, but
78			this time without the need for a mapped drive - which is a
79	tdb	1.1	much neater way of doing things.
80	tdb	1.3
81			Setting up CVS off campus/SSB (with WinCVS/SSH)
82			-----------------------------------------------
83	tdb	1.5	To do this you'll need two packages. Firstly, and most
84			obviously WinCVS. The latest version of WinCVS (1.1b16) can
85			be downloaded from the "WinCvs 1.1 BETA / Client + Local /
86	tdb	1.3	Binaries" on the following page;
87
88			http://www.wincvs.org/download.html
89
90	tdb	1.5	Secondly you'll require SSH. I'm not sure where this package
91	tdb	1.3	orginated, but there is a current version on raptor at;
92
93			/usr/local/proj/co600_10/sshwin32/ssh-1.2.14-win32bin.zip
94
95	tdb	1.5	Armed with those two files you're ready to go. To get
96			started we need to get ssh installed, and a key setup with
97	tdb	1.3	raptor.
98
99	tdb	1.5	Installing ssh is easy. Simply extract the contents of the
100			zip file in to your windows\system32 directory (on
101			winnt/win2k - windows\system on win9x). This will put the
102	tdb	1.3	DLL's in place and the binary ssh files.
103
104	tdb	1.5	Next, setting up a key. This requires a few straightforward
105	tdb	1.3	steps.
106
107	tdb	1.4	- setup a directory (on your machine) to be considered your
108	tdb	1.5	"home folder" and then ensure that the environment
109			variable HOME is pointed at this directory. Then make a
110	tdb	1.4	directory called .ssh within this.
111	tdb	1.3
112			- telnet into raptor and run this command;
113	tdb	1.4	ssh-keygen -f ssh-newkey -q -P '' -C '<user> on NT'
114	tdb	1.5
115			make sure you change <user> for your userid, and that you
116			notice that there are only single quotes like this ' .
117
118			- using ftp (or by any other means) copy the files named
119			ssh-newkey and ssh-newkey.pub to the .ssh folder you made
120			on your machine. Now rename them to identity and
121	tdb	1.3	identity.pub respectively.
122
123	tdb	1.5	- Finally we need to get the contents of the identity.pub
124			file above into the file ~/.ssh/authorized_keys on
125			raptor. The easiest way to do this is to type the
126	tdb	1.3	following;
127			cat ssh-newkey.pub >> .ssh/authorized_keys
128	tdb	1.5
129			This assumes you didn't delete the ssh-newkey files, and
130			that you are in your home folder. Finally, you can delete
131	tdb	1.3	the ssh-newkey and ssh-newkey.pub files from raptor.
132
133	tdb	1.5	Now, to test this setup you should try the following from a
134	tdb	1.4	command prompt (on your machine, not raptor);
135	tdb	1.3
136			ssh -l <userid> raptor.ukc.ac.uk
137
138	tdb	1.5	If everything has completed successfully you should now be
139			looking at a raptor prompt. You should NOT have been asked
140			for a password ! If it went wrong... work out why!
141	tdb	1.3
142	tdb	1.5	Right, now on to WinCVS. This is now a doddle. In the
143	tdb	1.3	preferences set the CVSROOT to;
144
145			:ext:<user>@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
146
147	tdb	1.5	Set Authentication to SSH server, and set the RSA identity
148			to your identity file (not the .pub one). On the ports tab
149			check the "alternate rsh name" box at the bottom, and make
150			sure "ssh" is in the text box. You might also like to
151			uncheck "checkout read-only" and "prune empty directories"
152	tdb	1.4	on the globals tab.
153
154	tdb	1.5	Finally set the browser directory to a suitable location and
155			try checking something out. If all has worked an SSH window
156			should pop up at the bottom of the screen and the files
157	tdb	1.4	should appear.
158	tdb	1.3
159	tdb	1.5	As a final note, turning TCP/IP compression on may make it
160	tdb	1.3	quicker over a modem.
161	tdb	1.1
162			How CVS handles binary files
163			----------------------------
164	tdb	1.5	Basically CVS can't do version management of binary files,
165			and quite obviously this is because it's not possible to
166			make version comparisons between two revisions in a logical
167			way. But, CVS will let you store binary files and will let
168			you add new versions. However, it will not store "changes"
169	tdb	1.1	between them, or allow you to view diffs between them.
170
171	tdb	1.5	IMPORTANT: You must make sure you tell CVS that a file is
172			binary, otherwise it will not store it correctly
173	tdb	1.1	and the file will be corrupted.
174
175	tdb	1.5	In WinCVS it's really easy to add a binary file, simply
176			select "Add selection binary" instead of the usual "Add
177			selection". WinCVS will display a "binary" icon instead, and
178			add "-kb" into the Option column. This -kb tells the CVS
179	tdb	1.1	command that the file is binary.
180
181	tdb	1.5	This leads nicely into how to do it from the command line.
182			You simply type the following in place of the usual "cvs
183	tdb	1.1	add" command.
184
185			cvs add -kb <filename>
186
187	tdb	1.5	Again, the -kb is present. Now, a quick explanation of what
188			this "-kb" means. Basically it is telling CVS not to do
189			keyword expansion (turning $Revision$ into $Revision: 1.3 $)
190			and tell is not to attempt to convert between unix/windows
191	tdb	1.1	text formats.
192
193			Tagging the Repository
194			----------------------
195	tdb	1.5	Tagging the repository is a way of "marking" all the files
196			at a particular point in time. For example, when "release 1"
197			is finished you might want to mark this in the history of
198			all the files, so you can easily come back to it in the
199			future. As every file the makes up "release 1" may be on a
200			different individual revision, it would be tedious to do
201	tdb	1.1	without the aid of tagging.
202
203	tdb	1.5	This is the best example I've seen that clearly shows how a
204			tag is implemented. Imagine the dotted line signfies the
205			point at which you declared the files were "release 1". As
206			you can see, work as continued on the files, but you could
207	tdb	1.1	easily pull out each file at "release 1".
208
209			File A File B File C File D File E
210			------ ------ ------ ------ ------
211			1.1 1.1 1.1 1.1 1.1
212			---1.2-. 1.2 1.2 1.2 1.2
213			1.3 \| 1.3 1.3 1.3 1.3
214			\ 1.4 .-1.4-. 1.4 1.4
215			\ 1.5 / 1.5 \ 1.5 1.5
216			\ 1.6 / 1.6 \| 1.6 1.6
217			\ 1.7 / \| 1.7 1.7
218			\ 1.8 / \| 1.8 .-1.8----->
219			\ 1.9 / \| 1.9 / 1.9
220			`1.10' \| 1.10 / 1.10
221			1.11 \| 1.11 \|
222			\| 1.12 \|
223			\| 1.13 \|
224			\ 1.14 \|
225			\ 1.15 /
226			\ 1.16 /
227			`-1.17-'
228
229	tdb	1.5	In fact, if you imagine pulling this line straight, you'd
230			get the following effect which even more clearly shows where
231	tdb	1.1	"release 1" is.
232
233			File A File B File C File D File E
234			------ ------ ------ ------ ------
235			1.1
236			1.2
237			1.3
238			1.4
239			1.5
240			1.6
241			1.7
242			1.1 1.8
243			1.2 1.9
244			1.3 1.10 1.1
245			1.4 1.11 1.2
246			1.5 1.12 1.3
247			1.6 1.13 1.4
248			1.7 1.1 1.14 1.5
249			1.8 1.2 1.15 1.6
250			1.1 1.9 1.3 1.16 1.7
251			---1.2---------1.10--------1.4---------1.17--------1.8----->
252			1.3 1.11 1.5 1.17 1.9
253			1.6 1.17 1.10
254
255	tdb	1.5	Tagging is actually remarkably easy to do. All you do is
256			issue a single command to tag the files at the current point
257			in time. You should make sure all development stops whilst
258			you do it, otherwise a bit of new code could sneak in.
259	tdb	1.1	Here's how to do it;
260
261			cvs tag public-release_1
262
263	tdb	1.5	This would mark the files with the tag "public-release_1".
264			You can then continue with developement, knowing that all
265			those files can easily be retrieved. It's again suprisingly
266			easy to do. Instead of typing "cvs checkout source" you
267	tdb	1.1	would type;
268
269			cvs checkout -r public-release_1 source
270
271	tdb	1.5	Which would checkout the source module at the point which
272			you tagged. Alternatively the following would update (or
273	tdb	1.1	downdate ?) your working copy to the tagged point;
274
275			cvs update -r public-release_1
276
277	tdb	1.5	Finally, a quick mention of why this would be useful.
278			Imagine the development team was split into two groups, one
279			working on coding, another working on testing. When the
280			coding group have finished "release 1" they can tag it and
281			carry on developing for "release 2". At the same time, the
282			testing team can checkout "release 1" and test it, reporting
283			bugs back to the coding team for fixing in "release 2". It
284			could also mean the a customer could still get hold of the
285	tdb	1.1	first release whilst you're busy coding for the second.
286
287			Branching in CVS
288			----------------
289	tdb	1.5	So far I've only talked about a single CVS branch, the
290			trunk. There is only ever one "current" revision of each
291			file, and everyone is working on the same files. However, it
292			is possible to branch this out into more than one copy of
293			the same files. A good example of why this is useful is
294	tdb	1.1	continuing the idea at the end of the last section.
295
296	tdb	1.5	Imagine the coding team are now busy working on "release 2"
297			and the testing team come up with a major flaw in
298			the older "release 1". Customers have already got this
299			version installed, so it needs fixing straight away. The
300			trick is to make a branch at the point where "release 1" was
301			tagged, and then fix the bugs on this branch. This branch
302			need not carry on, it could just have the few bugs fixed,
303			whilst the main branch (the trunk) has development of
304	tdb	1.1	"release 2" carrying on. This diagram shows this;
305
306			\|
307			\| -- tag "release_1"
308			\|\
309			\| \
310			\| \|
311			\| \|
312			\| - -- tag "release_1-fixed"
313			\|
314			\|
315			\| -- tag "release_2"
316
317	tdb	1.5	As you can see the customer could then get a copy of
318			"release_1-fixed" and not worry about the unstable code in
319	tdb	1.1	"release_2".
320
321	tdb	1.5	Branches can get much more complicated than this, but it's
322			beyond the scope of our requirements. Further info can be
323	tdb	1.1	found on the web.
324
325			Keyword Expansion
326			-----------------
327	tdb	1.5	CVS allows you to put certain keywords into a file which CVS
328			will expand when you check files in and out of the
329			repository. There are quite a few, and they're all pretty
330	tdb	1.1	useful in places. Here's a quick summary;
331
332			$Author$
333			The author of the latest change.
334			eg. $Author: tdb1 $
335
336			$Date$
337			The date/time of the latest change.
338			eg. $Date: 2000/10/30 13:10:04 $
339
340			$Header$
341			Various useful bits of information.
342			eg. $Header: /usr/local/proj/co600_10/cvs/file.txt,v \
343			1.1 2000/10/30 13:00:00 tdb1 Exp tdb1 $
344
345			$Id$
346			Simliar to $Header$, but without that wieldy path.
347			eg.
348			$Id: cvs-2.txt,v 1.3 2000/10/30 13:10:04 tdb1 Exp $
349
350			$Log$
351			Puts the latest log message in.
352
353			$Locker$
354			Name of the person who has a lock (usually no-one).
355			eg. $Locker: tdb1 $
356
357			$Name$
358			Name of the tag.
359			eg. $Name: release_1 $
360
361			$RCSfile$
362			Name of the RCS file.
363			eg. $RCSfile: cvs-2.txt,v $
364
365			$Revision$
366			Revision number of the file.
367			eg. $Revision: 1.3 $
368
369			$Source$
370			Full path to the file in the repository.
371			eg. $Source: /usr/local/proj/co600_10/cvs/file.txt,v $
372
373			$State$
374			State of the file (?).
375			eg. $State: Exp $
376
377	tdb	1.5	The keywords are automatically replaced by CVS, even if it's
378	tdb	1.1	already been expanded. You just put it in and leave it be!
379
380			Online CVS Resources
381			--------------------
382	tdb	1.5	That about concludes my guide on the basics of CVS for the
383			development work in the project. However, further resources
384			can be found on the following webpage. I've learnt an awful
385			lot from this "online book", and I'd recommend it to anyone
386	tdb	1.1	wanting to get to grips with CVS.
387
388			http://cvsbook.red-bean.com
389
390			Also, the "home" of CVS, if there is such a thing.
391
392			http://www.cvshome.org
393
394			About
395			-----
396	tdb	1.6	This document was written by Tim Bishop [tdb@i-scream.org] for
397	tdb	1.5	use by the team working on a 3rd year Computer Science
398			project called "i-scream". More details can be found on the
399	tdb	1.1	project website;
400
401	tdb	1.6	http://www.i-scream.org