documentation/papers/cvs-1.txt

Using CVS (part 1)
==================

tdb1, 18/10/2000

Overview
--------
CVS means "Concurrent Versioning System" and is used to keep
version control on plain text files - usually source code,
or html, but can be anything that has a plain text 
structure. It can store binaries, but doesn't offer the 
same version comparison features for obvious reasons.

CVS also offers many features for group working, and doesn't
lock the files when someone starts editing them. Instead it
works by each user having their own "checked out" local copy
of the source code (or a portion of it). The user then works
on this code until they are happy with it, then runs an
update command. This checks to see if someone else has
updated the version in the repository, and if so brings
their changes down into the users local copy. This can cause
conflicts if both users change the same bit, but this
shouldn't really happen - unless group communication is
lacking. CVS will do it's best to merge these new changes
in, but occasionaly it will need help from the user. This is
just a case of reviewing the file with conflicts and
manually resolving them. When CVS is happy that any updates
in the repository have been merged it will allow a commit.
This puts the users changes into the repository for all to
access.

In essence, that's CVS. Checkout, update, commit. That's all
there really is to it.

I think CVS would be very beneficial in writing the code for
our project for two reasons. Firstly CVS will help us to
maintain a control on all of our code for QA purposes, and
make it easy for us to keep track of our "phases". We can
tag the code at the end of each phase, and then continue
development. At the same time, another group member could be
testing the code at the tagged point. Finally, the group
work features make it ideal for this situation.

CVS Repository Structure
------------------------
I am proposing the following structure for the CVS
Repository. I suggest that we keep it the same from the word
go, although we can add more into the hierachy it's not
usually a good idea to move things around.

ROOT
  documentation
    minutes
    misc
    papers
    plan
    presentation
    specification
    user
  experimental
    client
    host
    misc
    server
  misc
  source
    client
    host
    misc
    server
  web
    client
    website
      cgi-bin
      www

We may need to expand that a bit, but it's a start.

Setting up CVS on Raptor
------------------------
Setting up CVS on raptor to use our "repository" takes a bit
of effort. This is because the cs-sysadmin guys have been
setting up CVS to run from marble, but it's not ready yet.
All we have to do is override some of their default
environment variables. Right, so add the following lines to
your .cshrc file (presuming you are using csh, which I think
you are).

unsetenv CVSROOT
unsetenv CVSREAD
unsetenv CVS_RSH
unsetenv CVSIGNORE
setenv CVSROOT /usr/local/proj/co600_10/cvs

A quick explanation of what this actually means. Firstly the
CVSROOT is the root directory of the CVS repository. I've
set it up as a directory called 'cvs' in our project space.
Next the CVS_RSH variable tells CVS to use something like
SSH, which we don't need to do locally. CVSREAD makes CVS
mark the files it checks-out be read-only, which is meant to
make you use the cvs edit command... but it's just a
complete pain in the arse. Last of all CVSIGNORE tells CVS
not to add certain files, but I think we've got enough sense
to be able to do that ourselves... but by all means leave
that line out if you feel happier.

Setting up CVS on a Public PC (with WinCVS)
-------------------------------------------
WinCVS is (obviously) a Windows frontend to CVS. The command
line thing is far easier to use if you're doing stuff
directly on raptor (or any other unix box), but under
windows it's nice to be able to get at files much more
easily. It's also got the familiar "point-n-click" style
interface, but I personally find that confusing.

WinCVS can be found at the following location;

\\drogo\packages\gnu\wincvs\wincvs.exe

It's not under Install Packages, so you might want to make
your own shortcut on the desktop, which is what I've done.

Setting up is easy. First map a drive to \\raptor\grproj (go
for grproj to help keep the permissions happy). Then when
the preferences pop up bung in m:\co600_10\cvs (assuming you
used m: like I did...) and select "Local mounted directory"
under Authentication. The only other bits to change are
unticking the "Checkout read-only" under Globals (it's just
a damn pain), and under WinCVS you might want to change the
"HOME folder" to your Z: drive.

Then you're ready to go with doing usual CVS stuff. Oh, it
took me ages to figure how to change which drive/directory
is viewed in the main windows... it's hidden at the bottom
of the View menu.

Finally, it might be possible to get it working with SSH
straight onto raptor, but I'm not sure of the exact process,
and even if it'll work. I may add this as an errata in part2 
of this documentation.

Setting up CVS from off campus
------------------------------
Using CVS from off campus is much trickier. We have no
"proper" CVS facilities on raptor for remote access (it can
run a server specifically for this task). However, as the
command line CVS will make use of SSH we can connect through
the firewall. This is fine if you have a Unix box at home,
but I'm not sure (again) if this will work from Windows.

