cvs2darcs
		 http://ab-initio.mit.edu/cvs2darcs/
			 cvs2darcs@darcs.net

cvs2darcs is a script to check out a CVS repository module and convert
it to use the Darcs version control system (http://www.darcs.net/).
In order to use it, you must have the cvsps utility installed
(http://www.cobite.com/cvsps/) (cvsps is used to extract the CVS patch
history).  cvsps version 2.0 or later is strongly recommended.  You
will also need Darcs, CVS, and Perl installed, as well as the
HTTP::Date Perl module from libwww.

To install cvs2darcs, do:

	./configure
	make install

which will install it in /usr/local/bin.  (To install it somewhere
other than /usr/local, use ./configure --prefix=<dir>).  You can
also run cvs2darcs directly from the source directory (after running
./configure).

Then, for a cvs module <module>, the basic usage is:

	cvs2darcs <module>

This checks out <module> into a new directory <module> and converts
the directory into a Darcs repository.  Run 'cvs2darcs -h' for more
options.  For example, you can pass the standard cvs -d option to
specify the location of the repository.

-----------------------------------------------------------------------------
			   Developer Notes

If you are setting up cvs2darcs from the cvs2darcs Darcs repository,
you will need to create the configure scripts etcetera before doing
anything.  Run:

	autoreconf --verbose --install --symlink --force

(You'll need automake and autoconf installed on your system.)

To create a version for distribution (so that end-users don't need
automake/autoconf), create a cvs2darcs-<version>.tar.gz file with:

	./configure
	make dist

You should *not* edit the cvs2darcs script; instead, edit cvs2darcs.in
and re-run ./config.status.

-----------------------------------------------------------------------------
		Documentation of Internal Perl Scripts

cvs2darcs is a shell script that, internally, calls two Perl scripts
written by David Roundy and Ganesh Sittampalam, called cvs_convert.pl
and branch_detect.pl.  The following text documents the direct usage
of these scripts (which was how these scripts were originally used).
The two scripts are installed in /usr/local/share/cvs2darcs/ (or
whatever the installation prefix was).

In order to run the scripts, you need a CVS checkout of the project
you're importing. As far as I know, it doesn't actually matter what
state the checkout is in.

To import HEAD:

<make a directory for it>
darcs initialize
/path/to/cvs2darcs/cvs_convert.pl /path/to/cvs/checkout

This will produce lots of output. Inspecting it might provide some idea
of what's going on.

To import another branch, you need to import the "parent" up to the
point of the fork, then import the child branch (this procedure needs
to be applied recursively until you get to HEAD)

/path/to/cvs2darcs/branch_detect.pl /path/to/cvs/checkout

This will produce output like this:

devel: 3 (HEAD)
nick: 140 (devel)
HEAD: 
ganesh: 

So, to import the nick branch we need to first import HEAD up to patch 3, 
then devel up to patch 140, then nick:

/path/to/cvs2darcs/cvs_convert.pl -l 3 /patch/to/cvs/checkout
/path/to/cvs2darcs/cvs_convert.pl -l 140 -b devel /patch/to/cvs/checkout
/path/to/cvs2darcs/cvs_convert.pl -b nick /patch/to/cvs/checkout

Known/possible bugs:

cvsps seems to cache things over-aggressively. If it seems to be ignoring
recent changes, try deleting the contents of ~/.cvsps

cvsps sometimes merges two independent checkins that occurred close to
each other in time. This is a known and unavoidable problem that isn't too
serious on its own; however if both checkins change the same file, the
changes will be reported in reverse order, which confuses things.

I'm not sure that cvs_convert.pl is deterministic; there are possibly
some weird interactions to do with process timing that can cause trouble. 
This needs proper testing.

If you have a CVS changelog formatted in a particular (fairly unlikely)
way, it'll confuse things. See the comments about bugs in the scripts.

Because CVS sets up branches at the per-file level, it's possible
to make a branch that starts from the middle of a patchset. branch_detetct.pl
will report such a branch as "INVALID".

Also, if a file is created/modified on HEAD (or any other parent branch)
after a branch is created, and later merged into that branch, then the
branch needs those changes, but they are lumped in with changes that the
branch musn't have.

Both of these problems make it pretty much inevitable that partial
changesets will need to be created for the child branch that are subsets
of full ones on the parent branch.