Part -1: Who to bug
If you have any problems with this conversion, please contact:
matt@starnix.com
no one else.
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/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.
NOTE: The -f option to do the fast import has proven
to be no faster than just the tips import (-t).
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. There
is also an option to supply a list of labels with the
codelines that should be used for the label revision.
The format is:
label1 codeline1 codeline2 ...
label2 codeline2 codeline3 ...
...
extra/dbdump - dumps the contents of any specifies DB file.
extra/legalrpt.pl - a script to check the CVS repository for bad files,
duplicates in the Attic, etc... It has an option to
delete the files for you, too.
extra/linedep.pl - a script to describe branch dependencies as well
as suggest a possible import order if you don't
wish to do them all at once.
extra/revcount.pl - a script to read changes files and report on some
interesting data like number of files in branches.
Part 0: Getting Started
0.1 What non-standard Perl modules will I need?
You will need Digest::MD5 from your favourite CPAN mirror.
You will also need P4-Modules, hopefully in CPAN shortly, or
from:
http://www.starnix.com/download/perforce/perl
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.
NOTE: not keeping the revlog from the start will cause dochanges
to need to be run from the start (change group 1).
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'.
1.5 dochanges dies with "P4 SUBMIT FAILED...CAN'T XXX UNOPENED FILE". What
does this mean?
It typically means that an earlier 'p4 add/edit/delete/integ' failed.
the p4 client doesn't exist with a non-zero exit value when this sort
of error occurs.
Check back in your log of STDERR (you were logging this, right?) for
a string like '...not in client view'. Usually you have missed a
depot or directory in your client view. If you are running with the
-d or -i option, you should be able to edit the client with 'p4 client'
and then restart dochanges with the -i option. Doing a 'p4 revert'
on any opened files is also a good idea.
1.6 Why is there both a revlog and a revmap option?
Some DBM implementations have severe limitations so the revlog was
added. Using one or the other is recommended as incremental dochanges
can cause the information to get out of sync between them (if you
forget one of the options later).
Also, genlabelist currently only support the revlog.
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.