documentation/papers/cvs-2.txt

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

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