ssphys/ReadMe.txt

   1 ========================================================================\r
   2        CONSOLE APPLICATION : ssphys\r
   3 ========================================================================\r
   4 \r
   5 \r
   6 ssphys is a replacment application for ss.exe, a Visual Source Safe reporting\r
   7 utility. ssphys reads and interpretes the physical files of an Source Safe\r
   8 archive.\r
   9 \r
  10 \r
  11 /////////////////////////////////////////////////////////////////////////////\r
  12 Notes:\r
  13 \r
  14 Source Safe stores its information in several file:\r
  15 \r
  16 1.) physical data files: \r
  17     these are all those file, that can be found in "data\[a..z]\[aaaaaaaa...zzzzzzzz]"\r
  18 2.) project information files:\r
  19     special files in data\[a..z] that tell VSS which files make up a project\r
  20 3.) names.dat\r
  21 4.) um.dat\r
  22     User Management\r
  23 5.) CRC.dat\r
  24 6.) Rights.dat\r
  25 7.) srcsafe.ini\r
  26 \r
  27 \r
  28 Most these files are made from special records that contain a header with \r
  29 length, type and crc information. The type is a two character code like "EL",\r
  30 "MC" or "FD". \r
  31 \r
  32 There are two types of these record based files. One with a 52 byte big file\r
  33 header (SSHeaderFile), and others that only contain these special records\r
  34 (SSPlainFile), and others that are simply binary files, without special records.\r
  35 \r
  36 The basic building of ssphys is based on these records (SSRecords). The records\r
  37 are read without any interpretation from a SSFile and can be wrapped by higher\r
  38 level special objects, depending on the type. The SSObject::MakeObject factory \r
  39 function builds a special SSObject derived object depending on the type.\r
  40 \r
  41 With this it is possible to build a basic history reporting. \r
  42 \r
  43 The binary layout for all special records can be found in the SSTypes.h header.\r
  44 \r
  45 /////////////////////////////////////////////////////////////////////////////\r
  46 \r
  47 Reverse Delta: \r
  48 VSS stores all checkins as reverse deltas in "FD" records. Reverse delta means,\r
  49 that the last version of the file is kept and delta to the previous version is \r
  50 stored. The last version is stored in a file named from the physical item plus\r
  51 an extension ".A" or ".B". These two extensions are used alternately. \r
  52 \r
  53 Rebuilding an older item is possible by retrieving the last version, and reverse\r
  54 apply all deltas up to the required version.\r
  55 \r
  56 The delta format is a very easy stream with only three commands with the following\r
  57 layout\r
  58 {<command> <start> <len> data} {<command> <start> <len> data} ... <stop>\r
  59 \r
  60 command:\r
  61 0 = take <len> bytes from the stream and append them to the output file\r
  62 1 = take <len> bytes from the last file, starting at offset <start> and append\r
  63     them to the output file\r
  64 2 = <stop>\r
  65 \r
  66 /////////////////////////////////////////////////////////////////////////////\r
  67 \r
  68 VSS Special notes:\r
  69 \r
  70 -- Shares\r
  71 SS support shares, but only for files. Shares are implemented in the way, that the\r
  72 reference count for the item is increased and the same physical entry is refrenced \r
  73 in another project. Additionally a shared flag is set. For each share a special "PF"\r
  74 record is appended tothe data file. There is no version information attached to \r
  75 these "PF" records. So the item can't tell when a share was made (only implicitly by \r
  76 the linear order of the history activity). \r
  77 \r
  78 Shares are only supported for files. If you recursivly share a project a new subproject\r
  79 is created in the share target project and all subitems are really shared into this\r
  80 new project. This means e.g. that the shared project does not have the same history. \r
  81 \r
  82 In each project record the ("last") specification of the parent record is stored and \r
  83 the physical item for the parent. The fact, that shares are not supported for projects\r
  84 allows us to exactly specify the parent path specification.\r
  85 \r
  86 -- Renames\r
  87 Renaming an item in VSS mainly done in tne parent project. There is a name variable \r
  88 in the item physical file that always carries the last name, but all historic activities\r
  89 are recorded in the parent. \r
  90 \r
  91 Sadly, the project structure is not recorded with FD records. As with files, the last \r
  92 state is stored in a special file, but no reverse deltas exits. To get the correct \r
  93 names for older items, one have to reverse apply all actions beginning from the last \r
  94 state.\r
  95 \r
  96 \r
  97 Renaming a project item will have additional effects. Since all sub projects will \r
  98 exactly record the parent specification, all parent specifications within the subprojects\r
  99 of the renamed parent have to be renamed also. Therefor the items will only know the last\r
 100 valid full parent specification (and the physical name), but no historic information.\r
 101 \r