Please read this whole document through carefully and install and setup configuration files carefully.
Then test with a test Perforce repository (do not start importing into your live Perforce repository!!). Note that an unlicensed Perforce test server is fine for this.
Only when you have a working version should you consider re-running with your live repository... Apart from anything else, at this point you know it will work and also you will have a rough idea of how long it will take.
Recommended practice is to import into an area of your repository such as:
//depot/import/vss/projectA/...
and then branch afterwards into your new structure for use in Perforce, e.g.
//depot/main/projectA/...
This gives you all the history (if you follow back branching history) and allows you to restructure things and get a better structure than perhaps you were forced to use in VSS (you can branch different projects to different levels).
Contents
The following versions of P4Perl are required for the current release of these scripts (version number is hard-coded and checked in module utils.pm). This readme will be updated when later versions are tested and known to work.
p4perl56-setup.exe or p4perl58-setup.exe
depending on your Perl version.Just double-click on Windows installer and run it (no real need to download and save).
You must fill in at least the following values in config.ini:
Other values are more optional but please read through the file carefully and make sensible choices!
Note that many sites have reported failures mid-way through conversions due to corruption in the SourceSafe database. The only way around this used to be to determine what files SourceSafe has corrupted and fix them somehow (by running analyze.exe with -f flag).
You can now use the "exclude" option in Config.ini file to ignore some directories if that makes your life easier, especially if used in conjunction with the "vsscorrupt" flag.
You can also use the "skip_ss_get_errors" option to ignore failures to get individual files.
In addition, please note that different versions of VSS are more reliable in some circumstances. Thus I have had a problem getting a file using VSS 6.0d and yet and older version (6.0c or even 6.0) gets the file without problems. This is one of the reasons VSS is so unreliable - they couldn't make changes without introducing bugs. Hence, you may find it worth while trying an older version. (Also please note there are more than one version of 6.0d!).
There are a number of scenarios that work-arounds have been found for. However, this is somewhat of a black art, and VSS is rather fragile so there are occasions when you just have to accept the corruptions and leave those files behind. If you have a support contract or MSDN support calls with Microsoft then it may be worth while asking for help.
If you get an error message:
Project $Some_project has been destroyed, and cannot be rebuilt. Continue anyway?(Y/N) N
then try setting ss_options in config.ini to include "-I-Y" rather than just "-I-". This will ignore the error and carry on. (As mentioned above 6.0d seems particularly susceptibel to this problem - older versions often don't give this error message).
If you get an error message:
***** Failed to run command: perl mkdepot.pl
Then:
Look in logfile.log for the last command executed. Try and run the same command from the command line. Note that the flag "-vN" is the version that is trying to be extracted. It is also worth trying to get this version out using the VSS GUI. Also make sure that analyze.exe runs without errors. In the worst case you may need to ignore that particular file (or version).
If you get an error message:
ERROR: VSS file not found: $/some/path/somefile.ext#2 get_vss_file() revision 2 to D:/vsstop4/data/main/depot/some/path/somefile.ext failed at mkdepot.pl line XXX,line NNN.
Then try the following:
Note that setting the flag "skip_ss_get_errors" to "yes" in the config.ini file might work to get around a particular error.
You can contact the curator if the above doesn't help, but be warned that some VSS repositories are corrupted in a way that certain files are not retrievable...
If contacting the curator, please send sumlogfile.log and the end of logfile.log.
The script can take a long time (many hours) to run if you have a large VSS repository. The script needs to parse the history of VSS and then get individual versions of each file out and check them in to Perforce. This by its nature takes time (and driving VSS from the command line is slow).
To ensure the fastest possible conversion:
It is highly recommended, that you read the following before
attempting to do the conversion.
VSS defines a hierarchy of files using the concept of a "project",
which is essentially just a versioned directory. The current
project must be set specifically before any VSS operation. The
information stored by VSS is stored in a proprietary format.
Perforce stores an arbitrary tree of files which can be mapped to
multiple clients independently using any 1:1 mapping. Perforce
uses RCS format files to store revisions, but all metadata
is stored in a single, central database.
Perforce uses the notion of an atomic change which may consist of many
add, edit, and/or delete operations. It is guaranteed that either all
of a change is visible, or none of it is. VSS does not provide atomic
change transactions.
VSS implements branching by "sharing" files among projects, then "branching" them by breaking this link. There is no record of merging activity.
In Perforce when you wish to create a "branch", you simply copy the files,
typically to another directory. The recommended convention
is to make the second component of the depot pathname
the branchname. Thus, when it is time for the main line of development
to be released as v7, you would typically do a
"p4 integrate //depot/main/... //depot/v7/..."
which (since there aren't any files in //depot/v7 currently) would create
copies of all files in //depot/main in //depot/v7. To refer to the mainline
version of foo.c use //depot/main/foo.c; for the v7 branched copy, use
//depot/v7/foo.c
This works well because Perforce implements a lazy copy. Archive files are never duplicated; only the metadata changes.
Merging operations are recorded in Perforce - if, for example, patches
were made to v7 code these patches could be merged back into the main line
of development with "p4 integrate //depot/v7/... //depot/main/...".
Only files which have changes that have not been previously integrated
into main will be integrated, and the integration will be recorded so
that next time those changes will not have to be revisited.
Because VSS lacks information on merging operations, the converter
simply imports files as they existed in VSS. Because the branching
models are quite different and adjustments will have to be made
after moving to Perforce, the converter does not attempt to infer
any branching relationships. It is highly recommended that the first
step after conversion is to identify directories which have a branching
relationship and establish this relationship in Perforce. Contact
Perforce Technical Support (support@perforce.com) for help with this.
Labels are commonly used in VSS; they are available in Perforce but not
usually needed. Perforce uses atomic change transactions, and thus the
state of the depot or any part of it is easy to specify.
Filenames may not contain ASCII unprintable characters, at signs (@) or
hashes (#) (please note an experimental version of the converter supports this).
Note that the converter changes things like German umlauts in filenames.
VSS files cannot start with a dollar sign ($) or contain colons (:) - these restrictions do not exist under Perforce.
Userids and labels may not contain spaces or ASCII unprintable characters. These characters will be mapped to underscores.
VSS version used must be English not Italian/French or any other version.
Time format separator should be colon e.g. hh:mm:ss rather than say hh.mm.ss (may be fixed in future).
The converter currently does not record any file deletions or renames, partially because it's extra effort to do that but also because it's impossible to do it properly; Visual SourceSafe simply will not give any history information for files which are currently deleted.
Sort order is based on time but VSS does not output seconds; it is thus
possible that two checkins will appear to be at the same time when they
weren't. This may result in two revisions of a file appearing to be out
of order. There is a
utility script to check for revisions with out-of-order checkin date/times
which will cause problems.
Corrupt dates (later revisions newer than earlier) may cause problems with
labels since the converter takes the label to refer to the next real
revision (not a label revision) rather than the closest revision in time.
The converter is not regularly tested against old server versions, and thus
it is not guaranteed to always work against all older versions. Unless
you have a good reason to use an old server version, you should run the
converter against the latest version of Perforce.
The converter works in four phases:
The "ss properties" and "ss history" commands are used to extract the metadata from VSS. Hierarchical "ss dir" commands are used if vss is indicated as being corrupt since corrupt directories can be avoided.
When the converter runs it reads configuration values from the file "config.ini". See the comments in "config.ini" for a description of each option.
If you want to be certain that the revisions stored in Perforce are
correct, answer yes to the question "Do you wish to verify the result?"
(If you say no and then change your mind, just run "perl verify.pl").
The verification step isn't done by default because it takes a long
time, and because there is no portable way to determine whether earlier
phases of the converter succeeded.
You can verify that all changes were successfully submitted by running
"p4 changes -s pending"; it should produce no output. Look in
the directory "metadata" for files containing a mapping of all VSS
files and revision numbers to the associated Perforce filename and
change number. The sorted, more human readable version is in the file
"mapping"; the tabular version is in "mapping.ns" (ns for "not sorted").
Change numbers should not be confused with version numbers. To see the files and versions affected by a particular change, type
p4 describe -s <change_number>
(Without the -s all differences between files involved in the change are displayed as well).
To see the list of all changes (you may want to pipe this through more):
p4 changes
To see the list of labels:
p4 labels
To see the list of changes affecting a particular file:
p4 filelog filename
To list revisions associated with the label "labelname":
p4 files @labelname
If you want to re-run the converter it would be best to erase the directory
tree "data", so that there cannot be any conflicts between runs. If you
don't want to keep the results of the previous conversion, delete all
files in the server root and directories below it.
You should normally also obliterate all the imported data from the previous run (e.g. p4 obliterate //depot/import/proj/... - use "-y" to really do it "p4 help obliterate"). Be careful about this since obliterate can do nasty things to your Perforce repository!!
Also delete "logfile.log" if it exists before re-running. Note that sumlogfile.log is automatically deleted and recreated each time.
See some possibly useful utility scripts.
originally by James Strickland (james@perforce.com)
Modified by Robert Cowham (robert@vaccaperna.co.uk)
Modified by Peter Steiner (peter.steiner@hugwi.ch)
$Id: //guest/perforce_software/utils/vsstop4/2006-06-special-chars/README.html#5 $