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 |