Quick (and rough) tutorial for getting CVS up and running
---------------------------------------------------------
by Michael Chu (mmchu@cs.berkeley.edu)
March 11, 1998
---------------------------------------------------------

This tutorial will attempt to get you up and running using some of CVS's
very basic functionality. It will show you how to:
	- create a CVS repository.
	- add a new module (directory-tree).
	- checkout a module to work on.
	- adding files/directories.	
	- removing files/directories.
	- checkin a module you have worked on.

NOTE: This tutorial does not claim to be complete or bug-free. For a more
      thorough treatment of CVS usage, please consult:
	http://www.loria.fr/~molli/cvs-index.html

-------------------------------------------------------------------------------

Create a CVS repository
-----------------------

1) Decide on a place to put the CVS repository (say ~/CVS). NOTE: It does
   not have to be called CVS, but it is just standard practice.

2) Create that directory.
	example: mkdir ~/CVS

3) Make sure your CVSROOT environment variable is set to point to this:
	example:
		for tcsh/csh:
			setenv CVSROOT ~/CVS
		for bash:
			CVSROOT=~/CVS
			export CVSROOT

		NOTE: It is a good idea to put this in your startup script.
		      For tcsh/csh, this would be in ~/.cshrc
		      For bash, not sure, but maybe ~/.bashrc or ~/.profile

		NOTE: This MUST be set correctly for any of the CVS tools
		      to work.

4) Type: cvsinit

-------------------------------------------------------------------------------

Add a new module (directory-tree)
---------------------------------

NOTE: CVS works with whole directory trees, not individual files. So, you
      must create a directory in the CVS repository before you can add
      files. THIS DOES NOT MEAN MANUALLY ADDING IT IN VIA mkdir!!! Follow
      the directions below!

Say you wanted to add a directory called finalproject.

1) Make an empty directory called finalproject.
	example: mkdir ~/finalproject

2) Change into that directory.
	example: cd ~/finalproject

3) Type the following: cvs import finalproject finalproject finalproject
	NOTE: Yes, 3 times. I have found this does the job. Read the
	      actual manual if you want to figure out the right way to
	      do it! :-)

4) Now, remove that empty directory.
	example: rm -rf ~/finalproject

	NOTE: rm -rf is a DANGEROUS command! PLEASE USE IT WITH CAUTION!!!!
	      Essentially, it will take whatever name you give it, and remove
	      it is. If this thing is a directory, it will recursively
	      go in an remove EVERYTHING! (without any questions asked!)

5) Now, checkout a copy of that directory you just created.
	example: cvs checkout finalproject

Now, you should have a working directory called finalproject in the CVS
directory.

-------------------------------------------------------------------------------

Checking out a module to work with
----------------------------------

Say you want to check out a module to work with (say finalproject).

1) Type: cvs checkout finalproject

2) Go do your stuff in finalproject!

-------------------------------------------------------------------------------

Adding files and directories
----------------------------

If you wanted to add a directory doc into finalproject, do this:

1) cd ~/finalproject
2) mkdir doc
3) cvs add doc

This will immediately add this to the repository.

If you wanted to add a file called funnyfile to finalproject, do this:

1) cd ~/finalproject
2) DO WHATEVER YOU NEED TO CREATE THE FILE.
3) cvs add funnyfile

This will schedule it to be added next time you commit (you can commit
a bunch of changes at once).

NOTE: The directories tree before the file must be added before the file
      is added.

	example: To add ~/finalproject/mydir/test.txt

		1) cd ~/finalproject
		2) mkdir mydir
		3) cvs add mydir
		4) cd mydir
		5) CREATE THE FILE test.txt
		6) cvs add test.txt

-------------------------------------------------------------------------------

Removing a file or directory
----------------------------

To remove a file, remove it first and then schedule it to be removed from the
repository.

To remove ~/finalproject/nofun:

1) cd ~/finalproject
2) rm nofun
3) cvs remove nofun

This will remove that file the next time the directory tree is committed.

NOTE: Inside the repository, the file will still be there, but further
checkouts will not see it.


To remove a directory, it is a bit more tricky. I personally suggest you just
ignore the directory for now. (Everytime I do this, it is a learning experience
all over for me...)

-------------------------------------------------------------------------------

Checking in a module you have been working on
---------------------------------------------

1) Change to the main directory of your working directory.
	example: cd ~/finalproject

2) Type:
	cvs commit

3) If all goes well (that is there are no conflicts due to 2 people working
   in the same file on the areas too close to each other), then it
   will probably ask you to enter in a log of what you changed. And then,
   you can continue.

4) If it complains about some kind of error (it should actually say error
   somewhere), most likely it will be because of a merge conflict error.

5) If there is a merge conflict error, type:
	cvs update

   This will try to merge changes. Look for the files which is says there
   is a conflict. Go to those files and look for area that do stuff like:

<<<<<<< q
5
=======
2
>>>>>>> 1.2

   What this says is one file wants this area to look like 5 and the other
   version wants it to look like 2. So, in this case, pick the one that
   is correct, delete all the other surrounding stuff (<<<<<'s and >>>>'s and
   ===='s and the wrong version also) and run cvs commit again.

-------------------------------------------------------------------------------

This tutorial is a bit rough. If you have questions, please come ask me
(mmchu@cs.berkeley.edu) for help.

Michael Chu
3/11/98