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
    plan
    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.

Using 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.


Using 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.

Using 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.

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.

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.1
Committed:	Wed Oct 25 18:17:22 2000 UTC (24 years, 1 month 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.
#	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.