www/faq.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <style type="text/css"> /* <![CDATA[ */
   6   @import "tigris-branding/css/tigris.css";
   7   @import "tigris-branding/css/inst.css";
   8   /* ]]> */</style>
   9 <link rel="stylesheet" type="text/css" media="print"
  10   href="tigris-branding/css/print.css"/>
  11 <script type="text/javascript" src="tigris-branding/scripts/tigris.js"></script>
  12 <title>cvs2svn FAQ</title>
  13 </head>
  14
  15 <body id="bodycol">
  16 <div class="app">
  17
  18 <h1>cvs2svn FAQ</h1>
  19
  20 <p><strong>General:</strong></p>
  21
  22 <ol>
  23
  24   <li><a href="#incremental">Does cvs2svn support incremental
  25     repository conversion?</a></li>
  26
  27 </ol>
  28
  29
  30 <p><strong>Compatibility:</strong></p>
  31
  32 <ol>
  33
  34   <li><a href="#psyco">Does cvs2svn run under Psyco?</a></li>
  35
  36 </ol>
  37
  38
  39 <p><strong>How-to:</strong></p>
  40
  41 <ol>
  42
  43   <li><a href="#repoaccess">How can I convert a CVS repository to
  44     which I only have remote access?</a></li>
  45
  46   <li><a href="#oneatatime">How can I convert my CVS repository one
  47     module at a time?</a></li>
  48
  49   <li><a href="#partialconversion">How can I convert part of a CVS
  50     repository?</a></li>
  51
  52   <li><a href="#onetoone">How can I convert separate projects in my
  53     CVS repository into a single Subversion repository?</a></li>
  54
  55   <li><a href="#automation">I have hundreds of subprojects to convert
  56     and my options file is getting huge</a></li>
  57
  58   <li><a href="#inverted">How can I convert project <tt>foo</tt> so
  59     that <tt>trunk/tags/branches</tt> are inside of
  60     <tt>foo</tt>?</a></li>
  61
  62   <li><a href="#eol-fixup">How do I fix up end-of-line translation
  63     problems?</a></li>
  64
  65   <li><a href="#path-symbol-transforms">I want a single project but
  66     tag-rewriting rules that vary by subdirectory.  Can this be
  67     done?</a></li>
  68
  69   <li><a href="#cvsnt">How can I convert a CVSNT repository?</a></li>
  70
  71   <li><a href="#osxsetup">How do I get cvs2svn to run on OS X
  72     10.5.5?</a></li>
  73
  74 </ol>
  75
  76
  77 <p><strong>Problems:</strong></p>
  78
  79 <ol>
  80
  81   <li><a href="#atticprob">I get an error "A CVS repository cannot
  82     contain both repo/path/file.txt,v and
  83     repo/path/Attic/file.txt,v".  What can I do?</a></li>
  84
  85   <li><a href="#rcsfileinvalid">I get an error "ERROR:
  86     <i>filename</i>,v is not a valid ,v file."</a></li>
  87
  88   <li><a href="#gdbm-nfs">gdbm.error: (45, 'Operation not supported')</a></li>
  89
  90   <li><a href="#apple-single">When converting a CVS repository that
  91     was used on a Macintosh, some files have incorrect contents in
  92     SVN.</a></li>
  93
  94   <li><a href="#rcsmissing">Using cvs2svn 1.3.x, I get an error "The
  95     command '['co', '-q', '-x,v', '-p1.1', '-kk',
  96     '/home/cvsroot/myfile,v']' failed" in pass 8.</a></li>
  97
  98   <li><a href="#nonstandardntdb">Vendor branches created with
  99     "cvs import -b &lt;branch number&gt;" are not correctly
 100     handled.</a></li>
 101
 102 </ol>
 103
 104
 105 <p><strong>Getting help:</strong></p>
 106
 107 <ol>
 108
 109   <li><a href="#gettinghelp">How do I get help?</a></li>
 110
 111   <li><a href="#subscribing">How do I subscribe to a mailing list?</a></li>
 112
 113   <li><a href="#reportingbugs">How do I report a bug?</a></li>
 114
 115   <li><a href="#testcase">How can I produce a useful test case?</a></li>
 116
 117   <li><a href="#commercialsupport">Does anybody offer commercial
 118     support for cvs2svn/cvs2git conversions?</a></li>
 119
 120 </ol>
 121
 122 <hr />
 123
 124
 125 <h2>General:</h2>
 126
 127 <h3><a name="incremental" title="#incremental">Does cvs2svn support
 128 incremental repository conversion?</a></h3>
 129
 130 <p>No.</p>
 131
 132 <p>Explanation: During the transition from CVS to Subversion, it would
 133 sometimes be useful to have the new Subversion repository track
 134 activity in the CVS repository for a period of time until the final
 135 switchover.  This would require each conversion to determine what had
 136 changed in CVS since the last conversion, and add those commits on top
 137 of the Subversion repository.</p>
 138
 139 <p>Unfortunately, cvs2svn/cvs2git does <em>not</em> support
 140 incremental conversions.  With some work it would be possible to add
 141 this feature, but it would be difficult to make it robust.  The
 142 trickiest problem is that CVS allows changes to the repository that
 143 have retroactive effects (e.g., affecting parts of the history that
 144 have already been converted).</p>
 145
 146 <p>Some conversion tools claim to support incremental conversions from
 147 CVS, but as far as is known none of them are reliable.</p>
 148
 149 <p>Volunteers or sponsorship to add support for incremental
 150 conversions to cvs2svn/cvs2git would be welcome.</p>
 151
 152 <hr />
 153
 154
 155 <h2>Compatibility:</h2>
 156
 157 <h3><a name="psyco" title="#psyco">Does cvs2svn run under
 158 Psyco?</a></h3>
 159
 160 <p>No.</p>
 161
 162 <p>Explanation: <a href="http://psyco.sourceforge.net/">Psyco</a> is a
 163 python extension that can speed up the execution of Python code by
 164 compiling parts of it into i386 machine code.  Unfortunately, Psyco is
 165 known <em>not</em> to run cvs2svn correctly (this was last tested with
 166 the Psyco pre-2.0 development branch).  When cvs2svn is run under
 167 Psyco it crashes in <tt>OutputPass</tt> with an error message that
 168 looks something like this:</p>
 169
 170 <pre>
 171 cvs2svn_lib.common.InternalError: ID changed from 2 -> 3 for Trunk, r2
 172 </pre>
 173
 174 <p>The Psyco team <a
 175 href="https://sourceforge.net/tracker/?func=detail&amp;aid=2827082&amp;group_id=41036&amp;atid=429622">has
 176 been informed about the problem</a>.</p>
 177
 178 <hr />
 179
 180
 181 <h2>How-to:</h2>
 182
 183 <h3><a name="repoaccess" title="#repoaccess">How can I convert a CVS
 184 repository to which I only have remote access?</a></h3>
 185
 186 <p>cvs2svn requires direct, filesystem access to a copy of the CVS
 187 repository that you want to convert.  The reason for this requirement
 188 is that cvs2svn directly parses the <tt>*,v</tt> files that make up
 189 the CVS repository.</p>
 190
 191 <p>Many remote hosting sites provide access to backups of your CVS
 192 repository, which could be used for a cvs2svn conversion.  For
 193 example:</p>
 194
 195 <ul>
 196   <li><a href="http://sourceforge.net">SourceForge</a> allows CVS
 197     content to be accessed via
 198     <a href="http://sourceforge.net/docs/E04/en/#rsync">rsync</a>.  In
 199     fact, they provide <a
 200     href="http://sourceforge.net/apps/trac/sourceforge/wiki/SVN%20adminrepo#Usingcvs2svntocreateaSVNdumpfilefromCVScontent">complete instructions</a>
 201     for migrating a SourceForge project from CVS to SVN.</li>
 202   <li>...<i>(other examples welcome)</i></li>
 203 </ul>
 204
 205 <p>If your provider does not provide any way to download your CVS
 206 repository, there are two known tools that claim to be able to
 207 clone a CVS repository via the CVS protocol:</p>
 208
 209 <ul>
 210
 211   <li><a href="http://samba.org/ftp/tridge/rtc/cvsclone.l">cvsclone</a></li>
 212
 213   <li><a href="http://cvs.m17n.org/~akr/cvssuck/">CVSsuck</a></li>
 214
 215 </ul>
 216
 217 <p>It should be possible to use one of these tools to fetch a copy of
 218 your CVS repository from your provider, then to use cvs2svn to convert
 219 the copy.  However, the developers of cvs2svn do not have any
 220 experience with these tools, so you are on your own here.  If you try
 221 one of them, please tell us about your experience on the <a
 222 href="mailto:users@cvs2svn.tigris.org">users mailing list</a>.</p>
 223
 224
 225 <h3><a name="oneatatime" title="#oneatatime">How can I convert my CVS
 226 repository one module at a time?</a></h3>
 227
 228 <p>If you need to convert certain CVS modules (in one large
 229 repository) to Subversion <b>now</b> and other modules <b>later</b>,
 230 you may want to convert your repository one module at a time.  This
 231 situation is typically encountered in large organizations where each
 232 project has a separate lifecycle and schedule, and a one-step
 233 conversion process is not practical.
 234 </p>
 235
 236 <p>First you have to decide whether you want to put your converted
 237 projects into a single Subversion repositories or multiple ones.  This
 238 decision mostly depends on the degree of coupling between the projects
 239 and is beyond the scope of this FAQ.  See <a
 240 href="http://svnbook.red-bean.com/en/1.2/svn.reposadmin.projects.html#svn.reposadmin.projects.chooselayout">the
 241 Subversion book</a> for a discussion of repository organization.
 242 </p>
 243
 244 <p>If you decide to convert your projects into separate Subversion
 245 repositories, then please follow the instructions in <a
 246 href="#partialconversion">How can I convert part of a CVS
 247 repository?</a> once for each repository.
 248 </p>
 249
 250 <p>If you decide to put more than one CVS project into a single
 251 Subversion repository, then please follow the instructions in <a
 252 href="#onetoone">How can I convert separate projects in my CVS
 253 repository into a single Subversion repository?</a>.
 254 </p>
 255
 256
 257 <h3><a name="partialconversion" title="#partialconversion">How can I
 258 convert part of a CVS repository?</a></h3>
 259
 260 <p>This is easy: simply run cvs2svn normally, passing it the path of
 261 the project subdirectory within the CVS repository.  Since cvs2svn
 262 ignores any files outside of the path it is given, other projects
 263 within the CVS repository will be excluded from the conversion.
 264 </p>
 265
 266 <p>Example: You have a CVS repository at path <tt>/path/cvsrepo</tt>
 267 with projects in subdirectories <tt>/path/cvsrepo/foo</tt> and
 268 <tt>/path/cvsrepo/bar</tt>, and you want to create a new Subversion
 269 repository at <tt>/path/foo-svn</tt> that includes only the
 270 <tt>foo</tt> project:
 271 </p>
 272
 273 <pre>
 274     $ cvs2svn -s /path/foo-svn /path/cvsrepo/foo
 275 </pre>
 276
 277
 278 <h3><a name="onetoone" title="#onetoone">How can I convert separate
 279 projects in my CVS repository into a single Subversion
 280 repository?</a></h3>
 281
 282 <p>cvs2svn supports multiproject conversions, but you have to use the
 283 <a href="cvs2svn.html#options-file-method">options file method</a> to
 284 start the conversion.  In your options file, you simply call
 285 <tt>run_options.add_project()</tt> once for each sub-project in your
 286 repository.  For example, if your CVS repository has the layout:</p>
 287
 288 <pre>
 289   /project_a
 290   /project_b
 291 </pre>
 292
 293   <p>and you want your Subversion repository to be laid out like this:</p>
 294
 295 <pre>
 296    project_a/
 297       trunk/
 298          ...
 299       branches/
 300          ...
 301       tags/
 302          ...
 303    project_b/
 304       trunk/
 305          ...
 306       branches/
 307          ...
 308       tags/
 309          ...
 310 </pre>
 311
 312 <p>then you need to have a section like this in your options file:</p>
 313
 314 <pre>
 315 run_options.add_project(
 316     'my/cvsrepo/project_a',
 317     trunk_path='project_a/trunk',
 318     branches_path='project_a/branches',
 319     tags_path='project_a/tags',
 320     symbol_transforms=[
 321         #...whatever...
 322         ],
 323     symbol_strategy_rules=[
 324         #...whatever...
 325         ],
 326     )
 327 run_options.add_project(
 328     'my/cvsrepo/project_b',
 329     trunk_path='project_b/trunk',
 330     branches_path='project_b/branches',
 331     tags_path='project_b/tags',
 332     symbol_transforms=[
 333         #...whatever...
 334         ],
 335     symbol_strategy_rules=[
 336         #...whatever...
 337         ],
 338     )
 339 </pre>
 340
 341
 342 <h3><a name="automation" title="#automation">I have hundreds of
 343     subprojects to convert and my options file is getting
 344     huge</a></h3>
 345
 346 <p>The options file is Python code, executed by the Python
 347 interpreter.  This makes it easy to automate parts of the
 348 configuration process.  For example, to add many subprojects, you can
 349 write a Python loop:</p>
 350
 351 <pre>
 352 projects = ['A', 'B', 'C', ...etc...]
 353
 354 cvs_repo_main_dir = r'test-data/main-cvsrepos'
 355 for project in projects:
 356     run_options.add_project(
 357         cvs_repo_main_dir + '/' + project,
 358         trunk_path=(project + '/trunk'),
 359         branches_path=(project + '/branches'),
 360         tags_path=(project + '/tags'),
 361         # ...
 362         )
 363 </pre>
 364
 365 <p>or you could even read the subprojects directly from the CVS
 366 repository:</p>
 367
 368 <pre>
 369 import os
 370 cvs_repo_main_dir = r'test-data/main-cvsrepos'
 371 projects = os.listdir(cvs_repo_main_dir)
 372
 373 # Probably you don't want to convert CVSROOT:
 374 projects.remove('CVSROOT')
 375
 376 for project in projects:
 377     # ...as above...
 378 </pre>
 379
 380
 381 <h3><a name="inverted" title="#inverted">How can I convert project
 382     <tt>foo</tt> so that <tt>trunk/tags/branches</tt> are inside of
 383     <tt>foo</tt>?</a></h3>
 384
 385   <p>If <tt>foo</tt> is the only project that you want to convert,
 386     then either run cvs2svn like this:</p>
 387
 388 <pre>
 389    $ cvs2svn --trunk=foo/trunk --branches=foo/branches --tags=foo/tags CVSREPO/foo
 390 </pre>
 391
 392   <p>or use an options file that defines a project like this:</p>
 393
 394 <pre>
 395 run_options.add_project(
 396     'my/cvsrepo/foo',
 397     trunk_path='foo/trunk',
 398     branches_path='foo/branches',
 399     tags_path='foo/tags',
 400     symbol_transforms=[
 401         #...whatever...
 402         ],
 403     symbol_strategy_rules=[
 404         #...whatever...
 405         ],
 406     )
 407 </pre>
 408
 409   <p>If <tt>foo</tt> is not the only project that you want to convert,
 410     then you need to do a multiproject conversion; see <a
 411     href="#onetoone">How can I convert separate projects in my CVS
 412     repository into a single Subversion repository?</a> for more
 413     information.</p>
 414
 415
 416 <h3><a name="eol-fixup" title="#eol-fixup">How do I fix up end-of-line
 417   translation problems?</a></h3>
 418
 419   <p>Warning: cvs2svn's handling of end-of-line options changed
 420     between version 1.5.x and version 2.0.x.  <strong>This
 421     documentation applies to version 2.0.x and later.</strong>  The
 422     documentation applying to an earlier version can be found in the
 423     <tt>www</tt> directory of that release of cvs2svn.</p>
 424
 425   <p>Starting with version 2.0, the default behavior of cvs2svn is to
 426     treat all files as binary except those explicitly determined to be
 427     text.  (Previous versions treated files as text unless they were
 428     determined to be binary.)  This behavior was changed because,
 429     generally speaking, it is safer to treat a text file as binary
 430     than vice versa.</p>
 431
 432   <p>However, it is often preferred to set
 433     <tt>svn:eol-style=native</tt> for text files, so that their
 434     end-of-file format is converted to that of the client platform
 435     when the file is checked out.  This section describes how to
 436     get the settings that you want.</p>
 437
 438   <p>If a file is marked as binary in CVS (with <tt>cvs admin
 439     -kb</tt>, then cvs2svn will always treat the file as binary.  For
 440     other files, cvs2svn has a number of options that can help choose
 441     the correct end-of-line translation parameters during the
 442     conversion:</p>
 443
 444     <table border="1" cellpadding="10" cellspacing="3" width="80%">
 445
 446       <tr>
 447         <td align="right"><tt>--auto-props=FILE</tt></td>
 448         <td>
 449
 450           <p>Set arbitrary Subversion properties on files based on the
 451             auto-props section of a file in svn config format.  The
 452             auto-props file might have content like this:</p>
 453
 454 <pre>
 455 [auto-props]
 456 *.txt = svn:mime-type=text/plain;svn:eol-style=native
 457 *.doc = svn:mime-type=application/msword;!svn:eol-style
 458 </pre>
 459
 460           <p>This option can also be used in combination with
 461             <tt>--eol-from-mime-type</tt>.</p>
 462
 463           <p>To force end-of-line translation off, use a setting of
 464             the form <tt>!svn:eol-style</tt> (with a leading
 465             exclamation point).</p>
 466
 467         </td>
 468       </tr>
 469
 470       <tr>
 471         <td align="right"><tt>--mime-types=FILE</tt></td>
 472         <td><p>Specifies an Apache-style mime.types file for setting
 473           files' <tt>svn:mime-type</tt> property based on the file
 474           extension.  The mime-types file might have content like
 475           this:</p>
 476 <pre>
 477 text/plain              txt
 478 application/msword      doc
 479 </pre>
 480           <p>This option only has an effect on <tt>svn:eol-style</tt>
 481           if it is used in combination with
 482           <tt>--eol-from-mime-type</tt>.</p></td>
 483       </tr>
 484
 485       <tr>
 486         <td align="right"><tt>--eol-from-mime-type</tt></td>
 487         <td>Set <tt>svn:eol-style</tt> based on the file's mime type
 488           (if known).  If the mime type starts with "<tt>text/</tt>",
 489           then the file is treated as a text file; otherwise, it is
 490           treated as binary.  This option is useful in combination with
 491           <tt>--auto-props</tt> or <tt>--mime-types</tt>.</td>
 492       </tr>
 493
 494       <tr>
 495         <td align="right"><tt>--default-eol=STYLE</tt></td>
 496         <td>Usually cvs2svn treats a file as binary unless one of the
 497           other rules determines that it is not binary and it is not
 498           marked as binary in CVS.  But if this option is specified,
 499           then cvs2svn uses the specified style as the default.  STYLE
 500           can be 'binary' (default), 'native', 'CRLF', 'LF', or 'CR'.
 501           If you have been diligent about annotating binary files in
 502           CVS, or if you are confident that the above options will
 503           catch all of your binary files, then
 504           <tt>--default-style=native</tt> should give good
 505           results.</td>
 506       </tr>
 507
 508     </table>
 509
 510   <p>If you don't use any of these options, then cvs2svn will not
 511     arrange any line-end translation whatsoever.  The file contents in
 512     the SVN repository should be the same as the contents you would
 513     get if checking out with CVS on the machine on which cvs2svn is
 514     run.  This also means that the EOL characters of text files will
 515     be the same no matter where the SVN data are checked out (i.e.,
 516     not translated to the checkout machine's EOL format).</p>
 517
 518   <p>To do a better job, you can use <tt>--auto-props</tt>,
 519     <tt>--mime-types</tt>, and <tt>--eol-from-mime-type</tt> to
 520     specify exactly which properties to set on each file based on its
 521     filename.</p>
 522
 523   <p>For total control over setting properties on files, you can use
 524     the <a
 525     href="cvs2svn.html#options-file-method"><tt>--options</tt>-file
 526     method</a> and write your own <tt>FilePropertySetter</tt> or
 527     <tt>RevisionPropertySetter</tt> in Python.  For example,</p>
 528 <pre>
 529 from cvs2svn_lib.property_setters import FilePropertySetter
 530
 531 class MyPropertySetter(FilePropertySetter):
 532   def set_properties(self, cvs_file):
 533     if cvs_file.cvs_path.startswith('path/to/funny/files/'):
 534       cvs_file.properties['svn:mime-type'] = 'text/plain'
 535       cvs_file.properties['svn:eol-style'] = 'CRLF'
 536
 537 ctx.file_property_setters.append(MyPropertySetter())
 538 </pre>
 539   <p>See the file <tt>cvs2svn_lib/property_setters.py</tt> for more
 540     examples.</p>
 541
 542
 543 <h3><a name="path-symbol-transforms" title="#path-symbol-transforms">I
 544   want a single project but tag-rewriting rules that vary by
 545   subdirectory.  Can this be done?</a></h3>
 546
 547   <p>This is an example of how the cvs2svn conversion can be
 548     customized using Python.</p>
 549
 550   <p>Suppose you want to write symbol transform rules that are more
 551     complicated than "replace REGEXP with PATTERN".  This can easily
 552     be done by adding just a little bit of Python code to your <a
 553     href="cvs2svn.html#options-file-method">options file</a>.</p>
 554
 555   <p>When a symbol is encountered, cvs2svn iterates through the list
 556     of <tt>SymbolTransform</tt> objects defined for the project.  For
 557     each one, it calls <tt>symbol_transform.transform(cvs_file,
 558     symbol_name, revision)</tt>.  That method can return
 559     any legal symbol name, which will be used in the conversion
 560     instead of the original name.</p>
 561
 562   <p>To use this feature, you will have to use an <a
 563     href="cvs2svn.html#options-file-method">options file</a> to start
 564     the conversion.  You then write a new SymbolTransform class that
 565     inherits from RegexpSymbolTransform but checks the path before
 566     deciding whether to transform the symbol.  Add the following to
 567     your options file:</p>
 568
 569 <pre>
 570 from cvs2svn_lib.symbol_transform import RegexpSymbolTransform
 571
 572 class MySymbolTransform(RegexpSymbolTransform):
 573     def __init__(self, path, pattern, replacement):
 574         """Transform only symbols that occur within the specified PATH."""
 575
 576         self.path = path
 577         RegexpSymbolTransform.__init__(self, pattern, replacement)
 578
 579     def transform(self, cvs_file, symbol_name, revision):
 580         # Is the file is within the path we are interested in?
 581         if cvs_file.cvs_path.startswith(path + '/'):
 582             # Yes -> Allow RegexpSymbolTransform to transform the symbol:
 583             return RegexpSymbolTransform.transform(
 584                     self, cvs_file, symbol_name, revision)
 585         else:
 586             # No -> Return the symbol unchanged:
 587             return symbol_name
 588
 589 # Note that we use a Python loop to fill the list of symbol_transforms:
 590 symbol_transforms = []
 591 for subdir in ['project1', 'project2', 'project3']:
 592     symbol_transforms.append(
 593         MySymbolTransform(
 594             subdir,
 595             r'release-(\d+)_(\d+)',
 596             r'%s-release-\1.\2' % subdir))
 597
 598 # Now register the project, using our own symbol transforms:
 599 run_options.add_project(
 600     'your_cvs_path',
 601     trunk_path='trunk',
 602     branches_path='branches',
 603     tags_path='tags',
 604     symbol_transforms=symbol_transforms))
 605 </pre>
 606
 607   <p>This example causes any symbol under "project1" that looks like
 608     "release-3_12" to be transformed into a symbol named
 609     "project1-release-3.12", whereas if the same symbol appears under
 610     "project2" it will be transformed into
 611     "project2-release-3.12".</p>
 612
 613
 614 <h3><a name="cvsnt" title="#cvsnt">How can I convert a CVSNT
 615     repository?</a></h3>
 616
 617   <p><a href="http://www.cvsnt.org/">CVSNT</a> is a version control
 618     system that started out by adding support for running CVS under
 619     Windows NT.  Since then it has made numerous extensions to the RCS
 620     file format, to the point where CVS compatibility does not imply
 621     CVSNT compatibility with any degree of certainty.</p>
 622
 623   <p>cvs2svn <em>might</em> happen to successfully convert a CVSNT
 624     repository, especially if the repository has never had any
 625     CVSNT-only features used on it, but <b>this use is not supported
 626     and should not be expected to work</b>.</p>
 627
 628   <p>If you want to experiment with converting a CVSNT repository,
 629     then please consider the following suggestions:</p>
 630
 631   <ul>
 632     <li>Use cvs2svn's <tt>--use-cvs</tt> option.</li>
 633
 634     <li>Use CVSNT's version of the <tt>cvs</tt> executable (i.e.,
 635       ensure that the first <tt>cvs</tt> program in your $PATH is the
 636       one that came with CVSNT).</li>
 637
 638     <li>Carefully check the result of the conversion before you rely
 639       on it, <em>even if the conversion completed without any
 640       errors or warnings</em>.</li>
 641
 642   </ul>
 643
 644   <p>Patches to support the conversion of CVSNT repositories would, of
 645     course, be welcome.</p>
 646
 647
 648 <h3><a name="osxsetup" title="#osxsetup">How do I get cvs2svn to run
 649 on OS X 10.5.5?</a></h3>
 650
 651 <p>Attempting to run cvs2svn on a standard OS X 10.5.5 installation
 652 yields the following error:</p>
 653
 654 <blockquote> <p> ERROR: cvs2svn uses the anydbm package, which depends on
 655 lower level dbm libraries.  Your system has dbm, with which cvs2svn is
 656 known to have problems.  To use cvs2svn, you must install a Python dbm
 657 library other than dumbdbm or dbm.  See <a
 658 href="http://python.org/doc/current/lib/module-anydbm.html">http://python.org/doc/current/lib/module-anydbm.html</a>
 659 for more information. </p> </blockquote>
 660
 661 <p>The problem is that the standard distribution of python on OS X
 662 10.5.5 does not include any other dbm libraries other than the
 663 standard dbm.  In order for cvs2svn to work, we need to install the
 664 gdbm library, in addition to a new version of python that enables the
 665 python gdbm module.</p>
 666
 667 <p>The precompiled versions of python for OS X available from
 668 python.org or activestate.com (currently version 2.6.2) do not have
 669 gdbm support turned on.  To check for gdbm support, check for the
 670 library module (<code>libgdmmodule.so</code>) within the python
 671 installation.</p>
 672
 673 <p>Here is the procedure for a successful installation of cvs2svn and
 674 all supporting libs:</p>
 675
 676 <ol>
 677
 678   <li>Download the gdbm-1.8.3 (or greater) source, unarchive and
 679     change directory to gdbm-1.8.3. We need to install the gdbm
 680     libraries so python's gdbm module can use them.
 681
 682   <ol>
 683
 684     <li>Type <code>./configure</code></li>
 685
 686     <li>Edit "Makefile" so that the owner and group are not the
 687         non-existing "bin" owner and group by changing
 688
 689 <pre>
 690 BINOWN = bin
 691 BINGRP = bin
 692 </pre>
 693 to
 694 <pre>
 695 BINOWN = root
 696 BINGRP = admin
 697 </pre>
 698
 699     </li>
 700
 701     <li>Type "make"</li>
 702
 703     <li>Type "sudo make install"</li>
 704
 705   </ol>
 706
 707   </li>
 708
 709   <li>Download the Python2.6 (or greater) source, unarchive, and
 710   change directory to Python2.6.  We need to enable python gdbm
 711   support which is not enabled in the default OS X 10.5.5 installation
 712   of python, as the gdbm libs are not included.  However, we just
 713   installed the gdbm libs in step 1, so we can now compile python with
 714   gdbm support.
 715
 716   <ol>
 717
 718     <li>Edit the file "Modules/Setup" by uncommenting the line which
 719       links against gdbm by changing
 720
 721 <pre>
 722 #gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 723 </pre>
 724 to
 725 <pre>
 726 gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 727 </pre>
 728     </li>
 729
 730     <li>Edit the file "Modules/Setup" by uncommenting the line to
 731       create shared libs by changing
 732
 733 <pre>
 734 #*shared*
 735 </pre>
 736 to
 737 <pre>
 738 *shared*
 739 </pre>
 740     </li>
 741
 742     <li>Type <code>./configure --enable-framework
 743     --enable-universalsdk</code> in the top-level
 744     Python2.6 directory.  This will configure the installation of
 745     python as a shared OS X framework, and usable with OS X GUI
 746     frameworks and SDKs. You may have problems building if you don't
 747     have the SDKs that support the PPC platform. If you do, just
 748     specify <code>--disable-universalsdk</code>.
 749     By default, python will be installed in
 750     "/Library/Frameworks/Python.framework", which is what we
 751     want.</li>
 752
 753     <li>Type <code>make</code></li>
 754
 755     <li>Type <code>sudo make install</code></li>
 756
 757     <li>Type <code>cd /usr/local/bin; sudo ln -s python2.6 python</code></li>
 758
 759     <li>Make sure "/usr/local/bin" is at the front of your search path
 760     in ~/.profile or ~/.bashrc etc.</li>
 761
 762     <li>Type <code>source ~/.profle</code> or <code>source
 763     ~/.bashrc</code> etc. or alternatively, just open a new shell
 764     window.  When you type <code>which python</code> it should give
 765     you the new version in "/usr/local/bin" <strong>not</strong> the
 766     one in "/usr/bin".</li>
 767
 768   </ol>
 769
 770   </li>
 771
 772   <li>Download the cvs2svn-2.2.0 (or greater) source, unarchive and
 773   change directory to cvs2svn-2.2.0.  Many people can't get cvs2svn to
 774   work except in the installation directory.  The reason for this is
 775   that the installation places copies of cvs2svn, cvs2svn_libs, and
 776   cvs2svn_rcsparse in the /Library/Frameworks/Python.framework
 777   hierarchy.  All we need to do is make a link in /usr/local/bin
 778   pointing to the location of cvs2svn in the python framework
 779   hierarchy.  And for good measure we also make links to the lib and
 780   include directories:
 781
 782   <ol>
 783
 784     <li>Type <code>sudo make install</code></li>
 785
 786     <li>Create the required links by typing the following:
 787
 788 <pre>
 789 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/bin/cvs2svn /usr/local/bin/cvs2svn
 790 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6 /usr/local/lib/python2.6
 791 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/include/python2.6 /usr/local/include/python2.6
 792 </pre>
 793
 794     </li>
 795
 796   </ol>
 797
 798   </li>
 799
 800 </ol>
 801
 802 <p>The installation is complete. Change directory out of the
 803 cvs2svn-2.2.0 installation directory, and you should be able to run
 804 cvs2svn. Be careful *not* to copy the version of cvs2svn in the
 805 cvs2svn-2.2.0 installation directory to /usr/local/bin, as this has a
 806 different python environment setting at the top of the file than the
 807 one that was installed in the /Library/Frameworks/Python.framework
 808 hierarchy. Follow the instructions exactly, and it should work.
 809 </p>
 810
 811
 812 <hr />
 813
 814 <h2>Problems:</h2>
 815
 816 <h3><a name="atticprob" title="#atticprob">I get an error "A CVS
 817     repository cannot contain both repo/path/file.txt,v and
 818     repo/path/Attic/file.txt,v".  What can I do?</a></h3>
 819
 820 <p>Background: Normally, if you have a file called
 821 <tt>path/file.txt</tt> in your project, CVS stores its history in a
 822 file called <tt>repo/path/file.txt,v</tt>.  But if <tt>file.txt</tt>
 823 is deleted on the main line of development, CVS moves its history file
 824 to a special <tt>Attic</tt> subdirectory:
 825 <tt>repo/path/Attic/file.txt,v</tt>.  (If the file is recreated, then
 826 it is moved back out of the <tt>Attic</tt> subdirectory.)  Your
 827 repository should never contain both of these files at the same
 828 time.</p>
 829
 830 <p>This cvs2svn error message thus indicates a mild form of corruption
 831 in your CVS repository.  The file has two conflicting histories, and
 832 even CVS does not know the correct history of <tt>path/file.txt</tt>.
 833 The corruption was probably created by using tools other than CVS to
 834 backup or manipulate the files in your repository.  With a little work
 835 you can learn more about the two histories by viewing each of the
 836 <tt>file.txt,v</tt> files in a text editor.</p>
 837
 838 <p>There are four straightforward approaches to fixing the repository
 839 corruption, but each has potential disadvantages.  Remember to <b>make
 840 a backup</b> before starting.  Never run cvs2svn on a live CVS
 841 repository--always work on a copy of your repository.</p>
 842
 843 <ol>
 844   <li>Restart the conversion with the
 845     <tt>--retain-conflicting-attic-files</tt> option.  This causes the
 846     non-attic and attic versions of the file to be converted
 847     separately, with the <tt>Attic</tt> version stored to a new
 848     subdirectory as <tt>path/Attic/file.txt</tt>.  This approach
 849     avoids losing any history, but by moving the <tt>Attic</tt>
 850     version of the file to a different subdirectory it might cause
 851     historical revisions to be broken.</li>
 852
 853   <li>Remove the <tt>Attic</tt> version of the file and restart the
 854     conversion.  Sometimes it represents an old version of the file
 855     that was deleted long ago, and it won't be missed.  But this
 856     completely discards one of the file's histories, probably causing
 857     <tt>file.txt</tt> to be missing in older historical revisions.
 858     (For what it's worth, this is probably how CVS would behave in
 859     this situation.)
 860
 861     <pre>
 862       # You did make a backup, right?
 863       $ rm repo/path/Attic/file.txt,v
 864     </pre></li>
 865
 866   <li>Remove the non-<tt>Attic</tt> version of the file and restart
 867     the conversion.  This might be appropriate if the
 868     non-<tt>Attic</tt> version has less important content than the
 869     <tt>Attic</tt> version.  But this completely discards one of the
 870     file's histories, probably causing <tt>file.txt</tt> to be missing
 871     in recent historical revisions.
 872
 873     <pre>
 874       # You did make a backup, right?
 875       $ rm repo/path/file.txt,v
 876     </pre></li>
 877
 878   <li>Rename the non-<tt>Attic</tt> version of the file and restart
 879     the conversion.  This avoids losing history, but it changes the
 880     name of the non-<tt>Attic</tt> version of the file to
 881     <tt>file-not-from-Attic.txt</tt> whenever it appeared, and might
 882     thereby cause revisions to be broken.
 883
 884     <pre>
 885       # You did make a backup, right?
 886       $ mv repo/path/file.txt,v repo/path/file-not-from-Attic.txt,v
 887     </pre></li>
 888
 889 </ol>
 890
 891 <p>If you run cvs2svn on a case-insensitive operating system, it is
 892 possible to get this error even if the filename of the file in
 893 Attic has different case than the one out of the Attic.  This could
 894 happen, for example, if the CVS repository was served from a
 895 case-sensitive operating system at some time.  A workaround for this
 896 problem is to copy the CVS repository to a case-sensitive operating
 897 system and convert it there.
 898 </p>
 899
 900
 901 <h3><a name="rcsfileinvalid" title="#rcsfileinvalid">I get an error
 902     "ERROR: <i>filename</i>,v is not a valid ,v file."</a></h3>
 903
 904 <p>The named file is corrupt in some way.  (Corruption is surprisingly
 905 common in CVS repositories.)  It is likely that even CVS has problems
 906 with this file; try checking out the head revision, revision 1.1, and
 907 the tip revision on each branch of this file; probably one or more of
 908 them don't work.</p>
 909
 910 <p>Here are some options:</p>
 911
 912 <ol>
 913
 914   <li>Omit this file from the conversion (by making a copy of your
 915     repository, deleting this file from the copy, then converting from
 916     the copy).</li>
 917
 918   <li>Restore an older copy of this file from backups, if you have
 919     backups from before it was corrupted.</li>
 920
 921   <li>Hand-fix the file as best you can by opening it in a binary
 922     editor and trying to put it back in RCS file format (documented in
 923     the rcsfile(5) manpage).  Often it is older revisions that are
 924     affected by corruption; you might need to delete some old
 925     revisions to salvage newer ones.</li>
 926
 927 </ol>
 928
 929
 930 <h3><a name="gdbm-nfs" title="#gdbm-nfs">gdbm.error: (45, 'Operation
 931     not supported')</a></h3>
 932
 933 <p>This has been reported to be caused by trying to create gdbm
 934 databases on an NFS partition.  Apparently gdbm does not support
 935 databases on NFS partitions.  The workaround is to use the
 936 <tt>--tmpdir</tt> option to choose a local partition for cvs2svn to
 937 write its temporary files.</p>
 938
 939
 940 <h3><a name="apple-single" title="#apple-single">When converting a CVS
 941     repository that was used on a Macintosh, the contents of some
 942     files are incorrect in SVN.</a></h3>
 943
 944 <p>Some Macintosh CVS clients use a nonstandard trick to store the
 945 resource fork of files in CVS: instead of storing the file contents
 946 directly, store an <a
 947 href="http://rfc.net/rfc1740.html">AppleSingle</a> data stream
 948 containing both the data fork and resource fork.  When checking the
 949 file out, the client unpacks the AppleSingle data and writes the two
 950 forks separately to disk.  By default, cvs2svn treats the file
 951 contents literally, so when you check the file out of Subversion, the
 952 file contains the combined data in AppleSingle format rather than only
 953 the data fork of the file as expected.</p>
 954
 955 <p>Subversion does not have any special facilities for dealing with
 956 Macintosh resource forks, so there is nothing cvs2svn can do to
 957 preserve both forks of your data.  However, sometimes the resource
 958 fork is not needed.  If you would like to discard the resource fork
 959 and only record the data fork in Subversion, then start your
 960 conversion using the <a
 961 href="cvs2svn.html#options-file-method">options file method</a> and
 962 set the following option to <tt>True</tt> in your options file:</p>
 963
 964 <pre>
 965       ctx.decode_apple_single = True
 966 </pre>
 967
 968 <p>There is more information about this option in the comments in
 969 <tt>cvs2svn-example.options</tt>.</p>
 970
 971
 972 <h3><a name="rcsmissing" title="#installrcs">Using cvs2svn 1.3.x, I
 973     get an error "The command '['co', '-q', '-x,v', '-p1.1', '-kk',
 974     '/home/cvsroot/myfile,v']' failed" in pass 8.</a></h3>
 975
 976 <p><i>What are you using cvs2svn version 1.3.x for anyway?
 977 Upgrade!</i></p>
 978
 979 <p>But if you must, either install RCS, or ensure that CVS is
 980 installed and use cvs2svn's <a
 981 href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt></a> option.</p>
 982
 983
 984 <h3><a name="nonstandardntdb" title="#nonstandardntdb">Vendor
 985     branches created with "cvs import -b &lt;branch number&gt;"
 986     are not correctly handled.</a></h3>
 987
 988 <p>Normally, people using "cvs import" don't specify the
 989 "-b" flag.  cvs2svn handles this normal case fine.</p>
 990
 991 <p>If you have a file which has an <i>active</i> vendor branch, i.e.
 992 there have never been any trunk commits but only "cvs imports" onto
 993 the vendor branch, then cvs2svn will handle this fine.  (Even if
 994 you've used the "-b" option to specify a non-standard branch
 995 number).</p>
 996
 997 <p>If you've used "cvs import -b &lt;branch number&gt;", you didn't
 998 specify the standard CVS vendor branch number of 1.1.1, and there
 999 has since been a commit on trunk (either a modification or delete),
