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