Helix SwarmHelix Swarm
Loading...

README.html

  • //
  • guest/
  • ashish_melanta/
  • perforce/
  • utils/
  • vsstop4/
  • main/
  • README.html #1
  • View
  • Commits
  • Open Download .zip Download (19 KB) 
  1. <html>
  2.  
  3. <head>
  4. <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
  5. <title>VSSToP4 - Conversion Script Readme</title>
  6. </head>
  7.  
  8. <body>
  9.  
  10. <h1>Microsoft Visual SourceSafe (VSS) to Perforce converter</h1>
  11. <h2>Summary</h2>
  12. <p>Please read this whole document through carefully and install and setup 
  13. configuration files carefully.</p>
  14. <p>Then test with a test Perforce repository (<b>do not start importing into 
  15. your live Perforce repository!!</b>). Note that an unlicensed Perforce test 
  16. server is fine for this.</p>
  17. <p>Only when you have a working version should you consider re-running with your 
  18. live repository... Apart from anything else, at this point you know it will work 
  19. and also you will have a rough idea of how long it will take.</p>
  20. <p>Recommended practice is to import into an area of your repository such as:
  21. </p>
  22. <blockquote>
  23. 	<p>//depot/import/vss/projectA/... </p>
  24. </blockquote>
  25. <p>and then branch afterwards into your new structure for use in Perforce, e.g.
  26. </p>
  27. <blockquote>
  28. 	<p>//depot/main/projectA/... </p>
  29. </blockquote>
  30. <p>This gives you all the history (if you follow back branching history) and 
  31. allows
  32. you to restructure things and get a better structure than perhaps you were 
  33. forced to
  34. use in VSS (you can branch different projects to different levels). </p>
  35. <p><b><font size="5">Contents</font></b></p>
  36. <ul>
  37. 	<li><a href="#requirements">Requirements</a></li>
  38. 	<li><a href="#running">Running the Conversion</a></li>
  39. 	<li><a href="#vss_corruptions">VSS Corruptions</a></li>
  40. 	<li><a href="#troubleshooting">Troubleshooting</a></li>
  41. 	<li><a href="#performance">Improving Performance</a></li>
  42. 	<li><a href="#differences">Differences between VSS and Perforce</a></li>
  43. 	<li><a href="#restrictions">Restrictions and limitations</a></li>
  44. 	<li><a href="#how_it_works">How does the converter work?</a></li>
  45. 	<li><a href="#check_result">How do I check the end result, and what does it all mean?</a></li>
  46. 	<li><a href="#rerunning">Re-running the converter</a></li>
  47. </ul>
  48. <h2><a name="requirements"></a>Requirements</h2>
  49. <ul>
  50. 	<li>Obtain and install a version of Perl for your machine. This script 
  51. 	assumes you are running on Windows (as it reads registry settings for date and time). You can download a precompiled binary from
  52. 	<a href="http://www.activestate.com/">http://www.activestate.com/</a> . Note 
  53. 	that this script has been mostly tested with Perl 5.6. One recent customer 
  54. 	tried using Perl 5.8 and had problems which went away when he went back to 
  55. 	5.6. We never did find out quite why - life is too short sometimes...</li>
  56. 	<li>Install P4Perl from
  57. 	<a href="http://public.perforce.com//guest/tony_smith/perforce/API/Perl/index.html">http://public.perforce.com//guest/tony_smith/perforce/API/Perl/index.html</a> 
  58. 	. This is the Perl interface to Perforce and is required because it is 
  59. 	significantly faster than executing p4.exe at the command line. </li>
  60. </ul>
  61. <blockquote>
  62. 	<p>The following versions of P4Perl are required for the current 
  63. 	release of these scripts (version number is hard-coded and checked in module utils.pm). This readme will be updated when later versions 
  64. 	are tested and known to work. <br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  65. 	<a href="http://public.perforce.com/guest/tony_smith/perforce/API/Perl/released/p4perl56-setup-3.5708.exe">p4perl56-setup.exe</a>&nbsp;
  66. 	or&nbsp;
  67. 	<a href="http://public.perforce.com/guest/tony_smith/perforce/API/Perl/released/p4perl58-setup-3.5708.exe">p4perl58-setup.exe</a><br>depending on your Perl version.&nbsp; 
  68. 	</p>
  69. 	<p>Just double-click on Windows installer and run it (no real need to download 
  70.  
  71. and save). 
  72.  
  73. </blockquote>
  74. </p>
  75. <ul>
  76. 	<li>You must use Visual SourceSafe version 5.0 or 6.0 - <b>note that VSS 
  77. 	2005 is not currently supported.</b> VSS 6.0 and 2005 both share the same 
  78. 	archive format, so please install the earlier version (2005 has been used by 
  79. 	some people successfully but not reliably - for now don't waste your time). 
  80. 	If you have 2005 you can install 6.0 in parallel - just make sure the 
  81. 	correct version is found in the path - see next point.</li>
  82. 	<li>Ensure both Perforce's &quot;p4&quot; and SourceSafe's &quot;SS&quot; command can execute 
  83. correctly.<br>Add the directory containing SS.EXE to your path, then try running &quot;ss 
  84. 	about -Y&lt;user&gt;,&lt;password&gt;&quot;.<br>(see setenv.bat for example setting 
  85. 	of environment) 
  86. 	</li>
  87. 	<li>Test Perforce by running &quot;p4 info&quot;. The Perforce depot can be empty or not.<br>The Perforce server need not run on the same machine you are running
  88. the converter on, however it may be wise to do so to avoid network
  89. traffic. <br>
  90. 	Accessing the VSS repository over a slowish network will definitely
  91. slow things down - <b>SEE IF YOU CAN COPY VSS REPOSITORY LOCALLY FOR CONVERSION</b>. 
  92. 	</li>
  93. </ul>
  94. <h2><a name="running"></a>Running the Conversion</h2>
  95. <ul>
  96. 	<li>Unzip the converter vsstop4.zip on a disk large enough to hold all files
  97. stored in VSS, plus the space required for the &quot;metadata&quot;.<br>The directory you put the converter in must not be under the Perforce
  98. server root!<br>I strongly advise not having spaces in the path (use 
  99. 	&quot;c:\work\vsstop4&quot; rather than &quot;c:\work\some path to vss\&quot; for example).</li>
  100. 	<li>If you do not configure (in config.ini) a Perforce user that has 
  101. 	superuser rights in your depot then you will get error messages since the 
  102. 	script tries to update date/time and username in changelists and labels - 
  103. 	this action is limited to superusers. </li>
  104. 	<li>Change directory to the directory the converter was installed into and
  105. edit the file &quot;config.ini&quot; to setup for your environment.<br>Please note that you can specify the name of this file by setting a DOS 
  106. Environment variable: VSSTOP4_CONFIG <br>
  107. 	(Default assumes &quot;config.ini&quot;)
  108. 	<p>You <b>must</b> fill in at least the following values in config.ini:<ul>
  109. 	<li>root</li>
  110. 	<li>p4port/p4client/p4user</li>
  111. 	<li>depot/depot_root</li>
  112. 	<li>vss_user</li>
  113. 	<li>vss_password</li>
  114. </ul>
  115. 	<p>Other values are more optional but please read through the file carefully 
  116. 	and make sensible choices!&nbsp;</li>
  117. 	<li>Make sure that you do not have a client workspace called &quot;vss&quot; or whatever 
  118. you specified
  119. as p4client in config.ini since it will be overwritten by the script. Make sure 
  120. 	your Perforce user exists.</li>
  121. 	<li>Then run &quot;perl convert.pl&quot; (note Performance tips below before doing this). 
  122. 	</li>
  123. 	<li>Examine sumlogfile.log for summary info and logfile.log for gory detalis</li>
  124. </ul>
  125. <h2><a name="vss_corruptions"></a>VSS Corruptions</h2>
  126. <p>Note that many sites have reported failures mid-way through conversions
  127. due to corruption in the SourceSafe database. The only way around this used to 
  128. be to determine what files SourceSafe has corrupted and fix them somehow (by 
  129. running analyze.exe with -f flag).</p>
  130. <p>You can now use the &quot;exclude&quot; option in Config.ini file to ignore some 
  131. directories
  132. if that makes your life easier, especially if used in conjunction with the 
  133. &quot;vsscorrupt&quot;
  134. flag. </p>
  135. <p>You can also use the &quot;skip_ss_get_errors&quot; option to ignore failures to get 
  136. individual files.</p>
  137. <h2><a name="troubleshooting"></a>Troubleshooting</h2>
  138. <p>There are a number of scenarios that work-arounds have been found for. 
  139. However, this is somewhat of a black art, and VSS is rather fragile so there are 
  140. occasions when you just have to accept the corruptions and leave those files 
  141. behind. If you have a support contract or MSDN support calls with Microsoft then 
  142. it may be worth while asking for help.</p>
  143. <p>If you get an error message:</p>
  144. <pre>Project $Some_project has been destroyed, and cannot be rebuilt. 
  145. Continue anyway?(Y/N) N </pre>
  146. <p>then try setting ss_options in config.ini to include &quot;-I-Y&quot; rather than just 
  147. &quot;-I-&quot;. This will ignore the error and carry on.</p>
  148. <p>If you get an error message: </p>
  149. <pre>***** Failed to run command: perl mkdepot.pl </pre>
  150. <p>Then: </p>
  151. <p>Look in logfile.log for the last command executed. Try and run the 
  152. same command from the command
  153. line. Note that the flag &quot;-vN&quot; is the version that is trying to be extracted. It 
  154. is also worth trying
  155. to get this version out using the VSS GUI. Also make sure that analyze.exe runs 
  156. without errors. In the
  157. worst case you may need to ignore that particular file (or version). </p>
  158. <p>If you get an error message:</p>
  159. <pre>ERROR: VSS file not found: $/some/path/somefile.ext#2
  160. get_vss_file() revision 2 to D:/vsstop4/data/main/depot/some/path/somefile.ext
  161.  failed at mkdepot.pl line XXX, <CHANGES> line NNN.
  162. </pre>
  163. <p>Then try the following:</p>
  164. <ul>
  165. 	<li>Find the &quot;get command&quot; at the end of logfile.log and execute it yourself 
  166. 	from the command line and see if that works. </li>
  167. <li>If not, try getting the same version of the same file using the VSS GUI. 
  168. Otherwise, google the error message and see if that helps.</li>
  169. 	<li>If the GUI works (and command line doesn't), then one option may be to 
  170. 	revert to using VSS 6.0c rather than 6.0d - this has fixed the problem for 
  171. 	some people.</li>
  172. </ul>
  173. <p>Note that setting the flag &quot;skip_ss_get_errors&quot; to &quot;yes&quot; in the 
  174. config.ini file 
  175. might work to get around a particular error.</p>
  176. <p>You can contact the curator if the above doesn't help, but be warned that 
  177. some VSS repositories are
  178. corrupted in a way that certain files are not retrievable... </p>
  179. <p>If contacting the curator, please send sumlogfile.log and the end of 
  180. logfile.log.</p>
  181. <h2><a name="performance"></a>Improving Performance</h2>
  182. <p>The script can take a long time (many hours) to run if you have a large VSS 
  183. repository. The
  184. script needs to parse the history of VSS and then get individual versions of 
  185. each file out
  186. and check them in to Perforce. This by its nature takes time (and driving VSS 
  187. from the command
  188. line is slow).</p>
  189. <p>To ensure the fastest possible conversion: </p>
  190. <ul>
  191. 	<li>Copy VSS repository locally (and use a fast machine! - some machines can 
  192. take 50% less time than others) </li>
  193. 	<li>Try setting the config.ini option &quot;vss_use_ole&quot; to yes - this uses VSS OLE 
  194. Automation instead
  195. of ss.exe from the command line. It can be faster (but not always). Note that 
  196. this requires the
  197. full VSS to be installed locally, and in particular the OLE interface which is 
  198. usually to be found
  199. in &quot;C:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SSAPI.DLL&quot; to be 
  200. installed and
  201. registered.<br>
  202. 	<br>****WARNING****: if you get OLE Exceptions using this option (e.g. it can be 
  203. more sensitive to VSS repository
  204. corruptions than &quot;ss get&quot;), then just turn this option off.<br>
  205. 	</li>
  206. </ul>
  207. <p>It is highly recommended, that you read the following before
  208. attempting to do the conversion.<br>
  209. </p>
  210. <h2><a name="differences"></a>Differences between VSS and Perforce</h2>
  211. <p>VSS defines a hierarchy of files using the concept of a &quot;project&quot;,
  212. which is essentially just a versioned directory. The current<br>
  213. project must be set specifically before any VSS operation. The
  214. information stored by VSS is stored in a proprietary format. </p>
  215. <p>Perforce stores an arbitrary tree of files which can be mapped to
  216. multiple clients independently using any 1:1 mapping. Perforce<br>
  217. uses RCS format files to store revisions, but all metadata
  218. is stored in a single, central database. </p>
  219. <p>Perforce uses the notion of an atomic change which may consist of many
  220. add, edit, and/or delete operations. It is guaranteed that either all<br>
  221. of a change is visible, or none of it is. VSS does not provide atomic
  222. change transactions.</p>
  223. <p>VSS implements branching by &quot;sharing&quot; files among projects, then &quot;branching&quot;
  224. them by breaking this link. There is no record of merging activity. </p>
  225. <p>In Perforce when you wish to create a &quot;branch&quot;, you simply copy the files,
  226. typically to another directory. The recommended convention<br>
  227. is to make the second component of the depot pathname
  228. the branchname. Thus, when it is time for the main line of development<br>
  229. to be released as v7, you would typically do a
  230. &quot;p4 integrate //depot/main/... //depot/v7/...&quot;
  231. which (since there aren't any files in //depot/v7 currently) would create
  232. copies of all files in //depot/main in //depot/v7. To refer to the mainline
  233. version of foo.c use //depot/main/foo.c; for the v7 branched copy, use
  234. //depot/v7/foo.c </p>
  235. <p>This works well because Perforce implements a lazy copy. Archive files
  236. are never duplicated; only the metadata changes. </p>
  237. <p>Merging operations are recorded in Perforce - if, for example, patches
  238. were made to v7 code these patches could be merged back into the main line
  239. of development with &quot;p4 integrate //depot/v7/... //depot/main/...&quot;.
  240. Only files which have changes that have not been previously integrated<br>
  241. into main will be integrated, and the integration will be recorded so
  242. that next time those changes will not have to be revisited. </p>
  243. <p>Because VSS lacks information on merging operations, the converter
  244. simply imports files as they existed in VSS. Because the branching<br>
  245. models are quite different and adjustments will have to be made
  246. after moving to Perforce, the converter does not attempt to infer<br>
  247. any branching relationships. It is highly recommended that the first
  248. step after conversion is to identify directories which have a branching<br>
  249. relationship and establish this relationship in Perforce. Contact
  250. Perforce Technical Support (support@perforce.com) for help with this. </p>
  251. <p>Labels are commonly used in VSS; they are available in Perforce but not
  252. usually needed. Perforce uses atomic change transactions, and thus the<br>
  253. state of the depot or any part of it is easy to specify.</p>
  254. <h2><a name="restrictions"></a>Restrictions and limitations</h2>
  255. <p>Filenames may not contain ASCII unprintable characters, at signs (@) or 
  256. hashes (#) (please note an experimental version of the converter supports this).<br>
  257. Note that the converter changes things like German umlauts in filenames. </p>
  258. <p>VSS files cannot start with a dollar sign ($) or contain colons
  259. (:) - these restrictions do not exist under Perforce. </p>
  260. <p>Userids and labels may not contain spaces or ASCII unprintable characters.
  261. These characters will be mapped to underscores. </p>
  262. <p>VSS version used must be English not Italian/French or any other version.</p>
  263. <p>Time format separator should be colon e.g. hh:mm:ss rather than say hh.mm.ss 
  264. (may be fixed in future).</p>
  265. <p>The converter currently does not record any file deletions or renames, 
  266. partially because
  267. it's extra effort to do that but also because it's impossible to do it
  268. properly; Visual SourceSafe simply will not give any history information
  269. for files which are currently deleted. </p>
  270. <p>Sort order is based on time but VSS does not output seconds; it is thus
  271. possible that two checkins will appear to be at the same time when they<br>
  272. weren't. This may result in two revisions of a file appearing to be out
  273. of order. There is a
  274. <a href="http://public.perforce.com/guest/robert_cowham/perforce/utils/vss_rev_date_problems.rb">
  275. utility script</a> to check for revisions with out-of-order checkin date/times 
  276. which will cause problems.</p>
  277. <p>Corrupt dates (later revisions newer than earlier) may cause problems with
  278. labels since the converter takes the label to refer to the next real<br>
  279. revision (not a label revision) rather than the closest revision in time. </p>
  280. <p>The converter is not regularly tested against old server versions, and thus
  281. it is not guaranteed to always work against all older versions. Unless<br>
  282. you have a good reason to use an old server version, you should run the
  283. converter against the latest version of Perforce. </p>
  284. <h1><a name="how_it_works"></a>How does the converter work?</h1>
  285. <p>The converter works in four phases:</p>
  286. <ul>
  287. 	<li>Phase I: extract VSS metadata</li>
  288. 	<li>Phase II: improve the metadata (sort and compact changes using a heuristic)</li>
  289. 	<li>Phase III: execute appropriate VSS and p4 commands
  290. to construct Perforce database</li>
  291. 	<li>Phase IV: niceties after the fact </li>
  292. </ul>
  293. <p>The &quot;ss properties&quot; and &quot;ss history&quot; commands are used to extract the
  294. metadata from VSS. Hierarchical &quot;ss dir&quot; commands are used if vss is indicated 
  295. as
  296. being corrupt since corrupt directories can be avoided. </p>
  297. <p>When the converter runs it reads configuration values from the file 
  298. &quot;config.ini&quot;.
  299. See the comments in &quot;config.ini&quot; for a description of each option.</p>
  300. <h2><a name="check_result"></a>How do I check the end result, and what does it all mean?</h2>
  301. <p>If you want to be certain that the revisions stored in Perforce are
  302. correct, answer yes to the question &quot;Do you wish to verify the result?&quot;<br>
  303. (If you say no and then change your mind, just run &quot;perl verify.pl&quot;). </p>
  304. <p>The verification step isn't done by default because it takes a long
  305. time, and because there is no portable way to determine whether earlier<br>
  306. phases of the converter succeeded. </p>
  307. <p>You can verify that all changes were successfully submitted by running
  308. &quot;p4 changes -s pending&quot;; it should produce no output. Look in<br>
  309. the directory &quot;metadata&quot; for files containing a mapping of all VSS
  310. files and revision numbers to the associated Perforce filename and<br>
  311. change number. The sorted, more human readable version is in the file
  312. &quot;mapping&quot;; the tabular version is in &quot;mapping.ns&quot; (ns for &quot;not sorted&quot;). </p>
  313. <p>Change numbers should not be confused with version numbers. To see the
  314. files and versions affected by a particular change, type </p>
  315. <blockquote>
  316. 	<p>p4 describe -s &lt;change_number&gt; </p>
  317. </blockquote>
  318. <p>(Without the -s all differences between files involved in the change are
  319. displayed as well). </p>
  320. <p>To see the list of all changes (you may want to pipe this through more):</p>
  321. <blockquote>
  322. 	<p>p4 changes </p>
  323. </blockquote>
  324. <p>To see the list of labels:</p>
  325. <blockquote>
  326. 	<p>p4 labels </p>
  327. </blockquote>
  328. <p>To see the list of changes affecting a particular file:</p>
  329. <blockquote>
  330. 	<p>p4 filelog filename </p>
  331. </blockquote>
  332. <p>To list revisions associated with the label &quot;labelname&quot;:</p>
  333. <blockquote>
  334. 	<p>p4 files @labelname<br></p>
  335. </blockquote>
  336. <h2><a name="rerunning"></a>Re-running the converter</h2>
  337. <p>If you want to re-run the converter it would be best to erase the directory
  338. tree &quot;data&quot;, so that there cannot be any conflicts between runs. If you<br>
  339. don't want to keep the results of the previous conversion, delete all
  340. files in the server root and directories below it.</p>
  341. <p>You should normally also obliterate all the imported data from the previous 
  342. run (e.g. p4 obliterate //depot/import/proj/... - use &quot;-y&quot; to really do it &quot;p4 
  343. help obliterate&quot;). <b>Be careful about this </b>since obliterate can do nasty 
  344. things to your Perforce repository!!</p>
  345. <p>Also delete &quot;logfile.log&quot; if it exists before re-running. Note that 
  346. sumlogfile.log is automatically deleted and recreated each time.</p>
  347. <h2>Resources</h2>
  348. <p>See some possibly useful
  349. <a href="http://public.perforce.com/guest/robert_cowham/perforce/utils/index.html">
  350. utility scripts</a>.</p>
  351. <p><br>
  352. </p>
  353. <p>originally by James Strickland (james@perforce.com)<br>
  354. Modified by Robert Cowham (robert@vaccaperna.co.uk)<br>
  355. Modified by Peter Steiner (peter.steiner@hugwi.ch)</p>
  356. <p>$Id: //guest/ashish_melanta/perforce/utils/vsstop4/main/README.html#1 $</p>
  357.  
  358. </body>
  359.  
  360. </html>
# Change User Description Committed
#1 5974 Ashish Melanta Pulling in the Perforce utils into my guest branch 18 years ago
//guest/perforce_software/utils/vsstop4/main/README.html
#12 5860 Robert Cowham - Improved logging slightly - new summary log file sumlogfile.log created 18 years ago
#11 5776 Robert Cowham Upgrade to P4Perl 3.5708 18 years ago
#10 5682 Robert Cowham Remove use of DB_File module as seems unreliable. 19 years ago
#9 5681 Robert Cowham - Fix compatibility problem with 2005.1 server
- Added tests for all servers back to 2003....2
- Log more info about options used
- Clarify the vss_user/password rather than put in ss_options «		 19 years ago
#8 5652 Robert Cowham - Add more troubleshooting help to readme.html.
- Update to use P4Perl 3.5313
- Added ne...w module utils.pm to detect and fail if wrong P4Perl version used. «		 19 years ago
#7 5439 Robert Cowham Reiterate version of P4Perl to use. 19 years ago
#6 5387 Robert Cowham - Update troubleshooting notes. 19 years ago
#5 5342 Robert Cowham Document that VSS 2005 not supported yet - use 6.0 19 years ago
#4 5334 Robert Cowham Point out config.ini values to set 19 years ago
#3 5331 Robert Cowham Updated readme 19 years ago
#2 5316 Robert Cowham Change filetype 19 years ago
#1 5315 Robert Cowham - Output script version. Changed warning message.
- Converted README.txt to README.html 		19 years ago