ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/papers/cvs-1.txt
Revision: 1.4
Committed: Sun Aug 1 10:39:54 2004 UTC (19 years, 11 months ago) by tdb
Content type: text/plain
Branch: MAIN
CVS Tags: HEAD
Changes since 1.3: +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 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