Microsoft Visual SourceSafe (VSS) to Perforce converter Summary - Obtain and install a version of Perl for your machine. If you are running a version of UNIX and for some reason don't already have Perl available, download http://www.perl.com/CPAN/src/latest.tar.gz and get your sysadmin to compile and install it. If you are running Windows 95 or NT you can download a precompiled binary from http://www.activestate.com/ - Ensure both Perforce and SourceSafe's "SS" command can execute correctly. Add the directory containing SS.EXE to your path, then try running "ss". You must use Visual SourceSafe version 5.0 or later. Test Perforce by running "p4 info". The Perforce depot should be empty (we have not tested running the converter against non-empty servers). The Perforce server need not run on the same machine you are running the converter on, however it may be wise to do so to avoid network traffic. - 2002-03-04/ps - if your PC does not use the U.S. time format, you have to adjust parse_user_and_timestamp in readhist.pl. An example for Swiss time format is provided in the comment. Still better would be a configuration option... - Untar or Unzip the converter on a disk large enough to hold all files stored in VSS, plus the space required for the "metadata". The directory you put the converter in must not be under the Perforce server root! - RHGC - If you are not a superuser in your depot then you will get error messages since the script tries to update date/time and username in changelists and labels - limited to superusers. - Change directory to the directory the converter was installed into and edit the file "config" - Create a client workspace called "vss" which looks similar to the one in "client_spec" (and has appropriate variables in "config"). - Then run "perl convert.pl" - Note that many sites have reported failures mid-way through conversions due to corruption in the SourceSafe database. The only way around this is to determine what files SourceSafe has corrupted and fix them somehow. It is highly recommended, however, that you read the following before attempting to do the conversion. Differences between VSS and Perforce 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. Restrictions and limitations Filenames may not contain ASCII unprintable characters, at signs (@) or hashes (#). 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. 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. 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. 2002-03-04/ps: If your comments contain lines with 17 ore more asterisks in a row, the extraction of metadata stops there and the conversion is only partial. If this happens to you either fix readhist.pl or just edit the VSS comments. How does the converter work? The converter works in four phases: Phase I: extract VSS metadata Phase II: improve the metadata (sort and compact changes using a heuristic) Phase III: execute appropriate VSS and p4 commands to construct Perforce database Phase IV: niceties after the fact The "ss properties" and "ss history" commands are used to extract the metadata from VSS. When the converter runs it reads configuration values from the file "config". Only root must be supplied; the others have defaults. See the comments in "config" for a description of each option. How do I check the end result, and what does it all mean? 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 A note about re-running the converter 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. originally by James Strickland (james@perforce.com) Modified by Robert Cowham (robert@vaccaperna.co.uk) Modified by Peter Steiner (peter.steiner@hugwi.ch)
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#6 | 3589 | Robert Cowham | Merge in changes from Main branch. | ||
#5 | 2134 | Robert Cowham | Tidied docs | ||
#4 | 2125 | Robert Cowham |
Several improvements: - config option for date and time format (tested with US and UK) see comments in config for details. - improved error handling when running subsidiary scripts - extra config option allowing parts of a VSS repository to be excluded (e.g. if corrupt) - allow p4port/client/user to be specified in config file |
||
#3 | 1695 | Robert Cowham | Integrated Peter's changes in - note not fully tested... | ||
#2 | 686 | Robert Cowham |
Fixed problem in improve.pl where more than one "unget" after another caused a croak to fire. Seems more reliable now. |
||
#1 | 237 | Robert Cowham |
Improved version of vsstop4. Makes life easier if importing into a depot which already contains stuff you want to keep. Also handles other people updating the depot at the same time. See changes labelled RHGC, and new items in config file. |