###########################################################################
# CVS Notes                                                               #
# Anuradha Weeraman, 03 June 2004                                         #
# $Id: cvs.txt,v 1.1 2004/06/02 21:17:53 anuradha Exp $                   #
###########################################################################

setting up cvs on debian is simple, just create a directory called
/var/cvs and do an apt-get install cvs and cvs-doc. to import a
project into cvs, just
	cvs import repository vendor-tag release-tags
i imported merlin by first cd'ing to the merlin directory and
	cvs import merlin anuradha merlin
i may be slightly wrong here, hint release tag but that's how i
go it to work. i also needed to say
	export CVSROOT=/var/cvs
in my ~/.bashrc.

to download a project from cvs, just do a
	cvs checkout merlin
and it will make a directory called merlin and get everything from
cvs. then u can make changes to it like there's no tomorrow, and do a
	cvs commit
your editor will start up where u will have to type a small message
about what u just did. u could just as well say
	cvs commit -m "what u did"
quickly.

if u haven't set ur CVSROOT env variable, u would have to use a -d
switch.
	cvs -d /var/cvs checkout merlin

u can clean up the downloaded copy by doing a
	cd ..
	rm -rf merlin
but a better way is to
	cd ..
	cvs release -d merlin
you will be prompted if u had made any changes.

if you can't remember if u did any changes to a specific file, just do a
	cvs diff fileuchanged.pl
and a diff will be displayed. pretty cool.

change permissions of ur cvs repository (/var/cvs) so that a certain
group has total read and write access. what i did was
	chgrp -R anuradha /var/cvs
	chmod ug+w /var/cvs since they already had read permissions
i logged myself as anuradha, made a directory called cvs and did a
	cvs checkout merlin
modified some stuff. to quickly see the changes made
	cvs diff 	and then
	cvs commit -m "just testing"
and everything worked. COOOOOOLL!!!!!

when u need to edit the administrative files, its just like editing a
project,
	cvs checkout CVSROOT
edit the stuff, and commit the changes.

ok, to setup a cvs repository, type
	cvs init
this will create the necessary administrative files and setup the
repository on the directory specified either by CVSROOT env variable
or by the -d switch. if u don't want history logging, remove the history
file.

since the cvs repository does not resort to voodoo magic to store its
stuff, u can just back up the directory in the normal way and restore
it back any time, but make sure u have the required locks in place
to prevent inconsistencies.

to connect to remote repositories, the format of the repository name
will be :
	:method:user@hostname:/path/to/repository
more details will be revealed later on.

cvs uses the rsh protocol to perform these operations, so the remote
user host needs to have a .rhosts file which grants access to the local
user. for example, suppose u are the user mozart on the local machine
'toe.example.com', and the server machine is 'faun.example.com', on
faun, put the following line into the .rhosts file in bach's home
directory:
	toe.example.com		mozart
then test it out with :
	rsh -l bach faun.example.com 'echo $PATH'
make sure that the PATH variable also includes the cvs program directory.
alternately u can specify the location of the cvs program on the clients
side by setting the CVS_SERVER env variable. this process does not
require a cvs daemon or inetd stuff. an example of accessing the remote cvs:
	cvs -d :ext:bach@faun.example.org:/usr/local/cvsroot checkout merlin

the other way of implementing cvs is by using pserver. first edit
/etc/services and add
	cvspserver	2401/tcp
and add to /etc/inetd.conf
	cvspserver  stream  tcp  nowait  root  /usr/local/bin/cvs
		cvs --allow-root=/var/cvs pserver
passwd authentication is stored in $CVSROOT/CVSROOT/passwd and is similar
to /etc/passwd. only the username and password are in it, where the password
is encrypted using unix crypt(), so it is compatible with /etc/passwd.
pserver first checks this file and then resorts to /etc/passwd which can
be prevented by setting SystemAuth=no in the config file. so, someone
accessing the repository remotely would have to type
	cvs -d :pserver:bach@faun.example.org:/var/cvs login
to login when u will be prompted for the password, and then
	cvs -d :pserver:cvs@faun.example.com:/var/cvs checkout merlin
once u have a working copy checked out u need not specify the repository
explicitly since it is stored in the cvs directories in the working copy.
the password in stored in $HOME/.cvspass and u can remove it by logging out
	cvs logout
read and write restrictions can be implemented by either inclusion or
exclusion methods. for instance read-only access can be given to users
in $CVSROOT/CVSROOT/readers :
melissa
john
anuradha
simlarly, write access can be given to users in $CVSROOT/CVSROOT/writers
and everybody else will have read-only access.

ok, now i have a better example on how to create a new project in CVS:
	cd merlin
	cvs import -m "imported sources" anuradha/merlin anuradha start
you could at first make the directory structure, import it and then later
'add' new files as they come along. remember to :
	cd ..
	mv merlin merlin.orig
	cvs checkout anuradha/merlin
	diff -r merlin.orig anuradha/merlin
	rm -rf merlin.orig
don't forget to update the modules file in the cvs administrative section
as follows :
	cvs checkout CVSROOT
	cd CVSROOT
	vi modules and add "merlin anuradha/merlin"
	cvs commit -m "added merlin module" modules
	cd ..
	cvs release -d CVSROOT

