-
Notifications
You must be signed in to change notification settings - Fork 9
Running The Migration
NOTE: This wiki page was converted from the [Google Code Repo Wiki] (https://code.google.com/p/vss2svn/wiki/Welcome). Some formatting may not have survived, and some links may be broken. See the README page for more info.
[# Running The Migration
Converting your VSS database to Subversion is not a simple process. Believe me, I know how much you'd love to just push a button, convert your database, and be done with VSS forever. :)
So, please take the time to read all these instructions carefully before you begin!
One thing to keep in mind is that VSS is notorious for corrupting its repository. Its storage format is fragile and limited. It is also not a true client/server architecture, relying instead on multiple clients playing nice with each other without a layer in between to ensure consistency.
In short, it was designed as a simple, small-scale versioning system. It is '''not''' an enterprise-level solution, and it is not well-suited to large teams or for distributed systems. All this means that it is '''very rare''' to find a VSS repository that has been in use for a significant amount of time that doesn't have at least some corruption. Furthermore, its analyze.exe program does very little to actually fix corrupted data aside from simply deleting unrecognizable entries.
Maybe you already know all this, and that's why you're switching to Subversion. And we are trying to account for and handle as best as possible the various cases of corruption we encounter in VSS. However, it may just be that a large part of your repository is unrecoverable. So your decision to switch to Subversion can't happen too soon!
As we continue development on this program, we are trying to handle all the features of VSS that easily translate to Subversion features. Here is the status of our support for various features of these systems:
- '''Atomic commits:''' VSS has absolutely no concept of atomic commits. If you select 10 files to commit, enter your check-in comments, and submit, VSS will record 10 separate entries, albeit with the same author and comment for each. We attempt to detect such cases and coerce these to atomic SVN commits instead.
- '''Moves, renames, deletes, recovers:''' These actions are all handled with equivalent Subversion actions.
- '''Destroy permanently:''' By design, there is no concept of destroying something permanently in Subversion. Such actions are treated as normal deletes.
- '''Shares, branches:''' These are very popular in VSS but no such concept exists in Subversion. We attempt to recreate shares by keeping track of them internally, and any time an action is performed on a shared item, that action is duplicated across all its shares. When a branch occurs, that share is no longer tracked.
- '''Pins:''' Work is underway to support pinning, but it is not currently supported.
- '''Labels:''' Labels are currently ignored. Discussion and further development is underway, and labels will be supported in a future version.
- '''Cloaked items:''' "Cloaked" items have no equivalent in Subversion; the cloak action from VSS is ignored.
- '''Store only latest version:''' This interesting "feature" of VSS is not handled, and files marked with this flag may not be correctly recovered.
- '''Backups and restores:''' We are still investigating the changes that occur to a VSS repository when it is restored from backup. It is best to use a "pristine" copy of your VSS repository if at all possible.
- '''Partial conversions:''' At the present, partial conversions are not handled. Due to the way the VSS database is structured, we currently only support migrating the entire VSS database at once. You may be able to edit out obsolete projects or files as a post-process.
These are the steps you will need to follow in order to migrate your repository:
- Set up the Subversion server
- Set up the Subversion repository
- Prepare the VSS database for migration
- Run the migration
- Load the dumpfile into the repository
- Compare the repositories
Decide on how the migrated repository will be accessed by your users, and set up the appropriate server accordingly. You can find more about setting up the server in the [http://svnbook.red-bean.com/ subversion book](Page Outline]) in Chapter 6. You don't actually need to have the server working before you migrate, because the migration will create a dumpfile which can be loaded to your repository at any time.
Create a new Subversion repository, as described in the subversion book in Chapter 5. As with setting up the subversion server, you don't really need to have this before the migration.
Although not absolutely necessary, you should copy your VSS database to the fastest storage possible before starting the migration, such as a local hard drive. You should also ensure that no one will be accessing the VSS repository during the migration. The best way to do this is at the OS level by removing the share which points to it or by restricting write access (vss2svn does not require write access to the VSS repo to run). You can also use the VSS Admin "lock out" feature, but this is less effective.
We recommend ''against'' trying to perform major changes to the VSS repository prior to migration. If you would like to rearrange projects, rename items, or do any other sort of restructuring, it's best to do that ''after'' you've migrated. Subversion is much better at keeping track of such changes, and there's less of a chance that your VSS repo will become corrupted.
Make sure your VSS repository does not contain serious errors. Run the VSS ANALYZE tool like this:
cd ...database-dir
mkdir analyze-results
vssbinPath/ANALYZE.EXE -banalyze-results -v4 -i- data
If errors are shown, then attempt to fix the problems. The microsoft bulletin http://support.microsoft.com/kb/152807 has descriptions of how to fix various defects. If there are still problems:
mkdir analyze-results-fix
vssbinPath/ANALYZE.EXE -banalyze-results-fix -f -d -v4 -i- data
If the analyze-results/analyze.bad file lists any files, then they are corrupt. Sometimes it may be necessary to delete files listed in the analyze.bad file and their associated log. E.g., if anaylze.bad lists data/d/dcxaaaaa, then delete data/d/dcxaaaaa*. Then re-run analyze into a new directory: mkdir analyze-results-again ...analyze... -banalyze-results-again... until there are no errors.
We have seen several examples of migrations failing due to the TortoiseSVN background cache process locking files. In particular, you may see an error such as the following during your migration:
DBD::SQLite2::st execute failed: unable to open database file(1) at dbdimp.c line 419 at vss2svn.pl line 590
To prevent this, if you have TortoiseSVN installed, go to the Settings page and choose "Icon Overlays", then set "Status Cache" to "None". Remember to set it back to "Default" after you are finished.
This same SQLite2 error is thrown if you have a space character in the path where vss2svn is installed such as "C:\Documents and Settings\username\My Documents". Installing in the root directory such as C:\vss2svn will avoid this problem.
Any other programs you have which consistently monitor disk activity and which could lock files during the conversion (including indexers such as Google Desktop) should also be temporarily disabled for best performance.
See the online help by typing vss2svn.exe --help. (If you are using the Perl source code version, replace all instances of vss2svn.exe with perl vss2svn.pl). You will run a command such as:
vss2svn.exe --vssdir <dir>
where ''<dir>'' is the path to your VSS repository (the one that contains the srcsafe.ini file). You may want to enable the `--debug`` switch in order to produce lots of output which may be beneficial if you have problems. After the migration is finished, you will have a dumpfile in the directory you ran the migration from.
Typical run times for the migration are from a few minutes for very small repositories (< 100 revisions) to several hours for very large repositories.
NOTE: for now you need write access to the root directory of your windows filesystem. The ssphys command will create temporary files and these files are stored in the root directory. (see #30)
Before you load the dumpfile to Subversion, you may want to remove any obsolete projects or files from the dumpfile by using svndumpfilter. You can also split the data contained in the dumpfile into multiple repositories by using svndumpfilter.
Load the dumpfile created by vss2svn as described in the subversion book in Chapter 5.
If {{{svnadmin}}} gives an error when loading the dumpfile see FixingTheDumpfile.
After the dumpfile is loaded to Subversion, it's a good idea to do some sanity checks against the two repositories. At a minimum, you should checkout your trunk from both VSS and your new Subversion repo (or, if you don't use a "trunk", whatever area you actually do development in, which might be the entire repository) and perform a full directory comparison against the two.
The following visual diff programs can perform recursive directory comparisons as well as individual file-based comparisons, and are a great way to make sure your new repo is ready to go:
- KDiff3; free, GPL-licensed, and multi-platform.
- Meld; also free and GPL-licensed, but (apparently) Linux-only.
- WinMerge free, GPL-licensed, for Windows only.
You may want to perform some additional post-processing on your converted repository. For example, there may be many SourceSafe-specific *.scc files in your repository, and any Visual Studio files may have additional SourceSafe data. Bill Mill has written a Python script to automate some of this cleanup.