ssphys/ReadMe.txt

   1 == Introduction ==\r
   2 \r
   3 ssphys is an application to read and ouput the content of the archive files \r
   4 created from Visual Source Safe 6.0. Additionally it can rebuild old versions of \r
   5 the archived files.\r
   6 \r
   7 ssphys was created in order to fully convert the from a Visual Source Safe \r
   8 archive to other source control systems, esp. subversion. The reason for the \r
   9 exitence of this tool is due to the buggyness of the VSS tool chain provided \r
  10 from Microsoft. With the provided commandline tool ss.exe it was impossible to \r
  11 retrieve deleted or renamed files.\r
  12 \r
  13 \r
  14 == Visual Source Safe ==\r
  15 \r
  16 Visual Source Safe is a source control application provided from Microsoft. \r
  17 \r
  18 === 5.0 ===\r
  19 \r
  20 not tested yet\r
  21 \r
  22 === 6.0 === \r
  23 \r
  24 provided with Visual Studio. COmes in different version. The last known is V6.0d\r
  25 \r
  26 === 7.0 ===\r
  27 \r
  28 provided with Whidebey Studio not tested yet.\r
  29 \r
  30 \r
  31 === Archive Format ===\r
  32 \r
  33 VSS differntiates between two different types of '''items''': '''Files''' and \r
  34 '''Projects''' Project are like directories and can contain different other \r
  35 Projects or Files. To differntiate between Projects and Files, Projects are \r
  36 written with a leading dollar sign like $/Project. \r
  37 \r
  38 VSS stores both types of items (Projects and Files) in seperate physical files \r
  39 within the archive. During all activities the name of the physical never \r
  40 changes, even throughout renames or deletes. If two items with the same name are \r
  41 stored within one Project, these two items are represented in two different \r
  42 physical files. \r
  43 \r
  44 The name of the physical file used for an item is build from an increasing list \r
  45 of 8 characters (aaaaaaaa...zzzzzzzz). The name of the file has no relation to \r
  46 the name of the Item. The last name that was used is recorded in the file \r
  47 aaaaaaaa.cnt in the data directory of the archive.\r
  48 \r
  49 The data directory of the archive is made up of several different files:\r
  50 \r
  51  1. physical data files: \r
  52 \r
  53     these are all those files, that can be found in the data directory. Starting \r
  54     from v6.0 the data directory is organized in different subfolders from "a" \r
  55     to "z". The physical datafiles are sorted into these folders from their \r
  56     first letter: data\[a..z]\[aaaaaaaa...zzzzzzzz]\r
  57 \r
  58  2. project information files:\r
  59 \r
  60     special files in data\[a..z] that tell VSS which Files make up a Project\r
  61 \r
  62  3. names.dat\r
  63 \r
  64     names cache to convert from a short representation of a File or Project name \r
  65     to the real name.\r
  66 \r
  67  4. um.dat\r
  68 \r
  69     User Management\r
  70 \r
  71  5. CRC.dat  \r
  72  \r
  73  6. Rights.dat \r
  74  \r
  75  7. srcsafe.ini\r
  76 \r
  77 \r
  78 Most of these files are made from special records that contain a header with \r
  79 length, type and crc information. The type is a two character code like "EL", \r
  80 "MC" or "FD", e.g names.dat and all physical files. \r
  81 \r
  82 Others files are simply binary files, without a special record structure, e.g \r
  83 status.dat\r
  84 \r
  85 Additionally sveral files have a specific file header (SSHeaderFile), and others \r
  86 that only contain these special records (SSPlainFile)\r
  87 \r
  88 The basic building of ssphys is based on these records (SSRecord). The records \r
  89 are read without any interpretation from a SSFile and can be wrapped by higher \r
  90 level special objects, depending on the type. The SSObject::MakeObject factory \r
  91 function builds a special SSObject derived object depending on the type.\r
  92 \r
  93 The binary layout for all special records can be found in the SSTypes.h header.\r
  94 \r
  95 \r
  96 === Reverse Delta ===\r
  97 \r
  98 VSS stores all checkins as reverse deltas in "FD" records. Reverse delta means, \r
  99 that the last version of the file is kept and delta to the previous version is \r
 100 stored. The last version is stored in a file named from the physical item plus \r
 101 an extension ".A" or ".B". These two extensions are used alternately. \r
 102 \r
 103 Rebuilding an older item is possible by retrieving the last version, and reverse \r
 104 apply all deltas up to the required version.\r
 105 \r
 106 The delta format is a very easy stream with only three commands with the \r
 107 following layout {<command> <start> <len> data} {<command> <start> <len> data} \r
 108 ... <stop>\r
 109 \r
 110 command: 0 = take <len> bytes from the stream and append them to the output file \r
 111 1 = take <len> bytes from the last file, starting at offset <start> and append \r
 112 them to the output file 2 = <stop>\r
 113 \r
 114 \r
 115 == VSS Actions == \r
 116 \r
 117 === Shares ===\r
 118 \r
 119 SS support shares, but only for files. Shares are implemented in the way, that \r
 120 the reference count for the item is increased and the same physical entry is \r
 121 refrenced in another project. Additionally a shared flag is set. For each share \r
 122 a special "PF" record is appended tothe data file. There is no version \r
 123 information attached to these "PF" records. So the item can't tell when a share \r
 124 was made (only implicitly by the linear order of the history activity). \r
 125 \r
 126 Shares are only supported for files. If you recursivly share a project a new \r
 127 subproject is created in the share target project and all subitems are really \r
 128 shared into this new project. This means e.g. that the shared project does not \r
 129 have the same history. \r
 130 \r
 131 In each project record the ("last") specification of the parent record is stored \r
 132 and the physical item for the parent. The fact, that shares are not supported \r
 133 for projects allows us to exactly specify the parent path specification.\r
 134 \r
 135 === Renames ===\r
 136 \r
 137 Renaming an item in VSS mainly done in tne parent project. There is a name \r
 138 variable in the item physical file that always carries the last name, but all \r
 139 historic activities are recorded in the parent. \r
 140 \r
 141 Sadly, the project structure is not recorded with FD records. As with files, the \r
 142 last state is stored in a special file, but no reverse deltas exits. To get the \r
 143 correct names for older items, one have to reverse apply all actions beginning \r
 144 from the last state.\r
 145 \r
 146 Renaming a project item will have additional effects. Since all sub projects \r
 147 will exactly record the parent specification, all parent specifications within \r
 148 the subprojects of the renamed parent have to be renamed also. Therefor the \r
 149 items will only know the last valid full parent specification (and the physical \r
 150 name), but no historic information.\r
 151 \r
 152 === Branches ===\r
 153 \r
 154 When branching a file VSS creates a new physical file and links it to the branch \r
 155 source file. The new branch is recorded in a special BF record in the branch \r
 156 source. This information is used in the properties dialog on the Paths page. \r
 157 \r
 158 A branch can only be performed on a file that was previously shared. During the \r
 159 branch the share is broken at the pinned version and a new physical file is \r
 160 created.\r
 161 \r
 162 The following changes are made:\r
 163 \r
 164  branch source::\r
 165 \r
 166   addition of a new BF record with the information about the new physical files. \r
 167   All BF records are linked from the last to the first. The last BF records and \r
 168   the number of records is stored in the DH File information record.\r
 169  \r
 170  branch target::\r
 171  \r
 172   The branch target starts as a new physical file with the following excpetions:\r
 173   \r
 174   1. The Item Information Record (DH) records the branch source physical file\r
 175   \r
 176   2. The first version is a RollBack action (in contrast to a Created File action)\r
 177   \r
 178         3. version numbering starts with one greater the version number from where the \r
 179            branch was created\r
 180   \r
 181  parent folder::\r
 182    \r
 183    A new EL (History Record) with the ActionID ''Branch_File'' is created. The \r
 184    name of the item, the old physical and the new physical files names are \r
 185    recorded. No information about the branch version is recorded.\r
 186    \r
 187   path:: the source safe name for the history of exactly one branch.\r
 188 \r
 189 example:\r
 190 \r
 191 A file Readme.txt (INEAAAAA) was branched at version 19 and the newly created "path"\r
 192 will live in the new physical file AJGAAAAA. The first version in this file is a \r
 193 RollBack action, that points back to the branch parent. The branchpoint can be \r
 194 calculated from the version number of the RollBack action, since the version number \r
 195 after the branch continues counting from the branchpoint, namely version 20.\r
 196 \r
 197 Since the Rollback action is only for internal bookeeping, no file change is \r
 198 associated with this action, that means, that the file INEAAAAA;19 is the same as the\r
 199 file AJGAAAAA;20. \r
 200 \r
 201   <Version offset="1116">\r
 202     <VersionNumber>20</VersionNumber>\r
 203     <UserName>Dirk</UserName>\r
 204     <Date>1094815584</Date>\r
 205     <Comment> </Comment>\r
 206     <Action ActionId="RollBack">\r
 207       <Physical>AJGAAAAA</Physical>\r
 208       <SSName offset="89324" type="file">Readme.txt</SSName>\r
 209       <Parent>INEAAAAA</Parent>\r
 210     </Action>\r
 211   </Version>\r
 212 \r
 213 The specifc RollBack version is reconstructable from the physical file AJGAAAAA. All\r
 214 further versions must be taken from the branch parent INEAAAAA. The version history\r
 215 for this branched file is therefor:\r
 216 \r
 217 ...\r
 218 readme.txt;21 = AJGAAAAA;21\r
 219 readme.txt;20 = AJGAAAAA;20\r
 220 readme.txt;19 = INEAAAAA;19\r
 221 readme.txt;18 = INEAAAAA;18\r
 222 ...\r
 223 \r
 224 \r
 225 === Rollback ===\r
 226 \r
 227 ==== Rollback Action vs. Rollback Activities ====\r
 228 \r
 229 The term Rollback is a bit misleading in VSS. There is a properties command where \r
 230 you can perform "Rollback" activities and, there is the "Rollback action" reported\r
 231 in the history. Both have nothing in common. \r
 232 \r
 233 The first one is available from the command line ot the history dialog of the \r
 234 SSExplorer. This one will let you "constantly" delete some content of your history \r
 235 by completly removing it out of the physical file. There are no remains left over \r
 236 and there is no entry in the item history, that you performed this action.\r
 237 \r
 238 The second one is implicitly triggered by the branch command. The branch will force\r
 239 the creation of a new physical file. In order to follow the history to the point\r
 240 before the branch, the first action in this new file is a "RollBack Action", with\r
 241 the information about the parent physical file and the branchpoint. See under Branches\r
 242 for an example. It is like saying "from now on continue with the history in a different \r
 243 file at a specific version number"\r
 244 \r
 245 If you see a "Roolback to version" action in the history of a file, this is always\r
 246 due to a branch action. \r
 247 \r