| 1 |
Using CVS (part 2) |
| 2 |
================== |
| 3 |
|
| 4 |
Contents |
| 5 |
-------- |
| 6 |
- Errata to "Using CVS (part 1)" |
| 7 |
- Setting up CVS on a Public PC (with WinCVS/SSH) |
| 8 |
- Setting up CVS off campus/SSB (with WinCVS/SSH) |
| 9 |
|
| 10 |
- How CVS handles binary files |
| 11 |
- Tagging the Repository |
| 12 |
- Branching in CVS |
| 13 |
- Keyword Expansion |
| 14 |
- Online CVS Resources |
| 15 |
|
| 16 |
- See "Using CVS (part 1)" for basic information on setting |
| 17 |
up and using CVS at UKC. |
| 18 |
|
| 19 |
tdb1, 29/10/00. |
| 20 |
|
| 21 |
Errata to "Using CVS (part 1)" |
| 22 |
------------------------------ |
| 23 |
Setting up CVS on a Public PC (with WinCVS/SSH) |
| 24 |
----------------------------------------------- |
| 25 |
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 |
on a normal SSB machine. |
| 30 |
|
| 31 |
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 |
remove the need for a password. |
| 36 |
|
| 37 |
[adapted from instructions given by jc] |
| 38 |
|
| 39 |
First thing is to setup a few environment variables. This is |
| 40 |
done in the System part of Control Panel. Under the User |
| 41 |
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 |
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 |
reads; |
| 57 |
|
| 58 |
set HOST=raptor |
| 59 |
|
| 60 |
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 |
to make it do it's stuff. |
| 64 |
|
| 65 |
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 |
something has gone wrong ! |
| 69 |
|
| 70 |
Finally, a quick alteration to WinCVS and we're done. In the |
| 71 |
preferences set the CVS Root to be; |
| 72 |
|
| 73 |
:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs |
| 74 |
|
| 75 |
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 |
much neater way of doing things. |
| 80 |
|
| 81 |
Setting up CVS off campus/SSB (with WinCVS/SSH) |
| 82 |
----------------------------------------------- |
| 83 |
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 |
Binaries" on the following page; |
| 87 |
|
| 88 |
http://www.wincvs.org/download.html |
| 89 |
|
| 90 |
Secondly you'll require SSH. I'm not sure where this package |
| 91 |
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 |
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 |
raptor. |
| 98 |
|
| 99 |
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 |
DLL's in place and the binary ssh files. |
| 103 |
|
| 104 |
Next, setting up a key. This requires a few straightforward |
| 105 |
steps. |
| 106 |
|
| 107 |
- setup a directory (on your machine) to be considered your |
| 108 |
"home folder" and then ensure that the environment |
| 109 |
variable HOME is pointed at this directory. Then make a |
| 110 |
directory called .ssh within this. |
| 111 |
|
| 112 |
- telnet into raptor and run this command; |
| 113 |
ssh-keygen -f ssh-newkey -q -P '' -C '<user> on NT' |
| 114 |
|
| 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 |
identity.pub respectively. |
| 122 |
|
| 123 |
- 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 |
following; |
| 127 |
cat ssh-newkey.pub >> .ssh/authorized_keys |
| 128 |
|
| 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 |
the ssh-newkey and ssh-newkey.pub files from raptor. |
| 132 |
|
| 133 |
Now, to test this setup you should try the following from a |
| 134 |
command prompt (on your machine, not raptor); |
| 135 |
|
| 136 |
ssh -l <userid> raptor.ukc.ac.uk |
| 137 |
|
| 138 |
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 |
|
| 142 |
Right, now on to WinCVS. This is now a doddle. In the |
| 143 |
preferences set the CVSROOT to; |
| 144 |
|
| 145 |
:ext:<user>@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs |
| 146 |
|
| 147 |
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 |
on the globals tab. |
| 153 |
|
| 154 |
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 |
should appear. |
| 158 |
|
| 159 |
As a final note, turning TCP/IP compression on may make it |
| 160 |
quicker over a modem. |
| 161 |
|
| 162 |
How CVS handles binary files |
| 163 |
---------------------------- |
| 164 |
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 |
between them, or allow you to view diffs between them. |
| 170 |
|
| 171 |
IMPORTANT: You must make sure you tell CVS that a file is |
| 172 |
binary, otherwise it will not store it correctly |
| 173 |
and the file will be corrupted. |
| 174 |
|
| 175 |
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 |
command that the file is binary. |
| 180 |
|
| 181 |
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 |
add" command. |
| 184 |
|
| 185 |
cvs add -kb <filename> |
| 186 |
|
| 187 |
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 |
text formats. |
| 192 |
|
| 193 |
Tagging the Repository |
| 194 |
---------------------- |
| 195 |
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 |
without the aid of tagging. |
| 202 |
|
| 203 |
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 |
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 |
In fact, if you imagine pulling this line straight, you'd |
| 230 |
get the following effect which even more clearly shows where |
| 231 |
"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 |
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 |
Here's how to do it; |
| 260 |
|
| 261 |
cvs tag public-release_1 |
| 262 |
|
| 263 |
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 |
would type; |
| 268 |
|
| 269 |
cvs checkout -r public-release_1 source |
| 270 |
|
| 271 |
Which would checkout the source module at the point which |
| 272 |
you tagged. Alternatively the following would update (or |
| 273 |
downdate ?) your working copy to the tagged point; |
| 274 |
|
| 275 |
cvs update -r public-release_1 |
| 276 |
|
| 277 |
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 |
first release whilst you're busy coding for the second. |
| 286 |
|
| 287 |
Branching in CVS |
| 288 |
---------------- |
| 289 |
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 |
continuing the idea at the end of the last section. |
| 295 |
|
| 296 |
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 |
"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 |
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 |
"release_2". |
| 320 |
|
| 321 |
Branches can get much more complicated than this, but it's |
| 322 |
beyond the scope of our requirements. Further info can be |
| 323 |
found on the web. |
| 324 |
|
| 325 |
Keyword Expansion |
| 326 |
----------------- |
| 327 |
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 |
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 |
The keywords are automatically replaced by CVS, even if it's |
| 378 |
already been expanded. You just put it in and leave it be! |
| 379 |
|
| 380 |
Online CVS Resources |
| 381 |
-------------------- |
| 382 |
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 |
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 |
This document was written by Tim Bishop [tdb@i-scream.org] for |
| 397 |
use by the team working on a 3rd year Computer Science |
| 398 |
project called "i-scream". More details can be found on the |
| 399 |
project website; |
| 400 |
|
| 401 |
http://www.i-scream.org |
