| 1 |
Using CVS (part 1) |
| 2 |
================== |
| 3 |
|
| 4 |
Contents |
| 5 |
-------- |
| 6 |
- Overview |
| 7 |
- CVS Repository Structure |
| 8 |
- Setting up CVS on Raptor |
| 9 |
- Setting up CVS on a Public PC (with WinCVS) |
| 10 |
- Setting up CVS from off campus |
| 11 |
- How to use CVS |
| 12 |
|
| 13 |
- See "Using CVS (part 2)" for information on binaries, |
| 14 |
branching, tagging and keywords. |
| 15 |
|
| 16 |
tdb1, 18/10/2000 |
| 17 |
|
| 18 |
Overview |
| 19 |
-------- |
| 20 |
CVS means "Concurrent Versioning System" and is used to keep |
| 21 |
version control on plain text files - usually source code, |
| 22 |
or html, but can be anything that has a plain text |
| 23 |
structure. It can store binaries, but doesn't offer the |
| 24 |
same version comparison features for obvious reasons. |
| 25 |
|
| 26 |
CVS also offers many features for group working, and doesn't |
| 27 |
lock the files when someone starts editing them. Instead it |
| 28 |
works by each user having their own "checked out" local copy |
| 29 |
of the source code (or a portion of it). The user then works |
| 30 |
on this code until they are happy with it, then runs an |
| 31 |
update command. This checks to see if someone else has |
| 32 |
updated the version in the repository, and if so brings |
| 33 |
their changes down into the users local copy. This can cause |
| 34 |
conflicts if both users change the same bit, but this |
| 35 |
shouldn't really happen - unless group communication is |
| 36 |
lacking. CVS will do it's best to merge these new changes |
| 37 |
in, but occasionaly it will need help from the user. This is |
| 38 |
just a case of reviewing the file with conflicts and |
| 39 |
manually resolving them. When CVS is happy that any updates |
| 40 |
in the repository have been merged it will allow a commit. |
| 41 |
This puts the users changes into the repository for all to |
| 42 |
access. |
| 43 |
|
| 44 |
In essence, that's CVS. Checkout, update, commit. That's all |
| 45 |
there really is to it. |
| 46 |
|
| 47 |
I think CVS would be very beneficial in writing the code for |
| 48 |
our project for two reasons. Firstly CVS will help us to |
| 49 |
maintain a control on all of our code for QA purposes, and |
| 50 |
make it easy for us to keep track of our "phases". We can |
| 51 |
tag the code at the end of each phase, and then continue |
| 52 |
development. At the same time, another group member could be |
| 53 |
testing the code at the tagged point. Finally, the group |
| 54 |
work features make it ideal for this situation. |
| 55 |
|
| 56 |
CVS Repository Structure |
| 57 |
------------------------ |
| 58 |
I am proposing the following structure for the CVS |
| 59 |
Repository. I suggest that we keep it the same from the word |
| 60 |
go, although we can add more into the hierachy it's not |
| 61 |
usually a good idea to move things around. |
| 62 |
|
| 63 |
ROOT |
| 64 |
documentation |
| 65 |
minutes |
| 66 |
misc |
| 67 |
papers |
| 68 |
plan |
| 69 |
presentation |
| 70 |
specification |
| 71 |
user |
| 72 |
experimental |
| 73 |
client |
| 74 |
host |
| 75 |
misc |
| 76 |
server |
| 77 |
misc |
| 78 |
source |
| 79 |
client |
| 80 |
host |
| 81 |
misc |
| 82 |
server |
| 83 |
web |
| 84 |
client |
| 85 |
website |
| 86 |
cgi-bin |
| 87 |
www |
| 88 |
|
| 89 |
We may need to expand that a bit, but it's a start. |
| 90 |
|
| 91 |
Setting up CVS on Raptor |
| 92 |
------------------------ |
| 93 |
Setting up CVS on raptor to use our "repository" takes a bit |
| 94 |
of effort. This is because the cs-sysadmin guys have been |
| 95 |
setting up CVS to run from marble, but it's not ready yet. |
| 96 |
All we have to do is override some of their default |
| 97 |
environment variables. Right, so add the following lines to |
| 98 |
your .cshrc file (presuming you are using csh, which I think |
| 99 |
you are). |
| 100 |
|
| 101 |
unsetenv CVSROOT |
| 102 |
unsetenv CVSREAD |
| 103 |
unsetenv CVS_RSH |
| 104 |
unsetenv CVSIGNORE |
| 105 |
setenv CVSROOT /usr/local/proj/co600_10/cvs |
| 106 |
|
| 107 |
A quick explanation of what this actually means. Firstly the |
| 108 |
CVSROOT is the root directory of the CVS repository. I've |
| 109 |
set it up as a directory called 'cvs' in our project space. |
| 110 |
Next the CVS_RSH variable tells CVS to use something like |
| 111 |
SSH, which we don't need to do locally. CVSREAD makes CVS |
| 112 |
mark the files it checks-out be read-only, which is meant to |
| 113 |
make you use the cvs edit command... but it's just a |
| 114 |
complete pain in the arse. Last of all CVSIGNORE tells CVS |
| 115 |
not to add certain files, but I think we've got enough sense |
| 116 |
to be able to do that ourselves... but by all means leave |
| 117 |
that line out if you feel happier. |
| 118 |
|
| 119 |
Setting up CVS on a Public PC (with WinCVS) |
| 120 |
------------------------------------------- |
| 121 |
WinCVS is (obviously) a Windows frontend to CVS. The command |
| 122 |
line thing is far easier to use if you're doing stuff |
| 123 |
directly on raptor (or any other unix box), but under |
| 124 |
windows it's nice to be able to get at files much more |
| 125 |
easily. It's also got the familiar "point-n-click" style |
| 126 |
interface, but I personally find that confusing. |
| 127 |
|
| 128 |
WinCVS can be found at the following location; |
| 129 |
|
| 130 |
\\drogo\packages\gnu\wincvs\wincvs.exe |
| 131 |
|
| 132 |
It's not under Install Packages, so you might want to make |
| 133 |
your own shortcut on the desktop, which is what I've done. |
| 134 |
|
| 135 |
Setting up is easy. First map a drive to \\raptor\grproj (go |
| 136 |
for grproj to help keep the permissions happy). Then when |
| 137 |
the preferences pop up bung in m:\co600_10\cvs (assuming you |
| 138 |
used m: like I did...) and select "Local mounted directory" |
| 139 |
under Authentication. The only other bits to change are |
| 140 |
unticking the "Checkout read-only" under Globals (it's just |
| 141 |
a damn pain), and under WinCVS you might want to change the |
| 142 |
"HOME folder" to your Z: drive. |
| 143 |
|
| 144 |
Then you're ready to go with doing usual CVS stuff. Oh, it |
| 145 |
took me ages to figure how to change which drive/directory |
| 146 |
is viewed in the main windows... it's hidden at the bottom |
| 147 |
of the View menu. |
| 148 |
|
| 149 |
Finally, it might be possible to get it working with SSH |
| 150 |
straight onto raptor, but I'm not sure of the exact process, |
| 151 |
and even if it'll work. I may add this as an errata in part2 |
| 152 |
of this documentation. |
| 153 |
|
| 154 |
Setting up CVS from off campus |
| 155 |
------------------------------ |
| 156 |
Using CVS from off campus is much trickier. We have no |
| 157 |
"proper" CVS facilities on raptor for remote access (it can |
| 158 |
run a server specifically for this task). However, as the |
| 159 |
command line CVS will make use of SSH we can connect through |
| 160 |
the firewall. This is fine if you have a Unix box at home, |
| 161 |
but I'm not sure (again) if this will work from Windows. |
| 162 |
|
| 163 |
From any Unix box (that has SSH and CVS installed) you just |
| 164 |
need to setup the following environment variables. These are |
| 165 |
best put in a file such as .cshrc (for the csh shell). |
| 166 |
|
| 167 |
CVS_RSH = |
| 168 |
ssh |
| 169 |
CVSROOT = |
| 170 |
:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs |
| 171 |
|
| 172 |
Every shell has it's own way of setting up environment |
| 173 |
variables, for example csh using the setenv command. Consult |
| 174 |
the man pages for more details. |
| 175 |
|
| 176 |
With this done you can use the command line facilities as |
| 177 |
usual, and you will be prompted for your raptor password |
| 178 |
each time a connection is made. |
| 179 |
|
| 180 |
How to use CVS |
| 181 |
-------------- |
| 182 |
There are three main CVS operations that you'll use on a |
| 183 |
regular basis; checkout, update and commit. Then there's the |
| 184 |
smaller commands such as add, delete, and export. I'll |
| 185 |
describe them, then give an example. This all assumes you've |
| 186 |
setup the CVSROOT environment variable as described above. |
| 187 |
|
| 188 |
These commands are for the command line version of CVS, but |
| 189 |
the ideas can be applied to any version, including WinCVS. |
| 190 |
|
| 191 |
A full list of commands can be found by typing; |
| 192 |
|
| 193 |
cvs --help-commands |
| 194 |
|
| 195 |
A quick mention of the version numbers first. Each file has |
| 196 |
a unique version number starting at 1.1 and incrementing to |
| 197 |
1.2, 1.3 and so on. It never becomes 2.x, unless you |
| 198 |
manually change it. These version numbers are independant |
| 199 |
for every single file, and have no overall bearing on any |
| 200 |
"release versions" that go out to the public. |
| 201 |
|
| 202 |
Firstly, the 'checkout' command. This extracts a copy of a |
| 203 |
section of the CVS Repository to a local working copy. All |
| 204 |
work (editing) is then carried out on this local copy. The |
| 205 |
local copy can be changed, completely deleted, or |
| 206 |
whatever... it'll have no effect on the database. The |
| 207 |
command has the following format; |
| 208 |
|
| 209 |
cvs checkout <module> |
| 210 |
|
| 211 |
eg. |
| 212 |
|
| 213 |
cvs checkout source/server |
| 214 |
|
| 215 |
This would extract a copy of all the files in server/source |
| 216 |
and all subdirectories below this. Note that CVS control |
| 217 |
files will be created in 'CVS' subdirectories all over the |
| 218 |
place, they're best ignored. |
| 219 |
|
| 220 |
Next the 'update' command. This command ensures that the |
| 221 |
local copy is up-to-date with the database. If the checkout |
| 222 |
was done a few days ago it's possible someone else may have |
| 223 |
updated something in the main repository since the original |
| 224 |
checkout. After issuing the update the local copy will be |
| 225 |
updated. The command is very simple; |
| 226 |
|
| 227 |
cvs update |
| 228 |
|
| 229 |
The exception to this is if the user has changed the local |
| 230 |
copy in some way. In this case the update still takes place, |
| 231 |
but any changes are merged into the local copy. No updates |
| 232 |
are sent to the repository, this is important to remember! |
| 233 |
This could of course cause problems if the update on the |
| 234 |
repository and the local update are on the same bit of code. |
| 235 |
Usually CVS can merge updates, but in this instance it will |
| 236 |
give a conflict error and the user will have to manually |
| 237 |
resolve them. This is a simple case of checking the code the |
| 238 |
problem areas will be marked out. After the conflicts have |
| 239 |
been resolved another update could be done to verify it's |
| 240 |
all OK. |
| 241 |
|
| 242 |
The update command also lets you know the state of files. If |
| 243 |
it puts an 'M' next to a file (when it lists them) it means |
| 244 |
you've modified it. If it's got a '?' it means the file is |
| 245 |
new or not part of the CVS (you have to add new files). A |
| 246 |
'C' means a conflicting file, and I think maybe 'A' means |
| 247 |
the file is scheduled to be added. There are probably |
| 248 |
others, check "man cvs" :) |
| 249 |
|
| 250 |
Right, the last main command is 'commit'. This puts local |
| 251 |
changes back into the repository and updates the version |
| 252 |
number. You should run an update first, though, and commit |
| 253 |
will complain if you haven't done when you need to. You will |
| 254 |
need to enter a comment, and it's good practice to describe |
| 255 |
roughly the reason for the commit - it helps keep a good |
| 256 |
audit trail, and lets other users know why you did what you |
| 257 |
did. In Unix it'll probably load up vi, which is ugly... I |
| 258 |
think if you change the EDITOR enviroment variable you can |
| 259 |
set it to use pico. The commit command is as easy as; |
| 260 |
|
| 261 |
cvs commit |
| 262 |
|
| 263 |
That's all there is to the everyday CVS commands. Next the |
| 264 |
occasional commands. Now on to the less used ones. |
| 265 |
|
| 266 |
Lets start with the 'add' command. Say you've done a |
| 267 |
checkout of source/server and you've added a file called |
| 268 |
main.java into the directory. Now lets add it to the |
| 269 |
repository. |
| 270 |
|
| 271 |
cd source/server |
| 272 |
cvs add main.java |
| 273 |
|
| 274 |
The add command will tell you that it's scheduled to be |
| 275 |
added at the next commit. Simply run an update then commit |
| 276 |
for the file to be added. |
| 277 |
|
| 278 |
The 'remove' command works in a similar way I think. I'm not |
| 279 |
sure whether you have to delete the file first, you'll have |
| 280 |
to try it. Again you'll need to update then commit. A note |
| 281 |
about deleted. The file obviously won't be deleted |
| 282 |
completely, that would defeat the point in a versioning |
| 283 |
system. Instead it's moved to an Attic subdirectory in the |
| 284 |
CVS so you can still review it's revisions in the future, |
| 285 |
and even resurrect it. |
| 286 |
|
| 287 |
Next there's the 'release' command. This is used as a tidy |
| 288 |
way of cleaning up the local files when you've finished with |
| 289 |
them. To remove the above example you'd do the following; |
| 290 |
|
| 291 |
cvs release source/server |
| 292 |
|
| 293 |
This will ensure that you don't accidently delete any local |
| 294 |
changes by informing you first of any non-commited files. If |
| 295 |
you add the -d switch it will actually delete the files too; |
| 296 |
|
| 297 |
cvs release -d source/server |
| 298 |
|
| 299 |
This is much safer than typing "rm..." :) |
| 300 |
|
| 301 |
Finally, the 'export' command. This has almost the same |
| 302 |
effect as the checkout command, but it doesn't create any of |
| 303 |
the CVS control files. The aim of this command is to extract |
| 304 |
sources for public release, so you can zip them up and send |
| 305 |
them out to the client. For example; |
| 306 |
|
| 307 |
cvs export source |
| 308 |
tar -cvf source.tar source |
| 309 |
gzip -v9 source.tar |
| 310 |
|
| 311 |
That's just about it for basic CVS. I'll probably produce |
| 312 |
another document on tagging at some point in the future. |
| 313 |
|
| 314 |
About |
| 315 |
----- |
| 316 |
This document was written by Tim Bishop [tdb@i-scream.org] for |
| 317 |
use by the team working on a 3rd year Computer Science |
| 318 |
project called "i-scream". More details can be found on the |
| 319 |
project website; |
| 320 |
|
| 321 |
http://www.i-scream.org |
