notes on CVS

Tue Mar 15 15:19:27 EST 2005

Oddly, cvs is on the OIT Linux machines (hats) but not on the Solaris
machines (arizona).

In my experience, proper CVS usage is balanced on a pinhead.  The
official manual and tutorial were plain wrong when I last tried to use
them; if you follow their instructions, you can easily get infinite
recursively nested directories, or infinitely long filenames, or blow
away your precious original files.

Much painful experimentation has led to this sequence that worked for
me.  If you follow these steps with your own filenames, maybe it will
work for you too.  Or maybe not.  Use at your own risk and be sure to
make backup copies *before* you start to play.


1. One time only, you have to set up a CVS repository, which is a
directory containing all the projects that you maintain with CVS.

	setenv CVSROOT /u/bwk/CVS 
		for csh/tcsh (place in .cshrc)
	export CVSROOT=/u/bwk/CVS 
		for ksh/bash (place in .bashrc or .kshrc)

	mkdir /u/bwk/CVS
	cvs init

This creates a directory /u/bwk/CVS/CVSROOT and puts a bunch of stuff in
it.  Note that CVSROOT here is a literal, bearing a strong resemblance
to the shell variable, but it's not the same thing.  The name CVS is
arbitrary.


If you are starting from nothing (no files already created), then it's
easy from here:

	cvs checkout awk

then proceed to step 5.


2. *BACK UP YOUR ORIGINALS*

If you're starting from an existing set of files (my situation), this
seemed to be the easiest way to preserve the full structure before
giving it to CVS:

	cd awk
	tar cf ../awk.tar .	# makes a tar file of everything, preserving times
				# all names are local, e.g., run.c, not awk/run.c
		# this is your precious backup in case something goes wrong


3. Now import your source into CVS:

	cd
	mv awk old.awk		# preserve the precious directory just in case

	cd old.awk
	cvs import -m 'the one true awk' awk bwk bwk-2005-03-15
		#  -m 'descriptive message' module vendor-tag release-tag


4. Then do a checkout from the repository to create and populate
the working directory:

	cd
	cvs checkout awk	# creates awk, extracts from repository into it


5. At this point, you can start editing files, making new ones, etc.
When you've made a bunch of changes, you have to "commit" your changes
to cause them to affect the repository and become visible to others:

	cd awk
	... edit files, etc. ...

	cvs add any_new_files
		schedule addition for subsequent commit
	cvw remove any_files_to_delete
		schedule removal for subsequent commit

	cvs commit
		to add, remove, modify repository version
		invokes $EDITOR so you can add log information


6. Someone else working on this project can check out the files from
the repository into a (different) working directory:

	cvs checkout awk	# assumes same machine, different part
				# of the file system


7. Before you start working again, if others are working on the same
files, you should update your copies:

	cvs update

If there is a conflict between your changes and someone else's, CVS
will tell you about it, and you get to resolve it manually.  If
there are no conflicts, commit and update proceed without complaining.


8. At any time, you can look at diffs between your version and the
respository with

	cvs diff [files]

You can check status with

	cvs status [files]
		which produces a compact display of the relevant bits

or read the log information collected with each commit via

	cvs log [files]


9. CVS doesn't lock files, but if you're done working on stuff for a
while, it's apparently wise to do

	cvs release

to announce your intention to be done with stuff.  Files are not deleted
(I think).


10.  Further documentation can be found at www.cvshome.org, which has a
tutorial.  There is an online CVS book by Karl Fogel and Moshe Bar at
http://cvsbook.red-bean.com.  Arnold Robbins (who gave me invaluable
advice on CVS for this writeup) is working on an update to Unix in a
Nutshell, which will contain chapters on CVS and Subversion.