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