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