ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/papers/cvs-2.txt
Revision: 1.6
Committed: Sun Aug 1 10:39:54 2004 UTC (19 years, 8 months ago) by tdb
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Changes since 1.5: +2 -2 lines
Log Message:
Catch a lot of old URL's and update them. Also remove a couple of old files
that aren't used.

File Contents

# Content
1 Using CVS (part 2)
2 ==================
3
4 Contents
5 --------
6 - Errata to "Using CVS (part 1)"
7 - Setting up CVS on a Public PC (with WinCVS/SSH)
8 - Setting up CVS off campus/SSB (with WinCVS/SSH)
9
10 - How CVS handles binary files
11 - Tagging the Repository
12 - Branching in CVS
13 - Keyword Expansion
14 - Online CVS Resources
15
16 - See "Using CVS (part 1)" for basic information on setting
17 up and using CVS at UKC.
18
19 tdb1, 29/10/00.
20
21 Errata to "Using CVS (part 1)"
22 ------------------------------
23 Setting up CVS on a Public PC (with WinCVS/SSH)
24 -----------------------------------------------
25 Assuming you already have WinCVS working we just need to
26 make a few modifications to get the same thing working with
27 SSH. This will only work on a public PC, although with some
28 careful copying of files you might be able to get it to work
29 on a normal SSB machine.
30
31 Firstly we need to get SSH working. As it is SSH does work,
32 but it will keep prompting for a password, which is a pain
33 when it's hidden in a cmd window somewhere. We'll start by
34 tweaking the SSH setup, and then we'll setup a key pair to
35 remove the need for a password.
36
37 [adapted from instructions given by jc]
38
39 First thing is to setup a few environment variables. This is
40 done in the System part of Control Panel. Under the User
41 Variables section add the following;
42
43 HOME =
44 z:\username
45 CVS_RSH =
46 ssh
47 CVSROOT =
48 :ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
49
50 Next we need to go about setting up the key pair. This is
51 done by two batch files called getkey.bat and copy-key.bat
52 which are already on the public PC's. Unfortunately you need
53 to modify getkey.bat to make it work with raptor, so copy it
54 from the C: drive (c:\winnt\system32 I believe) to your
55 desktop (or anywhere else). Edit it so that the third line
56 reads;
57
58 set HOST=raptor
59
60 Then run it. You'll be prompted for your raptor password
61 three times, and then the key is setup. Next you need to run
62 copy-key.bat. Just go to "Start -> Run -> copy-key raptor"
63 to make it do it's stuff.
64
65 Now, we're pretty much all set. You should be able to type
66 "ssh -l <user> raptor" into a command window and log
67 straight in without the need for a password. If not,
68 something has gone wrong !
69
70 Finally, a quick alteration to WinCVS and we're done. In the
71 preferences set the CVS Root to be;
72
73 :ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
74
75 Then set the Authentication type to "SSH server". Assuming
76 you've already done the rest of the setup from the last
77 document you should be able to do a checkout as normal, but
78 this time without the need for a mapped drive - which is a
79 much neater way of doing things.
80
81 Setting up CVS off campus/SSB (with WinCVS/SSH)
82 -----------------------------------------------
83 To do this you'll need two packages. Firstly, and most
84 obviously WinCVS. The latest version of WinCVS (1.1b16) can
85 be downloaded from the "WinCvs 1.1 *BETA* / Client + Local /
86 Binaries" on the following page;
87
88 http://www.wincvs.org/download.html
89
90 Secondly you'll require SSH. I'm not sure where this package
91 orginated, but there is a current version on raptor at;
92
93 /usr/local/proj/co600_10/sshwin32/ssh-1.2.14-win32bin.zip
94
95 Armed with those two files you're ready to go. To get
96 started we need to get ssh installed, and a key setup with
97 raptor.
98
99 Installing ssh is easy. Simply extract the contents of the
100 zip file in to your windows\system32 directory (on
101 winnt/win2k - windows\system on win9x). This will put the
102 DLL's in place and the binary ssh files.
103
104 Next, setting up a key. This requires a few straightforward
105 steps.
106
107 - setup a directory (on your machine) to be considered your
108 "home folder" and then ensure that the environment
109 variable HOME is pointed at this directory. Then make a
110 directory called .ssh within this.
111
112 - telnet into raptor and run this command;
113 ssh-keygen -f ssh-newkey -q -P '' -C '<user> on NT'
114
115 make sure you change <user> for your userid, and that you
116 notice that there are *only* single quotes like this ' .
117
118 - using ftp (or by any other means) copy the files named
119 ssh-newkey and ssh-newkey.pub to the .ssh folder you made
120 on your machine. Now rename them to identity and
121 identity.pub respectively.
122
123 - Finally we need to get the contents of the identity.pub
124 file above into the file ~/.ssh/authorized_keys on
125 raptor. The easiest way to do this is to type the
126 following;
127 cat ssh-newkey.pub >> .ssh/authorized_keys
128
129 This assumes you didn't delete the ssh-newkey files, and
130 that you are in your home folder. Finally, you can delete
131 the ssh-newkey and ssh-newkey.pub files from raptor.
132
133 Now, to test this setup you should try the following from a
134 command prompt (on your machine, not raptor);
135
136 ssh -l <userid> raptor.ukc.ac.uk
137
138 If everything has completed successfully you should now be
139 looking at a raptor prompt. You should NOT have been asked
140 for a password ! If it went wrong... work out why!
141
142 Right, now on to WinCVS. This is now a doddle. In the
143 preferences set the CVSROOT to;
144
145 :ext:<user>@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
146
147 Set Authentication to SSH server, and set the RSA identity
148 to your identity file (not the .pub one). On the ports tab
149 check the "alternate rsh name" box at the bottom, and make
150 sure "ssh" is in the text box. You might also like to
151 uncheck "checkout read-only" and "prune empty directories"
152 on the globals tab.
153
154 Finally set the browser directory to a suitable location and
155 try checking something out. If all has worked an SSH window
156 should pop up at the bottom of the screen and the files
157 should appear.
158
159 As a final note, turning TCP/IP compression on may make it
160 quicker over a modem.
161
162 How CVS handles binary files
163 ----------------------------
164 Basically CVS can't do version management of binary files,
165 and quite obviously this is because it's not possible to
166 make version comparisons between two revisions in a logical
167 way. But, CVS will let you store binary files and will let
168 you add new versions. However, it will not store "changes"
169 between them, or allow you to view diffs between them.
170
171 IMPORTANT: You must make sure you tell CVS that a file is
172 binary, otherwise it will not store it correctly
173 and the file will be corrupted.
174
175 In WinCVS it's really easy to add a binary file, simply
176 select "Add selection binary" instead of the usual "Add
177 selection". WinCVS will display a "binary" icon instead, and
178 add "-kb" into the Option column. This -kb tells the CVS
179 command that the file is binary.
180
181 This leads nicely into how to do it from the command line.
182 You simply type the following in place of the usual "cvs
183 add" command.
184
185 cvs add -kb <filename>
186
187 Again, the -kb is present. Now, a quick explanation of what
188 this "-kb" means. Basically it is telling CVS not to do
189 keyword expansion (turning $Revision$ into $Revision: 1.3 $)
190 and tell is not to attempt to convert between unix/windows
191 text formats.
192
193 Tagging the Repository
194 ----------------------
195 Tagging the repository is a way of "marking" all the files
196 at a particular point in time. For example, when "release 1"
197 is finished you might want to mark this in the history of
198 all the files, so you can easily come back to it in the
199 future. As every file the makes up "release 1" may be on a
200 different individual revision, it would be tedious to do
201 without the aid of tagging.
202
203 This is the best example I've seen that clearly shows how a
204 tag is implemented. Imagine the dotted line signfies the
205 point at which you declared the files were "release 1". As
206 you can see, work as continued on the files, but you could
207 easily pull out each file at "release 1".
208
209 File A File B File C File D File E
210 ------ ------ ------ ------ ------
211 1.1 1.1 1.1 1.1 1.1
212 ---1.2-. 1.2 1.2 1.2 1.2
213 1.3 | 1.3 1.3 1.3 1.3
214 \ 1.4 .-1.4-. 1.4 1.4
215 \ 1.5 / 1.5 \ 1.5 1.5
216 \ 1.6 / 1.6 | 1.6 1.6
217 \ 1.7 / | 1.7 1.7
218 \ 1.8 / | 1.8 .-1.8----->
219 \ 1.9 / | 1.9 / 1.9
220 `1.10' | 1.10 / 1.10
221 1.11 | 1.11 |
222 | 1.12 |
223 | 1.13 |
224 \ 1.14 |
225 \ 1.15 /
226 \ 1.16 /
227 `-1.17-'
228
229 In fact, if you imagine pulling this line straight, you'd
230 get the following effect which even more clearly shows where
231 "release 1" is.
232
233 File A File B File C File D File E
234 ------ ------ ------ ------ ------
235 1.1
236 1.2
237 1.3
238 1.4
239 1.5
240 1.6
241 1.7
242 1.1 1.8
243 1.2 1.9
244 1.3 1.10 1.1
245 1.4 1.11 1.2
246 1.5 1.12 1.3
247 1.6 1.13 1.4
248 1.7 1.1 1.14 1.5
249 1.8 1.2 1.15 1.6
250 1.1 1.9 1.3 1.16 1.7
251 ---1.2---------1.10--------1.4---------1.17--------1.8----->
252 1.3 1.11 1.5 1.17 1.9
253 1.6 1.17 1.10
254
255 Tagging is actually remarkably easy to do. All you do is
256 issue a single command to tag the files at the current point
257 in time. You should make sure all development stops whilst
258 you do it, otherwise a bit of new code could sneak in.
259 Here's how to do it;
260
261 cvs tag public-release_1
262
263 This would mark the files with the tag "public-release_1".
264 You can then continue with developement, knowing that all
265 those files can easily be retrieved. It's again suprisingly
266 easy to do. Instead of typing "cvs checkout source" you
267 would type;
268
269 cvs checkout -r public-release_1 source
270
271 Which would checkout the source module at the point which
272 you tagged. Alternatively the following would update (or
273 downdate ?) your working copy to the tagged point;
274
275 cvs update -r public-release_1
276
277 Finally, a quick mention of why this would be useful.
278 Imagine the development team was split into two groups, one
279 working on coding, another working on testing. When the
280 coding group have finished "release 1" they can tag it and
281 carry on developing for "release 2". At the same time, the
282 testing team can checkout "release 1" and test it, reporting
283 bugs back to the coding team for fixing in "release 2". It
284 could also mean the a customer could still get hold of the
285 first release whilst you're busy coding for the second.
286
287 Branching in CVS
288 ----------------
289 So far I've only talked about a single CVS branch, the
290 trunk. There is only ever one "current" revision of each
291 file, and everyone is working on the same files. However, it
292 is possible to branch this out into more than one copy of
293 the same files. A good example of why this is useful is
294 continuing the idea at the end of the last section.
295
296 Imagine the coding team are now busy working on "release 2"
297 and the testing team come up with a major flaw in
298 the older "release 1". Customers have already got this
299 version installed, so it needs fixing straight away. The
300 trick is to make a branch at the point where "release 1" was
301 tagged, and then fix the bugs on this branch. This branch
302 need not carry on, it could just have the few bugs fixed,
303 whilst the main branch (the trunk) has development of
304 "release 2" carrying on. This diagram shows this;
305
306 |
307 | -- tag "release_1"
308 |\
309 | \
310 | |
311 | |
312 | - -- tag "release_1-fixed"
313 |
314 |
315 | -- tag "release_2"
316
317 As you can see the customer could then get a copy of
318 "release_1-fixed" and not worry about the unstable code in
319 "release_2".
320
321 Branches can get much more complicated than this, but it's
322 beyond the scope of our requirements. Further info can be
323 found on the web.
324
325 Keyword Expansion
326 -----------------
327 CVS allows you to put certain keywords into a file which CVS
328 will expand when you check files in and out of the
329 repository. There are quite a few, and they're all pretty
330 useful in places. Here's a quick summary;
331
332 $Author$
333 The author of the latest change.
334 eg. $Author: tdb1 $
335
336 $Date$
337 The date/time of the latest change.
338 eg. $Date: 2000/10/30 13:10:04 $
339
340 $Header$
341 Various useful bits of information.
342 eg. $Header: /usr/local/proj/co600_10/cvs/file.txt,v \
343 1.1 2000/10/30 13:00:00 tdb1 Exp tdb1 $
344
345 $Id$
346 Simliar to $Header$, but without that wieldy path.
347 eg.
348 $Id: cvs-2.txt,v 1.3 2000/10/30 13:10:04 tdb1 Exp $
349
350 $Log$
351 Puts the latest log message in.
352
353 $Locker$
354 Name of the person who has a lock (usually no-one).
355 eg. $Locker: tdb1 $
356
357 $Name$
358 Name of the tag.
359 eg. $Name: release_1 $
360
361 $RCSfile$
362 Name of the RCS file.
363 eg. $RCSfile: cvs-2.txt,v $
364
365 $Revision$
366 Revision number of the file.
367 eg. $Revision: 1.3 $
368
369 $Source$
370 Full path to the file in the repository.
371 eg. $Source: /usr/local/proj/co600_10/cvs/file.txt,v $
372
373 $State$
374 State of the file (?).
375 eg. $State: Exp $
376
377 The keywords are automatically replaced by CVS, even if it's
378 already been expanded. You just put it in and leave it be!
379
380 Online CVS Resources
381 --------------------
382 That about concludes my guide on the basics of CVS for the
383 development work in the project. However, further resources
384 can be found on the following webpage. I've learnt an awful
385 lot from this "online book", and I'd recommend it to anyone
386 wanting to get to grips with CVS.
387
388 http://cvsbook.red-bean.com
389
390 Also, the "home" of CVS, if there is such a thing.
391
392 http://www.cvshome.org
393
394 About
395 -----
396 This document was written by Tim Bishop [tdb@i-scream.org] for
397 use by the team working on a 3rd year Computer Science
398 project called "i-scream". More details can be found on the
399 project website;
400
401 http://www.i-scream.org