documentation/papers/cvs-1.txt

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

Contents
--------
 - Overview
 - CVS Repository Structure
 - Setting up CVS on Raptor
 - Setting up CVS on a Public PC (with WinCVS)
 - Setting up CVS from off campus
 - How to use CVS
 
 - See "Using CVS (part 2)" for information on binaries, 
   branching, tagging and keywords.

   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.

About
-----
This document was written by Tim Bishop [tdb1@ukc.ac.uk] for 
use by the team working on a 3rd year Computer Science 
project called "i-scream". More details can be found on the 
project website;

http://www.i-scream.org.uk
Revision:	1.3
Committed:	Thu Nov 2 00:34:41 2000 UTC (25 years ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Changes since 1.2:	+22 -1 lines
Log Message:	Added a neat little contents section for easier browsing.
#	User	Rev	Content
1	tdb	1.1	Using CVS (part 1)
2			==================
3
4	tdb	1.3	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	tdb	1.1
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	tdb	1.2	papers
68	tdb	1.1	plan
69	tdb	1.2	presentation
70	tdb	1.1	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	tdb	1.2	Setting up CVS on Raptor
92			------------------------
93	tdb	1.1	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	tdb	1.2	Setting up CVS on a Public PC (with WinCVS)
120			-------------------------------------------
121	tdb	1.1	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	tdb	1.2	and even if it'll work. I may add this as an errata in part2
152			of this documentation.
153	tdb	1.1
154	tdb	1.2	Setting up CVS from off campus
155			------------------------------
156	tdb	1.1	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	tdb	1.2	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	tdb	1.1	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	tdb	1.2
188			These commands are for the command line version of CVS, but
189			the ideas can be applied to any version, including WinCVS.
190	tdb	1.1
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	tdb	1.3
314			About
315			-----
316			This document was written by Tim Bishop [tdb1@ukc.ac.uk] 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.uk