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.