1000 then your history has been damaged.  This isn't cvs2svn's fault.
1001 CVS simply doesn't record the branch number of the old vendor branch,
1002 it assumes it was 1.1.1.  You will even get the wrong results from
1003 "cvs checkout -D" with a date when the vendor branch was active.</p>
1004
1005 <p>Symptoms of this problem can include:</p>
1006
1007 <ul>
1008 <li>cvs2svn refusing to let you exclude the vendor branch, because
1009 some other branch depends on it</li>
1010 <li>if you did more than one import onto the vendor branch, then
1011 your SVN history "missing" one of the changes on trunk (though
1012 the change will be on the vendor branch).</li>
1013 </ul>
1014
1015 <p>(Note: There are other possible causes for these symptoms, don't
1016 assume you have a non-standard vendor branch number just because
1017 you see these symptoms).</p>
1018
1019 <p>The way to solve this problem is to renumber the vendor branch to
1020 the standard 1.1.1 branch number.  This has to be done before you run
1021 cvs2svn.  To help you do this, there is the "renumber_branch.py"
1022 script in the "contrib" directroy of the cvs2svn distribution.</p>
1023
1024 <p>The typical usage, assuming you used "cvs import -b 1.1.2 ..."
1025 to create your vendor branch, is:</p>
1026 <pre>
1027       contrib/renumber_branch.py 1.1.2 1.1.1 repos/dir/file,v
1028 </pre>
1029 <p>You should only run this on a <b>copy</b> of your CVS repository,
1030 as it edits the repository in-place.  You can fix a single file or a
1031 whole directory tree at a time.</p>
1032
1033 <p>The script will check that the 1.1.1 branch doesn't already exist;
1034 if it does exist then it will fail with an error message.</p>
1035
1036
1037
1038 <h2>Getting help:</h2>
1039
1040 <h3><a name="gettinghelp" title="#gettinghelp">How do I get
1041 help?</a></h3>
1042
1043 <p>There are several sources of help for cvs2svn:</p>
1044
1045 <ul>
1046
1047   <li>The <a href="cvs2svn.html">user manual</a> not only describes
1048   how to run cvs2svn, but also discusses some limitations, pitfalls,
1049   and conversion strategies.  Please note that the <a
1050   href="http://cvs2svn.tigris.org/cvs2svn.html">online manual</a>
1051   describes the latest "bleeding edge" trunk version of the software,
1052   which may be different than the version that you are using.</li>
1053
1054   <li>The <a href="faq.html">frequently asked questions (FAQ) list</a>
1055   is the document that you are now reading.  Please make sure you've
1056   scanned through the list of topics to see if your question is
1057   already answered.</li>
1058
1059   <li>The <a
1060   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">mailing
1061   list archives</a>.  Maybe your question has
1062   been discussed on either the <tt>user@cvs2svn.tigris.org</tt> or
1063   <tt>dev@cvs2svn.tigris.org</tt> mailing list.</li>
1064
1065   <li>If you need help with running cvs2svn or problems converting
1066   your repository, the <a
1067   href="mailto:users@cvs2svn.tigris.org"><tt>users@cvs2svn.tigris.org</tt></a>
1068   mailing list is the first place to send inquiries.  Please <a
1069   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">subscribe</a>
1070   to the list so that you can follow ensuing discussions.</li>
1071
1072   <li>You can also ask questions on IRC at <a
1073   href="irc://irc.freenode.net/"><tt>irc.freenode.net</tt></a>,
1074   channel <tt>#cvs2svn</tt>.</li>
1075
1076   <li>If you think you have found a bug, please refer to <a
1077   href="#reportingbugs">"How do I report a bug?"</a></li>
1078
1079 </ul>
1080
1081
1082 <h3><a name="subscribing" title="#subscribing">How do I subscribe to a
1083 mailing list?</a></h3>
1084
1085 <p>It is not so obvious how to subscribe to the cvs2svn mailing
1086 lists.  There are two ways:</p>
1087
1088 <ul>
1089
1090   <li>If you have an account on tigris.org, then you can go to any
1091   cvs2svn project page, click on "Mailing lists" in the "Project
1092   tools" menu on the left-hand column, then click on <a
1093   href="http://cvs2svn.tigris.org/ds/manageSubscriptions.do">"Manage
1094   my subscriptions"</a> (above the list of mailing lists).  On that
1095   page, tick the "Subscribed" checkbox next to the lists to which you
1096   would like to subscribe.</li>
1097
1098   <li>If you do not have a tigris account, then you can subscribe by
1099   sending an email to $LIST-subscribe@cvs2svn.tigris.org, where $LIST
1100   is one of "announce", "users", "dev", issues", or "commits".  Please
1101   be sure to send the email to $LIST-subscribe and not to the list
1102   itself!  (To unsubscribe, send and email to
1103   $LIST-unsubscribe@cvs2svn.tigris.org.)  More details can be found <a
1104   href="http://help.collab.net/index.jsp?topic=/faq/subscribetomailinglistviaemail.html">here</a>.</li>
1105
1106 </ul>
1107
1108
1109 <h3><a name="reportingbugs" title="#reportingbugs">How do I report a
1110 bug?</a></h3>
1111
1112 <p>cvs2svn is an open source project that is largely developed and
1113 supported by volunteers in their free time.  Therefore please try to
1114 help out by reporting bugs in a way that will enable us to help you
1115 efficiently.</p>
1116
1117 <p>The first question is whether the problem you are experiencing is
1118 caused by a cvs2svn bug at all.  A large fraction of reported "bugs"
1119 are caused by problems with the user's CVS repository, especially mild
1120 forms of repository corruption or <a href="#cvsnt">trying to convert a
1121 CVSNT repository with cvs2svn</a>.  Please also double-check the <a
1122 href="cvs2svn.html">manual</a> to be sure that you are using the
1123 command-line options correctly.</p>
1124
1125 <p>A good way to localize potential repository corruption is to use
1126 the <tt>shrink_test_case.py</tt> script (which is located in the
1127 <tt>contrib</tt> directory of the cvs2svn source tree).  This script
1128 tries to find the minimum subset of files in your repository that
1129 still shows the same problem.  <b>Warning: Only apply this script to a
1130 backup copy of your repository, as it destroys the repository that it
1131 operates on!</b> Often this script can narrow the problem down to a
1132 single file which, as often as not, is corrupt in some way.  Even if
1133 the problem is not in your repository, the shrunk-down test case will
1134 be useful for reporting the bug.  Please see <a href="#testcase">"How
1135 can I produce a useful test case?"</a> and the comments at the top of
1136 <tt>shrink_test_case.py</tt> for information about how to use this
1137 script.</p>
1138
1139 <p>Assuming that you still think you have found a bug, the next step
1140 is to investigate whether the bug is already known.  Please look
1141 through the <a
1142 href="http://cvs2svn.tigris.org/issue_tracker.html">issue tracker</a>
1143 for bugs that sound familiar.  If the bug is already known, then there
1144 is no need to report it (though possibly you could contribute a <a
1145 href="#testcase">useful test case</a> or a workaround).</p>
1146
1147 <p>If your bug seems new, then the best thing to do is report it via
1148 email to the <a
1149 href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">dev@cvs2svn.tigris.org</a>
1150 mailing list.  Be sure to include the following information in your
1151 message:</p>
1152
1153 <ol>
1154
1155   <li><em>Exactly what version</em> of cvs2svn are you using?  If you
1156   are not using an official release, please tell us what branch and
1157   revision number from the <a
1158   href="http://cvs2svn.tigris.org/svn/cvs2svn/">svn archive</a> you
1159   are using.  If you have modified cvs2svn, please tell us exactly
1160   what you have changed.</li>
1161
1162   <li>What platform are you using (Linux, BSD, Windows, etc.)?  What
1163   python version (e.g., type <tt>python --version</tt>)?</li>
1164
1165   <li>What is the <em>exact command line</em> that you used to start
1166   the conversion?  If you used the <tt>--options</tt> option, please
1167   attach a copy of the options file that you used.</li>
1168
1169   <li>What happened when you ran the program?  Why do you think the
1170   behavior was wrong?  Include transcripts and/or error output if
1171   available.</li>
1172
1173   <li>If at all possible, include a test case repository that we can
1174   use to reproduce the problem.  See <a href="#testcase">"How can I
1175   produce a useful test case?"</a> for more information.  In most
1176   cases, if we cannot reproduce the problem, there is nothing we can
1177   do to help you.</li>
1178
1179 </ol>
1180
1181
1182 <h3><a name="testcase" title="#testcase">How can I produce a useful
1183 test case?</a></h3>
1184
1185 <p>If you need to <a href="#reportingbugs">report a bug</a>, it is
1186 extremely helpful if you can include a test repository with your bug
1187 report.  In most cases, if we cannot reproduce the problem, there is
1188 nothing we can do to help you.  This section describes ways to
1189 overcome the most common problems that people have in producing a
1190 useful test case.  When you have a reasonable-sized test case (say
1191 under 1 MB--the smaller the better), you can just tar it up and attach
1192 it to the email in which you report the bug.</p>
1193
1194 <h4>If the repository is too big and/or contains proprietary information</h4>
1195
1196 <p>You don't want to send us your proprietary information, and we
1197 don't want to receive it either.  Short of open-sourcing your
1198 software, here is a way to strip out most of the proprietary
1199 information and simultaneously reduce the size of the archive
1200 tremendously.</p>
1201
1202 <p>The <tt>destroy_repository.py</tt> script tries to delete as much
1203 information as possible out of your repository while still preserving
1204 its basic structure (and therefore hopefully any cvs2svn bugs).
1205 Specifically, it tries to delete file descriptions, text content, all
1206 nontrivial log messages, and all author names.  It also renames all
1207 files and directories to have generic names (e.g.,
1208 <tt>dir015/file053,v</tt>).  (It does not affect the number and dates
1209 of revisions to the files.)</p>
1210
1211 <ol>
1212
1213   <li>This procedure will <b>destroy the repository</b> that it is
1214   applied to, so be sure to <b>make a backup copy of your
1215   repository and work with the backup!</b></li>
1216
1217   <li>Make sure you have the <tt>destroy_repository.py</tt> script.
1218   If you don't already have it, you should <a
1219   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
1220   source code</a> for cvs2svn (there is no need to install it).  The
1221   script is located in the <tt>contrib</tt> subdirectory.</li>
1222
1223   <li>Run <tt>destroy_repository.py</tt> by typing <pre>
1224 # You did make a backup, right?
1225 /path/to/config/destroy_repository.py /path/to/copy/of/repo
1226 </pre></li>
1227
1228   <li>Verify that the "destroyed" archive does not include any
1229   information that you consider proprietary.  Your data security is
1230   ultimately your responsibility, and we make no guarantees that the
1231   <tt>destroy_repository.py</tt> script works correctly.  You can open
1232   the *,v files using a text editor to see what they contain.</li>
1233
1234   <li>Try converting the "destroyed" repository using cvs2svn, and
1235   ensure that the bug still exists.  Take a note of the exact cvs2svn
1236   command line that you used and include it along with a tarball of
1237   the "destroyed" repository with your bug report.</li>
1238
1239 </ol>
1240
1241 <p>If running <tt>destroy_repository.py</tt> with its default options
1242 causes the bug to go away, consider using
1243 <tt>destroy_repository.py</tt> command-line options to leave part of
1244 the repository information intact.  Run <tt>destroy_repository.py
1245 --help</tt> for more information.</p>
1246
1247
1248 <h4>The repository is still too large</h4>
1249
1250 <p>This step is a tiny bit more work, so if your repository is already
1251 small enough to send you can skip this step.  But this step helps
1252 narrow down the problem (maybe even point you to a corrupt file in
1253 your repository!) so it is still recommended.</p>
1254
1255 <p>The <tt>shrink_test_case.py</tt> script tries to delete as many
1256 files and directories from your repository as possible while
1257 preserving the cvs2svn bug.  To use this command, you need to write a
1258 little test script that tries to convert your repository and checks
1259 whether the bug is still present.  The script should exit successfully
1260 (e.g., "<tt>exit 0</tt>") if the bug is still <em>present</em>, and
1261 fail (e.g., "<tt>exit 1</tt>") if the bug has <em>disappeared</em>.
1262 The form of the test script depends on the bug that you saw, but it
1263 can be as simple as something like this:</p>
1264
1265 <pre>
1266 #! /bin/sh
1267
1268 cvs2svn --dry-run /path/to/copy/of/repo 2>&amp;1 | grep -q 'KeyError'
1269 </pre>
1270
1271 <p>If the bug is more subtle, then the test script obviously needs to
1272 be more involved.</p>
1273
1274 <p>Once the test script is ready, you can shrink your repository via
1275 the following steps:</p>
1276
1277 <ol>
1278
1279   <li>This procedure will <b>destroy the repository</b> that it is
1280   applied to, so be sure to <b>make a backup copy of your
1281   repository and work with the backup!</b></li>
1282
1283   <li>Make sure you have the <tt>shrink_test_case.py</tt> script.
1284   If you don't already have it, you should <a
1285   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
1286   source code</a> for cvs2svn (there is no need to install it).  The
1287   script is located in the <tt>contrib</tt> subdirectory.</li>
1288
1289   <li>Run <tt>shrink_test_case.py</tt> by typing <pre>
1290 # You did make a backup, right?
1291 /path/to/config/shrink_test_case.py /path/to/copy/of/repo testscript.sh
1292 </pre>, where <tt>testscript.sh</tt> is the name of the test script
1293   described above.  This script will execute <tt>testscript.sh</tt>
1294   many times, each time using a subset of the original repository.</li>
1295
1296   <li>If the shrunken repository only consists of one or two files,
1297   look inside the files with a text editor to see whether they are
1298   corrupted in any obvious way.  (Many so-called cvs2svn "bugs" are
1299   actually the result of a corrupt CVS repository.)</li>
1300
1301   <li>Try converting the "shrunk" repository using cvs2svn, to make
1302   sure that the original bug still exists.  Take a note of the exact
1303   cvs2svn command line that you used, and include it along with a
1304   tarball of the "destroyed" repository with your bug report.</li>
1305
1306 </ol>
1307
1308
1309 <h3><a name="commercialsupport" title="#commercialsupport">Does
1310 anybody offer commercial support for cvs2svn/cvs2git
1311 conversions?</a></h3>
1312
1313 <p><b>Disclaimer:</b>These links in this section are provided as a
1314 service to cvs2svn/cvs2git users.  Neither Tigris.org, CollabNet
1315 Inc., nor the cvs2svn team guarantee the correctness, validity or
1316 usefulness of these links.  To add a link to this section, please
1317 submit it to the cvs2svn developers' mailing list.</p>
1318
1319 <p>Following is a list of known sources for commercial support for
1320 cvs2svn/cvs2git conversions:</p>
1321
1322 <ul>
1323
1324   <li>Michael Haggerty, the maintainer of cvs2svn/cvs2git, offers
1325   individual help with conversions, including implementation of new
1326   cvs2svn/cvs2git features, on a consulting basis.  Please contact
1327   Michael <a href="email:mhagger@alum.mit.edu">via email</a> for more
1328   information.</li>
1329
1330 </ul>
1331
1332
1333 </div>
1334 </body>
1335 </html>