i-scream documentation viewer
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
