legacy/readme.pod

   1 =pod
   2
   3 =head1 Running The C<vss2svn.pl> Script
   4
   5 (NOTE: THIS DOCUMENTATION WILL NO LONGER BE MAINTAINED. IT DESCRIBES THE
   6 "LEGACY" VERSION OF THE VSS2SVN TOOL AND MUCH OF IT MAY NO LONGER BE CORRECT.)
   7
   8 =head2 READ THIS FIRST
   9
  10 Converting your VSS repository to Subversion is not a simple process. Believe
  11 me, I know how much you'd love to just push a button, convert your repo, and
  12 be done with VSS forever. :)
  13
  14 However, there are quite a few decisions to be made and quite a few things that
  15 can go wrong. Take a moment to think about what you want out of your repository
  16 and plan your migration accordingly. Start off testing the migration on small
  17 portions of your repository with few files and few checkins.
  18
  19 You will have the most success converting repositories which use as few VSS
  20 specific "features" as possible... things like cloaks, pins, shares, and "store
  21 only latest version" have no equivalent in Subversion and this script is poorly
  22 designed to handle them at this point.
  23
  24 =head2 RUNNING THE SCRIPT
  25
  26 See INSTALL.txt for instructions on how to install the necessary modules for this script to run.
  27 Start a Windows Command Prompt, change to the directory where C<vss2svn.pl> is located, and type C<perl vss2svn.pl --help>. You should get usage information regarding the script's command-line arguments. If you get a Perl error message instead, you have not installed all required modules properly.
  28
  29 The URL you provide for "svnrepo" will become the base URL for all migrated
  30 files, so for the usage example above, B<$/vss/project/foo.c> would become
  31 B<http://svn/repository/url/foo.c>. Plan your migration accordingly so that you
  32 end up with the structure that you want. The URL also cannot contain any
  33 existing files; but as long as the "parent" of the URL is a Subversion
  34 repository, any non-existent directories in the URL will be created.
  35
  36 The B<$SSDIR> environment variable must be set to the directory where your
  37 system srcsafe.ini file is located; see the VSS online help for more info.
  38 The "svn" and "ss" command-line executables must also be in your PATH.
  39
  40 This script is released into the public domain. In case you're wondering
  41 about why the Vss2Svn packages have unused methods, it's because they came
  42 from in-house modules which had more functionality than just this conversion.
  43
  44 I recommend converting only a small branch at first to see how things go.
  45 This process takes a very long time for large databases. I have made liberal
  46
  47 =head2 HOW IT WORKS
  48
  49 TODO...
  50
  51 =head2 KNOWN PROBLEMS
  52
  53 Following is a list of known problems with this script. Listing a known issue
  54 here implies that I have plans to correct it in the future but haven't gotten
  55 around to it yet.
  56
  57 =head3 SS.EXE version:
  58
  59 It seems that version 6.0d of the SS.EXE program, distributed
  60 with Visual Studio .NET, is much more prone to errors with the command line
  61 client as version 6.0c. You can check the version of Visual SourceSafe you
  62 have by typing "ss" at the Command Prompt, or by clicking Help -> About in
  63 the Visual SourceSafe Explorer program. If you encounter many errors during
  64 your migration, you may want to try installing a previous version of Visual
  65 SourceSafe in order to perform the migration. Specifically, the error message
  66 "Project Foo has been destroyed, and cannot be rebuilt" will repeatedly be given
  67 with version 6.0d on some projects.
  68
  69 =head3 Labels:
  70
  71 Label support is currently poor. This will hopefully be fixed
  72 soon. In particular, label comments as well as SS.EXE label info output is
  73 currently added to the respective revision's comment in Subversion. This script
  74 may or may not eventually correctly parse labels and create a corresponding
  75 /labels area in Subversion.
  76
  77 =head3 Non-English SS.EXE unsupported:
  78
  79 Currently, only the English-language
  80 version of the VSS command-line utility SS.EXE is supported. Non-English
  81 characters are allowed in filenames and comments, but the SS.EXE program itself
  82 must be English. A workaround for this issue is to find and rename the SSxx.DLL
  83 in your VSS installation, where "xx" is your two-character language code. Then
  84 rename the DLL back after the migration. Support for other languages will be
  85 added soon.
  86
  87 =head3 Cloaked Projects:
  88
  89 If your VSS repository has cloaked projects, this
  90 script will crash. Un-cloak any projects before running this script.
  91
  92 =head3 Pinned Projects:
  93
  94 If your VSS repository has pinned projects or files, then only
  95 revisions up to and including the "pinned" version will be migrated. You will
  96 lose all more recent versions.
  97
  98 =head3 Shared Projects:
  99
 100 If your VSS repository has shared projects or files, multiple
 101 copies of each shared object will be created in your migrated Subversion
 102 repository, with no indication that the files were shared originally. In
 103 effect, each shared copy from VSS will become its own object in Subversion.
 104
 105 =head3 VSS Errors:
 106
 107 If you encounter any other VSS error messages during your migration, the
 108 following Microsoft documentation may help explain what caused it:
 109
 110 L<"http://msdn.microsoft.com/library/default.asp?url=/library/en-us/guides/html/vsorierrormessages.asp">
 111
 112 =head2 APR ICONV FILES
 113
 114 Subversion relies on the "ICONV" package of the Apache Portable Runtime library
 115 to convert non-ascii characters in directories, filenames, and comments to its
 116 native internal UTF-8 format. In order to ensure the correct ICONV files are
 117 used, the APR_ICONV_PATH environment variable must be set to the "iconv"
 118 directory in your Subversion client's program directory.
 119
 120 However, this environment variable is not automatically set by the Subversion
 121 client install utility on Windows. Furthermore, the popular TortoiseSVN plugin
 122 for Windows Explorer installs its own (incompatible) ICONV files and sets this
 123 variable to its own location. This means that non-ascii characters can cause
 124 the migration to fail with fatal errors.
 125
 126 To fix this, you can do one of the following: set the APR_ICONV_PATH
 127 environment variable to the correct "iconv" directory in your Subversion
 128 client installation; use the --iconv argument to explicitly specify a path
 129 to set the APR_ICONV_PATH variable to during the script's run; or specify
 130 "--iconv !" to have the script set this variable to what it determines to be
 131 the correct value.
 132
 133 =head2 BEST PRACTICES
 134
 135 =head3 In-Use VSS Databases:
 136
 137 This script will not attempt to determine whether anyone is logged in to the
 138 database while you are performing the conversion. It is highly recommended that
 139 you either use VSS Admin to lock out all users, or else make a local copy of the
 140 VSS database for purposes of the conversion. See below for more on local copies.
 141
 142 =head3 Local vs. Network:
 143
 144 Placing a VSS repository on a network share is very common. However, during the
 145 conversion to SVN, you will notice a significant speed increase if you copy the
 146 VSS repository to a local drive and run the conversion from there instead. This
 147 will also help ensure that no one else is using the VSS repository while it is
 148 being converted.
 149
 150 =head3 Setting commit timestamps:
 151
 152 It is recommended that you only set SVN timestamps (i.e. the svn:date revision
 153 property) if you are converting to a brand-new Subversion repository. This is
 154 because SVN optimizes several of its operations based on the assumption that the
 155 timestamp of each revision is chronologically later than that of the previous
 156 revision.
 157
 158 This means that if you convert a VSS repository "into" an SVN repository that
 159 already has commits, or if you convert your VSS repository(ies) in multiple
 160 stages, you could end up with out-of-order svn:date values. This could render
 161 such SVN features as blame, checkout by date, etc. unreliable or unusable.