ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/papers/cvs-1.txt
Revision: 1.1
Committed: Wed Oct 25 18:17:22 2000 UTC (24 years ago) by tdb
Content type: text/plain
Branch: MAIN
Log Message:
First paper outlining the need for CVS and how to use it in relation
to our project. Covers basic guide to CVS (on Unix), and how to setup
CVS to use our repository under Unix, Windows, and offsite.

File Contents

# Content
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.