readme.pod

   1 =pod
   2
   3 =head1 Running The C<vss2svn.pl> Script
   4
   5 (NOTE: THIS DOC IS STILL A WORK IN PROGRESS!)
   6
   7 =head2 RUNNING THE SCRIPT
   8
   9 See INSTALL.txt for instructions on how to install the necessary modules for this script to run.
  10 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.
  11
  12 The URL you provide for "svnrepo" will become the base URL for all migrated
  13 files, so for the usage example above, B<$/vss/project/foo.c> would become
  14 B<http://svn/repository/url/foo.c>. Plan your migration accordingly so that you
  15 end up with the structure that you want. The URL also cannot contain any
  16 existing files; but as long as the "parent" of the URL is a Subversion
  17 repository, any non-existent directories in the URL will be created.
  18
  19 The B<$SSDIR> environment variable must be set to the directory where your
  20 system srcsafe.ini file is located; see the VSS online help for more info.
  21 The "svn" and "ss" command-line executables must also be in your PATH.
  22
  23 This script is released into the public domain. In case you're wondering
  24 about why the Vss2Svn packages have unused methods, it's because they came
  25 from in-house modules which had more functionality than just this conversion.
  26
  27 I recommend converting only a small branch at first to see how things go.
  28 This process takes a very long time for large databases. I have made liberal
  29
  30 Partway through the migration, you will be presented with a list of all
  31 usernames which performed any checkin operations in the given VSS project.
  32 If you want these user names to be preserved, you must add this list
  33 (including a user "vss_migration" for creating directories and such) to your
  34 Apache AuthUserFile with *blank passwords*. Apache must also *require* that
  35 usernames be passed, otherwise SVN will use anonymous access and you lose
  36 the usernames. So you need an "AuthType Basic" line or the like, as well as
  37 an AuthUserFile. See L<http://svnbook.red-bean.com/svnbook/ch06s04.html#svn-ch-6-sect-4.3>
  38 for more info.
  39
  40 =head2 HOW IT WORKS
  41
  42 TODO...
  43
  44 =head2 KNOWN PROBLEMS
  45
  46 Following is a list of known problems with this script. Listing a known issue
  47 here implies that I have plans to correct it in the future but haven't gotten
  48 around to it yet.
  49
  50 =over 4
  51
  52 Labels: Label support is currently poor. This will hopefully be fixed
  53 soon. In particular, label comments as well as SS.EXE label info output is
  54 currently added to the respective revision's comment in Subversion. This script
  55 may or may not eventually correctly parse labels and create a corresponding
  56 /labels area in Subversion.
  57
  58 English-Only SS.EXE supported: Currently, only the English-language
  59 version of the VSS command-line utility SS.EXE is supported. Non-English
  60 characters are allowed in filenames and comments, but the SS.EXE program itself
  61 must be English. A workaround for this issue is to find and rename the SSxx.DLL
  62 in your VSS installation, where "xx" is your two-character language code. Then
  63 rename the DLL back after the migration. Support for other languages will be
  64 added soon.
  65
  66 Cloaked Projects: If your VSS projects have cloaked projects, this
  67 script will crash. Un-cloak any projects before running this script.
  68
  69 =back
  70
  71 =end