script/devnotes.txt

   1 DEVELOPMENT NOTES - VSS2SVN 0.10+
   2
   3 These are the development notes for the "new, improved" vss2svn script. Previous
   4 versions (0.1 - 0.3) were based on parsing output from Microsoft's ss.exe tool.
   5 The script was rewritten to instead use the ssphys.exe command-line tool, which
   6 is the result of a reverse-engineering effort on the VSS backend database files.
   7
   8 REQUIRED PERL MODULES
   9
  10 DBI
  11 DBD::SQLite2
  12 Time::CTime (Time-modules)
  13 Config::Ini
  14 Text::Glob
  15 Digest::MD5
  16 Data::UUID
  17
  18 SQLITE SCHEMA
  19
  20 All information about the conversion is stored in a SQLite version 2 database,
  21 using the DBD::SQLite Perl module. This is a wholly self-contained DBMS which
  22 offers SQL syntax, transactions, and a single database file. It is available in
  23 ActiveState's PPM repository, which means it is pre-compiled for Windows users.
  24
  25 Following is a description of the SQLite schema used by this project:
  26
  27     'Physical' table : list of physical VSS files
  28         physname (VARCHAR)  : name of physical VSS file
  29
  30     'NameLookup' table: references to item names from VSS names.dat
  31         offset              : primary key; byte offset from names.dat file
  32         name                : item name
  33
  34     'PhysicalAction' : history of actions as they pertain to physical VSS files
  35         physname (VARCHAR)  : name of physical VSS file
  36         type (VARCHAR)      : type of action (ADD, RENAME, LABEL, etc.)
  37         itemname (VARCHAR)  : name of item being acted upon
  38         itemtype (INTEGER)  : 1 = project
  39                               2 = file
  40         timestamp (INTEGER) : timestamp in VSS internal format
  41                               (seconds since Jan. 1, 1970)
  42         author (VARCHAR)    : name of user who performed action
  43         info (VARCHAR)      : action-specific info (such as previous name on
  44                               renames)
  45         comment (TEXT)      : user-supplied comment for this action
  46
  47     'Action' : history of actions on logical VSS items (files/projects)
  48         action_id (INTEGER) : primary key for Action table
  49         type (VARCHAR)      : type of action (ADD, RENAME, LABEL, etc.)
  50         itempath (VARCHAR)  : path to item being acted upon
  51         itemtype (INTEGER)  : 1 = project
  52                               2 = file
  53         timestamp (INTEGER) : timestamp in VSS internal format
  54         author (VARCHAR)    : name of user who performed action
  55         info (VARCHAR)      : action-specific info (such as previous name on
  56                               renames)
  57         comment (TEXT)      : user-supplied comment for this action
  58
  59     'Revision' table: contains information about eventual atomic SVN revisions
  60         revision_id (INT.)  : primary key for Revision table
  61         svndate (VARCHAR)   : svn:date formatted timestamp
  62         author (VARCHAR)    : name of author for this atomic revision
  63         comment (TEXT)      : comment for this atomic revision
  64         status              : 0 = revision has been imported to SVN
  65                               1 = revision not yet imported
  66
  67     'RevisionAction' table: many-to-many link between Revision and Action
  68         revision_id (INT.)  : primary key for Revision table
  69         action_id (INTEGER) : primary key for Action table
  70
  71 NOTES ON PHYSICAL VS. LOGICAL NAMES IN VSS
  72
  73 Every item in the VSS repository, whether a file or project, is represented on
  74 the backend by a "physical" file. The name of this physical file never changes,
  75 even if the name of the corresponding "logical" version-controlled item does
  76 change.
  77
  78 Unfortunately, only the original name for any item is stored in that item's
  79 physical file. If it is renamed (whether it is a project or a regular file),
  80 information about the rename is stored in the physical file of its *parent*
  81 instead.
  82
  83 This makes it rather difficult to figure out what name an item actually had when
  84 an action was performed on it. For this reason, we must maintain a history of
  85 all the names that an item ever had and the timestamp when that name became
  86 effective, so we can cross-reference this information during reconstruction of
  87 its history. This is the purpose of the 'ItemNameHistory' table.
  88
  89 The problem is compounded by the fact that we must figure out not only the name
  90 of a particular item at a given point in time, but also the name of its parent
  91 folder and all its ancestor folders at that moment as well. Luckily, physical
  92 files are created in an easily determined order, and because a file