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