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