--- projects/cms/documentation/papers/cvs-2.txt 2000/11/16 20:18:17 1.4 +++ projects/cms/documentation/papers/cvs-2.txt 2000/11/26 18:22:52 1.5 @@ -6,14 +6,14 @@ 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 + + - See "Using CVS (part 1)" for basic information on setting up and using CVS at UKC. tdb1, 29/10/00. @@ -22,22 +22,22 @@ 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 +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 +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 +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 = @@ -47,163 +47,163 @@ CVS_RSH = 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 +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" +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 raptor" into a command window and log -straight in without the need for a password. If not, +Now, we're pretty much all set. You should be able to type +"ssh -l 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 +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 +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 / +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 +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 +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 +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 +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 + "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 ' on NT' - - make sure you change for your userid, and that you - notice the difference between the single quote ' and the - double quotes ". + + make sure you change 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 + - 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 + - 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 + + 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 +Now, to test this setup you should try the following from a command prompt (on your machine, not raptor); ssh -l raptor.ukc.ac.uk -If everything has completed successfully you should now be -looking at a raptor prompt. If not... then work out why not! +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 +Right, now on to WinCVS. This is now a doddle. In the preferences set the CVSROOT to; :ext:@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" +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 +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 +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" +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 +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 +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 +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 -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 +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 +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 +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 @@ -226,8 +226,8 @@ easily pull out each file at "release 1". \ 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 +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 @@ -252,55 +252,55 @@ get the following effect which even more clearly shows 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. +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 +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 +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 +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 +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 +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; | @@ -314,19 +314,19 @@ whilst the main branch (the trunk) has development of | | -- 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 +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 +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 +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$ @@ -374,15 +374,15 @@ $State$ State of the file (?). eg. $State: Exp $ -The keywords are automatically replaced by CVS, even if it's +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 +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 @@ -393,9 +393,9 @@ 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 +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