Part 0: What you've got

  test/config - this is the template config file for the conversion.
		Copy it into a directory with _LOTS_ of disk space.
		This directory will also be used as the base for all
		of the generated data and the Perforce client Root.

  bin/legalrpt - not in yet but it's Chris' script to check the CVS
		 repository for bad files, duplicates in the Attic,
		 etc...  It has an option to delete the files, too.

  bin/genmetadata - this script goes through the CVS repository
		    and reads all of the information out of the
		    RCS files.  This is the basis for all of the
		    other steps and has to be done first.

  bin/genchanges - this takes the metadata that is generated and groups
		   them into "change groups" (not Perforce changes).


  bin/ckclientview - this script lets you run through your combination
		     of cvs2p4 "change groups", branch renaming and
		     client spec or P4::Modules module file to ensure
		     that every file will map somewhere.  This will run
		     a lot faster than actually trying to run through
		     the submissions.  If you're just letting cvs2p4
		     map everything then you done need this step.

  bin/dochanges - this script actually extracts file revisions out of
		  the CVS repository and submits them into Perforce.
		  Each cvs2p4 "change group" when submitted to Perforce
		  can generate one or more changelists.  First all
		  deletions are done as one Perforce change.  Then all
		  adds and edits are done.  Finally, all branches (p4
		  integrate) are done as the last possible change.

  bin/genlabellist - given the label information generated by genmetadata -l
                     and a revlog (or revmap) file, this script will created
                     equivalent label lists with Perforce revisions.


Part 1: Tips and Tricks

1.1 The genmetadata-genchanges-dochanges process takes too long.  What
    can I do?

    The problem is probably that you don't want to cut off developers
    from CVS until the conversion is complete.  You can use genmetadata's
    incremental option (-i) to only get the new file changes out of the
    CVS repository.  Rerun genchanges and the run dochanges with the -s
    option to have it pick up at the newest cvs2p4 "change group".

    The change group number will be in the first line of the changes
    file.  The changes file are named changes, changes.2, changes.3, ...
    You can do as many incrementals as you like.  The metadata files
    are named similarly.


1.2 Restarting the process because it stopped for some reason.

    Always run dochanges with the -i option.  It will keep a donelog of
    completed change groups (as well as partial ones) and will restart
    after the last completed change.  You may want to revert any opened
    files before restarting.  The operations will be attempted again.


1.3 Why/when should I use the revlog or revmap option when doing an
    incremental conversion.

    Sometimes a branch will be created after that file revision has
    already been seen in a previous genmetadata run.  When this happens
    dochanges will need the revision logs to figure out which Perforce
    file and revision to use as the integration source.

    The revlog is better than the revmap because dochanges can definitively
    determine which log entry was the original content and not one of the
    latter branches off of the original.  You will still get the same
    content using the revmap but the source file may be one of the branched
    ones.


1.4 How does the abbreviations (-a) option to dochanges work?

    The abbreviations file is a listing of root directories (relative
    to the CVS_MODULES directory, of course) to remove from the depot
    and client paths.  It has the following behaviour:

        1) only the first match in the list is used
        2) the abbreviation is anchored at the beginning of the
                path before the mapping and used later
        3) the abbreviation is removed _after_ determining where
                the file would normally have appeared in the
                depot and your client directory
        4) the abbreviation is removed after the codeline/branch

    With 1) in mind, if you want to remove both "/dirA" and "/dirA/dirB"
    you should have them listed in this order:

        /dirA/dirB
        /dirA

    With 2) and 3), if you have the path "/dirA/dirB" map into something
    like "/dirA" or "/dirB/dirA" the removal step will not find anything
    because it is trying to match "/dirA/dirB" in the removal and it no
    longer occurs.

    With 4) if '/dirA' would map to '//depot/dirA/codeline/dirA/dirC/dirA',
    it is the second dirA that will be removed to give
    '//depot/dirA/codeline/dirC/dirA'.


Part 2: Relocating files during the conversion

2.1 How can I define my own client spec to relocate files during the
    import?

    First, don't reuse the client name 'cvs2p4'.

    If you are going to define your own client spec to import the
    CVS files, the format for everything is:

	//client/branch_name/file_path/file_name

    where file_path will have the $CVS_MODULE prefix stripped off

    For example, if you have a CVS repository in /opt/CVSROOT and you
    want everything to go from /opt/CVSROOT/src/PROD-A to go into
    //products/PROD-A/branch_name, then you could create a mapping in
    your client spec like:

	//products/PROD-A/main/... //client/main/src/PROD-A/...
	//products/PROD-A/ver1/... //client/ver1/src/PROD-A/...
	//products/PROD-A/ver2/... //client/ver2/src/PROD-A/...
	
    etc... for each branch.  Make certain that you have the 'products'
    depot defined in Perforce, first.


2.2 What about files/directories that I miss or don't know where to put?

    cvs2p4 will ignore (with a warning) any unmappable files.  However,
    you could start your Client View with:

	//depot/lost_files/... //client/...

    And anything that isn't mapped later on will end up there.