revision numbers are automatically assigned by cvs as changes are being
made, but when u need to make a certain release, you can assign a tag
which will identify all the different revision numbers together. revision
numbers look like 1.3, 2.3.2.3, 2.3.4.3.4.3 always being in sets of even
numbers. revision number with more than one period indicate revisions on
branches. if the current revision numbers in a file are 1.3 3.2 and 4.12,
adding a new file to the repository will give it a revision number of 4.1
because of the highest first number revisions in the repository. the -r
switch can be used to bring all the files to a certain revision number,
for instance :
	cvs commit -r 3.0
you cannot do this if a 3.0 already exists. if you need to maintain
several releases in parallel, u will need to branch. u can tag a release
by :
	cvs tag merlin0-5
you can check its status by
	cvs status -v
you can do this to individual files by specifying it at the end of each cmd.
this will apply recursively.

if u ever want to pull out a certain release, u just have to say
	cvs checkout -r merlin0-5 merlin
if u want to delete a tag, use :
	cvs rtag -d merlin0-5 merlin
u can also move a tag, why u may ask, well, u current 'stable' tag may be
pointing to something old, so u should be able to point it to something else.
	cvs rtag -r merlin0-49 merlin0-5

you can create a new branch by :
	cvs tag -b merlin-radical-design
also
	cvs rtag -b -r merlin0-5 merlin-senile merlin

to access a certain branch :
	cvs checkout -r merlin-radical-design merlin
to update a certain branch with one u are working on :
	cvs update -r merlin-radical-design
to get information on the branches :
	cvs status -v
will display the branch information in the sticky sections

whenever a new branch is created cvs picks an even number starting from 2
to name it.

to merge several branches,
	cvs checkout -r merlin0-5 merlin
	cvs update -j merlin-radical-design
	cvs commit -m "included radical design"
read the section on branching and merging in the cvs-doc package for more
detailed information on this.

a sample session :
	cvs update -A
	touch a b c
	cvs add a b c ; cvs ci -m "added" a b c
	cvs tag -b branchtag
	cvs update -r branchtag
	touch d ; cvs add d
	rm a ; cvs rm a
	cvs ci -m "added d, removed a"
	cvs update -A
	cvs update -jbranchtag
After these commands are executed and a `cvs commit' is done, file `a'
will be removed and file `d' added in the main branch.

to add a new file to the repository,
	cd merlin
	vi newfile
	cvs add newfile
	cvs commit
unlike other commands, add is not recursive, you cannot even type
cvs add foo/bar, you must
	cd foo
	cvs add bar
	cvs commit
to add a whole new directory structure, use the import command.

to remove a file from the repository (don't worry, in cvsland, everything
is retrievable)
	rm foo
	cvs remove foo
	cvs commit

a sample session :
	$ cd test
	$ rm *.c
	$ cvs remove
	cvs remove: Removing .
	cvs remove: scheduling a.c for removal
	cvs remove: scheduling b.c for removal
	cvs remove: use 'cvs commit' to remove these files permanently
	$ cvs ci -m "Removed unneeded files"
	cvs commit: Examining .
	cvs commit: Committing .

you can also make the 2-step removal process into one by :
	cvs remove -f *.c

If you execute remove for a file, and then change your mind before you
commit, you can undo the remove with an add command.
	$ ls
	CVS   ja.h  oj.c
	$ rm oj.c
	$ cvs remove oj.c
	cvs remove: scheduling oj.c for removal
	cvs remove: use 'cvs commit' to remove this file permanently
	$ cvs add oj.c
	U oj.c
	cvs add: oj.c, version 1.1.1.1, resurrected

If you realize your mistake before you run the remove command you can
use update to resurrect the file:
	$ rm oj.c
	$ cvs update oj.c
	cvs update: warning: oj.c was lost
	U oj.c

The way that you remove a directory is to remove all the files in it.
You don't remove the directory itself; there is no way to do that.
Instead you specify the `-P' option to cvs update, cvs checkout, or
cvs export, which will cause CVS to remove empty directories from
working directories. Probably the best way to do this is to always
specify `-P'; if you want an empty directory then put a dummy file
(for example `.keepme') in it to prevent `-P' from removing it.

Note that `-P' is implied by the `-r' or `-D' options of checkout and
export. This way CVS will be able to correctly create the directory or
not depending on whether the particular version you are checking out
contains any files in that directory.

The normal way to move a file is to copy old to new, and then issue
the normal CVS commands to remove old from the repository, and add new
         to it.
         $ mv old new
         $ cvs remove old
         $ cvs add new
         $ cvs commit -m "Renamed old to new" old new
This method is more dangerous, since it involves moving files inside
the repository. Read this entire section before trying it out!
	$ cd $CVSROOT/dir
	$ mv old,v new,v

to check out the logs :
	cvs log
to check out the history :
	cvs history

cvs can also be used to make quick and dirty patch files. to make a
patch file for changes between merlin0-5 branch and merlin1-0 :
	cvs patch -rmerlin0-5 -rmerlin1-0 merlin

stopped at chapter 10 in /usr/share/doc/cvs/html-info/cvs_1.html