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