From any Unix box (that has SSH and CVS installed) you just 
need to setup the following environment variables. These are 
best put in a file such as .cshrc (for the csh shell).

CVS_RSH =
     ssh
CVSROOT =
     :ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs

Every shell has it's own way of setting up environment 
variables, for example csh using the setenv command. Consult 
the man pages for more details.

With this done you can use the command line facilities as 
usual, and you will be prompted for your raptor password 
each time a connection is made.

How to use CVS
--------------
There are three main CVS operations that you'll use on a
regular basis; checkout, update and commit. Then there's the
smaller commands such as add, delete, and export. I'll
describe them, then give an example. This all assumes you've
setup the CVSROOT environment variable as described above.

These commands are for the command line version of CVS, but 
the ideas can be applied to any version, including WinCVS.

A full list of commands can be found by typing;

cvs --help-commands

A quick mention of the version numbers first. Each file has
a unique version number starting at 1.1 and incrementing to
1.2, 1.3 and so on. It never becomes 2.x, unless you
manually change it. These version numbers are independant
for every single file, and have no overall bearing on any
"release versions" that go out to the public.

Firstly, the 'checkout' command. This extracts a copy of a
section of the CVS Repository to a local working copy. All
work (editing) is then carried out on this local copy. The
local copy can be changed, completely deleted, or
whatever... it'll have no effect on the database. The
command has the following format;

cvs checkout <module>

eg.

cvs checkout source/server

This would extract a copy of all the files in server/source
and all subdirectories below this. Note that CVS control
files will be created in 'CVS' subdirectories all over the
place, they're best ignored.

Next the 'update' command. This command ensures that the
local copy is up-to-date with the database. If the checkout
was done a few days ago it's possible someone else may have
updated something in the main repository since the original
checkout. After issuing the update the local copy will be
updated. The command is very simple;

cvs update

The exception to this is if the user has changed the local
copy in some way. In this case the update still takes place,
but any changes are merged into the local copy. No updates
are sent to the repository, this is important to remember!
This could of course cause problems if the update on the
repository and the local update are on the same bit of code.
Usually CVS can merge updates, but in this instance it will
give a conflict error and the user will have to manually
resolve them. This is a simple case of checking the code the
problem areas will be marked out. After the conflicts have
been resolved another update could be done to verify it's
all OK.

The update command also lets you know the state of files. If
it puts an 'M' next to a file (when it lists them) it means
you've modified it. If it's got a '?' it means the file is
new or not part of the CVS (you have to add new files). A
'C' means a conflicting file, and I think maybe 'A' means
the file is scheduled to be added. There are probably
others, check "man cvs" :)

Right, the last main command is 'commit'. This puts local
changes back into the repository and updates the version
number. You should run an update first, though, and commit
will complain if you haven't done when you need to. You will
need to enter a comment, and it's good practice to describe
roughly the reason for the commit - it helps keep a good
audit trail, and lets other users know why you did what you
did. In Unix it'll probably load up vi, which is ugly... I
think if you change the EDITOR enviroment variable you can
set it to use pico. The commit command is as easy as;

cvs commit

That's all there is to the everyday CVS commands. Next the
occasional commands. Now on to the less used ones.

Lets start with the 'add' command. Say you've done a
checkout of source/server and you've added a file called
main.java into the directory. Now lets add it to the
repository.

cd source/server
cvs add main.java

The add command will tell you that it's scheduled to be
added at the next commit. Simply run an update then commit
for the file to be added.

The 'remove' command works in a similar way I think. I'm not
sure whether you have to delete the file first, you'll have
to try it. Again you'll need to update then commit. A note
about deleted. The file obviously won't be deleted
completely, that would defeat the point in a versioning
system. Instead it's moved to an Attic subdirectory in the
CVS so you can still review it's revisions in the future,
and even resurrect it.

Next there's the 'release' command. This is used as a tidy
way of cleaning up the local files when you've finished with
them. To remove the above example you'd do the following;

cvs release source/server

This will ensure that you don't accidently delete any local
changes by informing you first of any non-commited files. If
you add the -d switch it will actually delete the files too;

cvs release -d source/server

This is much safer than typing "rm..." :)

Finally, the 'export' command. This has almost the same
effect as the checkout command, but it doesn't create any of
the CVS control files. The aim of this command is to extract
sources for public release, so you can zip them up and send
them out to the client. For example;

cvs export source
tar -cvf source.tar source
gzip -v9 source.tar

