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)
   
 - 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 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.

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