That's just about it for basic CVS. I'll probably produce
another document on tagging at some point in the future.
Revision:	1.2
Committed:	Sun Oct 29 21:21:47 2000 UTC (24 years, 2 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
Changes since 1.1:	+30 -8 lines
Log Message:	Made a few minor modifications to wording and layout. Also updated a few points here and there.
#	User	Rev	Content
1	tdb	1.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	tdb	1.2	papers
56	tdb	1.1	plan
57	tdb	1.2	presentation
58	tdb	1.1	specification
59			user
60			experimental
61			client
62			host
63			misc
64			server
65			misc
66			source
67			client
68			host
69			misc
70			server
71			web
72			client
73			website
74			cgi-bin
75			www
76
77			We may need to expand that a bit, but it's a start.
78
79	tdb	1.2	Setting up CVS on Raptor
80			------------------------
81	tdb	1.1	Setting up CVS on raptor to use our "repository" takes a bit
82			of effort. This is because the cs-sysadmin guys have been
83			setting up CVS to run from marble, but it's not ready yet.
84			All we have to do is override some of their default
85			environment variables. Right, so add the following lines to
86			your .cshrc file (presuming you are using csh, which I think
87			you are).
88
89			unsetenv CVSROOT
90			unsetenv CVSREAD
91			unsetenv CVS_RSH
92			unsetenv CVSIGNORE
93			setenv CVSROOT /usr/local/proj/co600_10/cvs
94
95			A quick explanation of what this actually means. Firstly the
96			CVSROOT is the root directory of the CVS repository. I've
97			set it up as a directory called 'cvs' in our project space.
98			Next the CVS_RSH variable tells CVS to use something like
99			SSH, which we don't need to do locally. CVSREAD makes CVS
100			mark the files it checks-out be read-only, which is meant to
101			make you use the cvs edit command... but it's just a
102			complete pain in the arse. Last of all CVSIGNORE tells CVS
103			not to add certain files, but I think we've got enough sense
104			to be able to do that ourselves... but by all means leave
105			that line out if you feel happier.
106
107	tdb	1.2	Setting up CVS on a Public PC (with WinCVS)
108			-------------------------------------------
109	tdb	1.1	WinCVS is (obviously) a Windows frontend to CVS. The command
110			line thing is far easier to use if you're doing stuff
111			directly on raptor (or any other unix box), but under
112			windows it's nice to be able to get at files much more
113			easily. It's also got the familiar "point-n-click" style
114			interface, but I personally find that confusing.
115
116			WinCVS can be found at the following location;
117
118			\\drogo\packages\gnu\wincvs\wincvs.exe
119
120			It's not under Install Packages, so you might want to make
121			your own shortcut on the desktop, which is what I've done.
122
123			Setting up is easy. First map a drive to \\raptor\grproj (go
124			for grproj to help keep the permissions happy). Then when
125			the preferences pop up bung in m:\co600_10\cvs (assuming you
126			used m: like I did...) and select "Local mounted directory"
127			under Authentication. The only other bits to change are
128			unticking the "Checkout read-only" under Globals (it's just
129			a damn pain), and under WinCVS you might want to change the
130			"HOME folder" to your Z: drive.
131
132			Then you're ready to go with doing usual CVS stuff. Oh, it
133			took me ages to figure how to change which drive/directory
134			is viewed in the main windows... it's hidden at the bottom
135			of the View menu.
136
137			Finally, it might be possible to get it working with SSH
138			straight onto raptor, but I'm not sure of the exact process,
139	tdb	1.2	and even if it'll work. I may add this as an errata in part2
140			of this documentation.
141	tdb	1.1
142	tdb	1.2	Setting up CVS from off campus
143			------------------------------
144	tdb	1.1	Using CVS from off campus is much trickier. We have no
145			"proper" CVS facilities on raptor for remote access (it can
146			run a server specifically for this task). However, as the
147			command line CVS will make use of SSH we can connect through
148			the firewall. This is fine if you have a Unix box at home,
149			but I'm not sure (again) if this will work from Windows.
150
151	tdb	1.2	From any Unix box (that has SSH and CVS installed) you just
152			need to setup the following environment variables. These are
153			best put in a file such as .cshrc (for the csh shell).
154
155			CVS_RSH =
156			ssh
157			CVSROOT =
158			:ext:user@raptor.ukc.ac.uk:/usr/local/proj/co600_10/cvs
159
160			Every shell has it's own way of setting up environment
161			variables, for example csh using the setenv command. Consult
162			the man pages for more details.
163
164			With this done you can use the command line facilities as
165			usual, and you will be prompted for your raptor password
166			each time a connection is made.
167
168	tdb	1.1	How to use CVS
169			--------------
170			There are three main CVS operations that you'll use on a
171			regular basis; checkout, update and commit. Then there's the
172			smaller commands such as add, delete, and export. I'll
173			describe them, then give an example. This all assumes you've
174			setup the CVSROOT environment variable as described above.
175	tdb	1.2
176			These commands are for the command line version of CVS, but
177			the ideas can be applied to any version, including WinCVS.
178	tdb	1.1
179			A full list of commands can be found by typing;
180
181			cvs --help-commands
182
183			A quick mention of the version numbers first. Each file has
184			a unique version number starting at 1.1 and incrementing to
185			1.2, 1.3 and so on. It never becomes 2.x, unless you
186			manually change it. These version numbers are independant
187			for every single file, and have no overall bearing on any
188			"release versions" that go out to the public.
189
190			Firstly, the 'checkout' command. This extracts a copy of a
191			section of the CVS Repository to a local working copy. All
192			work (editing) is then carried out on this local copy. The
193			local copy can be changed, completely deleted, or
194			whatever... it'll have no effect on the database. The
195			command has the following format;
196
197			cvs checkout <module>
198
199			eg.
200
201			cvs checkout source/server
202
203			This would extract a copy of all the files in server/source
204			and all subdirectories below this. Note that CVS control
205			files will be created in 'CVS' subdirectories all over the
206			place, they're best ignored.
207
208			Next the 'update' command. This command ensures that the
209			local copy is up-to-date with the database. If the checkout
210			was done a few days ago it's possible someone else may have
211			updated something in the main repository since the original
212			checkout. After issuing the update the local copy will be
213			updated. The command is very simple;
214
215			cvs update
216
217			The exception to this is if the user has changed the local
218			copy in some way. In this case the update still takes place,
219			but any changes are merged into the local copy. No updates
220			are sent to the repository, this is important to remember!
221			This could of course cause problems if the update on the
222			repository and the local update are on the same bit of code.
223			Usually CVS can merge updates, but in this instance it will
224			give a conflict error and the user will have to manually
225			resolve them. This is a simple case of checking the code the
226			problem areas will be marked out. After the conflicts have
227			been resolved another update could be done to verify it's
228			all OK.
229
230			The update command also lets you know the state of files. If
231			it puts an 'M' next to a file (when it lists them) it means
232			you've modified it. If it's got a '?' it means the file is
233			new or not part of the CVS (you have to add new files). A
234			'C' means a conflicting file, and I think maybe 'A' means
235			the file is scheduled to be added. There are probably
236			others, check "man cvs" :)
237
238			Right, the last main command is 'commit'. This puts local
239			changes back into the repository and updates the version
240			number. You should run an update first, though, and commit
241			will complain if you haven't done when you need to. You will
242			need to enter a comment, and it's good practice to describe
243			roughly the reason for the commit - it helps keep a good
244			audit trail, and lets other users know why you did what you
245			did. In Unix it'll probably load up vi, which is ugly... I
246			think if you change the EDITOR enviroment variable you can
247			set it to use pico. The commit command is as easy as;
248
249			cvs commit
250
251			That's all there is to the everyday CVS commands. Next the
252			occasional commands. Now on to the less used ones.
253
254			Lets start with the 'add' command. Say you've done a
255			checkout of source/server and you've added a file called
256			main.java into the directory. Now lets add it to the
257			repository.
258
259			cd source/server
260			cvs add main.java
261
262			The add command will tell you that it's scheduled to be
263			added at the next commit. Simply run an update then commit
264			for the file to be added.
265
266			The 'remove' command works in a similar way I think. I'm not
267			sure whether you have to delete the file first, you'll have
268			to try it. Again you'll need to update then commit. A note
269			about deleted. The file obviously won't be deleted
270			completely, that would defeat the point in a versioning
271			system. Instead it's moved to an Attic subdirectory in the
272			CVS so you can still review it's revisions in the future,
273			and even resurrect it.
274
275			Next there's the 'release' command. This is used as a tidy
276			way of cleaning up the local files when you've finished with
277			them. To remove the above example you'd do the following;
278
279			cvs release source/server
280
281			This will ensure that you don't accidently delete any local
282			changes by informing you first of any non-commited files. If
283			you add the -d switch it will actually delete the files too;
284
285			cvs release -d source/server
286
287			This is much safer than typing "rm..." :)
288
289			Finally, the 'export' command. This has almost the same
290			effect as the checkout command, but it doesn't create any of
291			the CVS control files. The aim of this command is to extract
292			sources for public release, so you can zip them up and send
293			them out to the client. For example;
294
295			cvs export source
296			tar -cvf source.tar source
297			gzip -v9 source.tar
298
299			That's just about it for basic CVS. I'll probably produce
300			another document on tagging at some point in the future.