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 adding just a little bit of Python code to your <a
 607     href="cvs2svn.html#options-file-method">options file</a>.</p>
 608
 609   <p>When a symbol is encountered, cvs2svn iterates through the list
 610     of <tt>SymbolTransform</tt> objects defined for the project.  For
 611     each one, it calls <tt>symbol_transform.transform(cvs_file,
 612     symbol_name, revision)</tt>.  That method can return
 613     any legal symbol name, which will be used in the conversion
 614     instead of the original name.</p>
 615
 616   <p>To use this feature, you will have to use
 617     an <a href="cvs2svn.html#options-file-method">options file</a> to
 618     start the conversion.  You then write a new SymbolTransform class
 619     that inherits from RegexpSymbolTransform but checks the path
 620     before deciding whether to transform the symbol.  You can do
 621     something like the following:</p>
 622
 623 <pre>
 624 from cvs2svn_lib.symbol_transform import RegexpSymbolTransform
 625
 626 class MySymbolTransform(RegexpSymbolTransform):
 627     def __init__(self, path, pattern, replacement):
 628         """Transform only symbols that occur within the specified PATH."""
 629
 630         self.path = path
 631         RegexpSymbolTransform.__init__(self, pattern, replacement)
 632
 633     def transform(self, cvs_file, symbol_name, revision):
 634         # Is the file is within the path we are interested in?
 635         if cvs_file.cvs_path.startswith(path + '/'):
 636             # Yes -> Allow RegexpSymbolTransform to transform the symbol:
 637             return RegexpSymbolTransform.transform(
 638                     self, cvs_file, symbol_name, revision)
 639         else:
 640             # No -> Return the symbol unchanged:
 641             return symbol_name
 642
 643 # Note that we use a Python loop to fill the list of symbol_transforms:
 644 symbol_transforms = []
 645 for subdir in ['project1', 'project2', 'project3']:
 646     symbol_transforms.append(
 647         MySymbolTransform(
 648             subdir,
 649             r'release-(\d+)_(\d+)',
 650             r'%s-release-\1.\2' % subdir))
 651
 652 # Now register the project, using our own symbol transforms:
 653 run_options.add_project(
 654     'your_cvs_path',
 655     trunk_path='trunk',
 656     branches_path='branches',
 657     tags_path='tags',
 658     symbol_transforms=symbol_transforms))
 659 </pre>
 660
 661   <p>Please note that <a href="#options-code">the class must be
 662     defined in a separate file</a>.</p>
 663
 664   <p>This example causes any symbol under "project1" that looks like
 665     "release-3_12" to be transformed into a symbol named
 666     "project1-release-3.12", whereas if the same symbol appears under
 667     "project2" it will be transformed into
 668     "project2-release-3.12".</p>
 669
 670
 671 <h3><a name="cvsnt" title="#cvsnt">How can I convert a CVSNT
 672     repository?</a></h3>
 673
 674   <p><a href="http://www.cvsnt.org/">CVSNT</a> is a version control
 675     system that started out by adding support for running CVS under
 676     Windows NT.  Since then it has made numerous extensions to the RCS
 677     file format, to the point where CVS compatibility does not imply
 678     CVSNT compatibility with any degree of certainty.</p>
 679
 680   <p>cvs2svn <em>might</em> happen to successfully convert a CVSNT
 681     repository, especially if the repository has never had any
 682     CVSNT-only features used on it, but <b>this use is not supported
 683     and should not be expected to work</b>.</p>
 684
 685   <p>If you want to experiment with converting a CVSNT repository,
 686     then please consider the following suggestions:</p>
 687
 688   <ul>
 689     <li>Use cvs2svn's <tt>--use-cvs</tt> option.</li>
 690
 691     <li>Use CVSNT's version of the <tt>cvs</tt> executable (i.e.,
 692       ensure that the first <tt>cvs</tt> program in your $PATH is the
 693       one that came with CVSNT).</li>
 694
 695     <li>Carefully check the result of the conversion before you rely
 696       on it, <em>even if the conversion completed without any
 697       errors or warnings</em>.</li>
 698
 699   </ul>
 700
 701   <p>Patches to support the conversion of CVSNT repositories would, of
 702     course, be welcome.</p>
 703
 704
 705 <h3><a name="osxsetup" title="#osxsetup">How do I get cvs2svn to run
 706 on OS X 10.5.5?</a></h3>
 707
 708 <p>Attempting to run cvs2svn on a standard OS X 10.5.5 installation
 709 yields the following error:</p>
 710
 711 <blockquote> <p> ERROR: cvs2svn uses the anydbm package, which depends on
 712 lower level dbm libraries.  Your system has dbm, with which cvs2svn is
 713 known to have problems.  To use cvs2svn, you must install a Python dbm
 714 library other than dumbdbm or dbm.  See <a
 715 href="http://python.org/doc/current/lib/module-anydbm.html">http://python.org/doc/current/lib/module-anydbm.html</a>
 716 for more information. </p> </blockquote>
 717
 718 <p>The problem is that the standard distribution of python on OS X
 719 10.5.5 does not include any other dbm libraries other than the
 720 standard dbm.  In order for cvs2svn to work, we need to install the
 721 gdbm library, in addition to a new version of python that enables the
 722 python gdbm module.</p>
 723
 724 <p>The precompiled versions of python for OS X available from
 725 python.org or activestate.com (currently version 2.6.2) do not have
 726 gdbm support turned on.  To check for gdbm support, check for the
 727 library module (<code>libgdmmodule.so</code>) within the python
 728 installation.</p>
 729
 730 <p>Here is the procedure for a successful installation of cvs2svn and
 731 all supporting libs:</p>
 732
 733 <ol>
 734
 735   <li>Download the gdbm-1.8.3 (or greater) source, unarchive and
 736     change directory to gdbm-1.8.3. We need to install the gdbm
 737     libraries so python's gdbm module can use them.
 738
 739   <ol>
 740
 741     <li>Type <code>./configure</code></li>
 742
 743     <li>Edit "Makefile" so that the owner and group are not the
 744         non-existing "bin" owner and group by changing
 745
 746 <pre>
 747 BINOWN = bin
 748 BINGRP = bin
 749 </pre>
 750 to
 751 <pre>
 752 BINOWN = root
 753 BINGRP = admin
 754 </pre>
 755
 756     </li>
 757
 758     <li>Type "make"</li>
 759
 760     <li>Type "sudo make install"</li>
 761
 762   </ol>
 763
 764   </li>
 765
 766   <li>Download the Python2.6 (or greater) source, unarchive, and
 767   change directory to Python2.6.  We need to enable python gdbm
 768   support which is not enabled in the default OS X 10.5.5 installation
 769   of python, as the gdbm libs are not included.  However, we just
 770   installed the gdbm libs in step 1, so we can now compile python with
 771   gdbm support.
 772
 773   <ol>
 774
 775     <li>Edit the file "Modules/Setup" by uncommenting the line which
 776       links against gdbm by changing
 777
 778 <pre>
 779 #gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 780 </pre>
 781 to
 782 <pre>
 783 gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 784 </pre>
 785     </li>
 786
 787     <li>Edit the file "Modules/Setup" by uncommenting the line to
 788       create shared libs by changing
 789
 790 <pre>
 791 #*shared*
 792 </pre>
 793 to
 794 <pre>
 795 *shared*
 796 </pre>
 797     </li>
 798
 799     <li>Type <code>./configure --enable-framework
 800     --enable-universalsdk</code> in the top-level
 801     Python2.6 directory.  This will configure the installation of
 802     python as a shared OS X framework, and usable with OS X GUI
 803     frameworks and SDKs. You may have problems building if you don't
 804     have the SDKs that support the PPC platform. If you do, just
 805     specify <code>--disable-universalsdk</code>.
 806     By default, python will be installed in
 807     "/Library/Frameworks/Python.framework", which is what we
 808     want.</li>
 809
 810     <li>Type <code>make</code></li>
 811
 812     <li>Type <code>sudo make install</code></li>
 813
 814     <li>Type <code>cd /usr/local/bin; sudo ln -s python2.6 python</code></li>
 815
 816     <li>Make sure "/usr/local/bin" is at the front of your search path
 817     in ~/.profile or ~/.bashrc etc.</li>
 818
 819     <li>Type <code>source ~/.profle</code> or <code>source
 820     ~/.bashrc</code> etc. or alternatively, just open a new shell
 821     window.  When you type <code>which python</code> it should give
 822     you the new version in "/usr/local/bin" <strong>not</strong> the
 823     one in "/usr/bin".</li>
 824
 825   </ol>
 826
 827   </li>
 828
 829   <li>Download the cvs2svn-2.2.0 (or greater) source, unarchive and
 830   change directory to cvs2svn-2.2.0.  Many people can't get cvs2svn to
 831   work except in the installation directory.  The reason for this is
 832   that the installation places copies of cvs2svn, cvs2svn_libs, and
 833   cvs2svn_rcsparse in the /Library/Frameworks/Python.framework
 834   hierarchy.  All we need to do is make a link in /usr/local/bin
 835   pointing to the location of cvs2svn in the python framework
 836   hierarchy.  And for good measure we also make links to the lib and
 837   include directories:
 838
 839   <ol>
 840
 841     <li>Type <code>sudo make install</code></li>
 842
 843     <li>Create the required links by typing the following:
 844
 845 <pre>
 846 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/bin/cvs2svn /usr/local/bin/cvs2svn
 847 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6 /usr/local/lib/python2.6
 848 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/include/python2.6 /usr/local/include/python2.6
 849 </pre>
 850
 851     </li>
 852
 853   </ol>
 854
 855   </li>
 856
 857 </ol>
 858
 859 <p>The installation is complete. Change directory out of the
 860 cvs2svn-2.2.0 installation directory, and you should be able to run
 861 cvs2svn. Be careful *not* to copy the version of cvs2svn in the
 862 cvs2svn-2.2.0 installation directory to /usr/local/bin, as this has a
 863 different python environment setting at the top of the file than the
 864 one that was installed in the /Library/Frameworks/Python.framework
 865 hierarchy. Follow the instructions exactly, and it should work.
 866 </p>
 867
 868
 869 <hr />
 870
 871 <h2>Problems:</h2>
 872
 873 <h3><a name="atticprob" title="#atticprob">I get an error "A CVS
 874     repository cannot contain both repo/path/file.txt,v and
 875     repo/path/Attic/file.txt,v".  What can I do?</a></h3>
 876
 877 <p>Background: Normally, if you have a file called
 878 <tt>path/file.txt</tt> in your project, CVS stores its history in a
 879 file called <tt>repo/path/file.txt,v</tt>.  But if <tt>file.txt</tt>
 880 is deleted on the main line of development, CVS moves its history file
 881 to a special <tt>Attic</tt> subdirectory:
 882 <tt>repo/path/Attic/file.txt,v</tt>.  (If the file is recreated, then
 883 it is moved back out of the <tt>Attic</tt> subdirectory.)  Your
 884 repository should never contain both of these files at the same
 885 time.</p>
 886
 887 <p>This cvs2svn error message thus indicates a mild form of corruption
 888 in your CVS repository.  The file has two conflicting histories, and
 889 even CVS does not know the correct history of <tt>path/file.txt</tt>.
 890 The corruption was probably created by using tools other than CVS to
 891 backup or manipulate the files in your repository.  With a little work
 892 you can learn more about the two histories by viewing each of the
 893 <tt>file.txt,v</tt> files in a text editor.</p>
 894
 895 <p>There are four straightforward approaches to fixing the repository
 896 corruption, but each has potential disadvantages.  Remember to <b>make
 897 a backup</b> before starting.  Never run cvs2svn on a live CVS
 898 repository--always work on a copy of your repository.</p>
 899
 900 <ol>
 901   <li>Restart the conversion with the
 902     <tt>--retain-conflicting-attic-files</tt> option.  This causes the
 903     non-attic and attic versions of the file to be converted
 904     separately, with the <tt>Attic</tt> version stored to a new
 905     subdirectory as <tt>path/Attic/file.txt</tt>.  This approach
 906     avoids losing any history, but by moving the <tt>Attic</tt>
 907     version of the file to a different subdirectory it might cause
 908     historical revisions to be broken.</li>
 909
 910   <li>Remove the <tt>Attic</tt> version of the file and restart the
 911     conversion.  Sometimes it represents an old version of the file
 912     that was deleted long ago, and it won't be missed.  But this
 913     completely discards one of the file's histories, probably causing
 914     <tt>file.txt</tt> to be missing in older historical revisions.
 915     (For what it's worth, this is probably how CVS would behave in
 916     this situation.)
 917
 918     <pre>
 919       # You did make a backup, right?
 920       $ rm repo/path/Attic/file.txt,v
 921     </pre></li>
 922
 923   <li>Remove the non-<tt>Attic</tt> version of the file and restart
 924     the conversion.  This might be appropriate if the
 925     non-<tt>Attic</tt> version has less important content than the
 926     <tt>Attic</tt> version.  But this completely discards one of the
 927     file's histories, probably causing <tt>file.txt</tt> to be missing
 928     in recent historical revisions.
 929
 930     <pre>
 931       # You did make a backup, right?
 932       $ rm repo/path/file.txt,v
 933     </pre></li>
 934
 935   <li>Rename the non-<tt>Attic</tt> version of the file and restart
 936     the conversion.  This avoids losing history, but it changes the
 937     name of the non-<tt>Attic</tt> version of the file to
 938     <tt>file-not-from-Attic.txt</tt> whenever it appeared, and might
 939     thereby cause revisions to be broken.
 940
 941     <pre>
 942       # You did make a backup, right?
 943       $ mv repo/path/file.txt,v repo/path/file-not-from-Attic.txt,v
 944     </pre></li>
 945
 946 </ol>
 947
 948 <p>If you run cvs2svn on a case-insensitive operating system, it is
 949 possible to get this error even if the filename of the file in
 950 Attic has different case than the one out of the Attic.  This could
 951 happen, for example, if the CVS repository was served from a
 952 case-sensitive operating system at some time.  A workaround for this
 953 problem is to copy the CVS repository to a case-sensitive operating
 954 system and convert it there.
 955 </p>
 956
 957
 958 <h3><a name="rcsfileinvalid" title="#rcsfileinvalid">I get an error
 959     "ERROR: <i>filename</i>,v is not a valid ,v file."</a></h3>
 960
 961 <p>The named file is corrupt in some way.  (Corruption is surprisingly
 962 common in CVS repositories.)  It is likely that even CVS has problems
 963 with this file; try checking out the head revision, revision 1.1, and
 964 the tip revision on each branch of this file; probably one or more of
 965 them don't work.</p>
 966
 967 <p>Here are some options:</p>
 968
 969 <ol>
 970
 971   <li>Omit this file from the conversion (by making a copy of your
 972     repository, deleting this file from the copy, then converting from
 973     the copy).</li>
 974
 975   <li>Restore an older copy of this file from backups, if you have
 976     backups from before it was corrupted.</li>
 977
 978   <li>Hand-fix the file as best you can by opening it in a binary
 979     editor and trying to put it back in RCS file format (documented in
 980     the rcsfile(5) manpage).  Often it is older revisions that are
 981     affected by corruption; you might need to delete some old
 982     revisions to salvage newer ones.</li>
 983
 984 </ol>
 985
 986
 987 <h3><a name="gdbm-nfs" title="#gdbm-nfs">gdbm.error: (45, 'Operation
 988     not supported')</a></h3>
 989
 990 <p>This has been reported to be caused by trying to create gdbm
 991 databases on an NFS partition.  Apparently gdbm does not support
 992 databases on NFS partitions.  The workaround is to use the
 993 <tt>--tmpdir</tt> option to choose a local partition for cvs2svn to
 994 write its temporary files.</p>
 995
 996
 997 <h3><a name="apple-single" title="#apple-single">When converting a CVS
 998     repository that was used on a Macintosh, the contents of some
 999     files are incorrect in SVN.</a></h3>
1000
1001 <p>Some Macintosh CVS clients use a nonstandard trick to store the
1002 resource fork of files in CVS: instead of storing the file contents
1003 directly, store an <a
1004 href="http://rfc.net/rfc1740.html">AppleSingle</a> data stream
1005 containing both the data fork and resource fork.  When checking the
1006 file out, the client unpacks the AppleSingle data and writes the two
1007 forks separately to disk.  By default, cvs2svn treats the file
1008 contents literally, so when you check the file out of Subversion, the
1009 file contains the combined data in AppleSingle format rather than only
1010 the data fork of the file as expected.</p>
1011
1012 <p>Subversion does not have any special facilities for dealing with
1013 Macintosh resource forks, so there is nothing cvs2svn can do to
1014 preserve both forks of your data.  However, sometimes the resource
1015 fork is not needed.  If you would like to discard the resource fork
1016 and only record the data fork in Subversion, then start your
1017 conversion using the <a
1018 href="cvs2svn.html#options-file-method">options file method</a> and
1019 set the following option to <tt>True</tt> in your options file:</p>
1020
1021 <pre>
1022       ctx.decode_apple_single = True
1023 </pre>
1024
1025 <p>There is more information about this option in the comments in
1026 <tt>cvs2svn-example.options</tt>.</p>
1027
1028
1029 <h3><a name="rcsmissing" title="#installrcs">Using cvs2svn 1.3.x, I
1030     get an error "The command '['co', '-q', '-x,v', '-p1.1', '-kk',
1031     '/home/cvsroot/myfile,v']' failed" in pass 8.</a></h3>
1032
1033 <p><i>What are you using cvs2svn version 1.3.x for anyway?
1034 Upgrade!</i></p>
1035
1036 <p>But if you must, either install RCS, or ensure that CVS is
1037 installed and use cvs2svn's <a
1038 href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt></a> option.</p>
1039
1040
1041 <h3><a name="nonstandardntdb" title="#nonstandardntdb">Vendor
1042     branches created with "cvs import -b &lt;branch number&gt;"
1043     are not correctly handled.</a></h3>
1044
1045 <p>Normally, people using "cvs import" don't specify the
1046 "-b" flag.  cvs2svn handles this normal case fine.</p>
1047
1048 <p>If you have a file which has an <i>active</i> vendor branch, i.e.
1049 there have never been any trunk commits but only "cvs imports" onto
1050 the vendor branch, then cvs2svn will handle this fine.  (Even if
1051 you've used the "-b" option to specify a non-standard branch
1052 number).</p>
1053
1054 <p>If you've used "cvs import -b &lt;branch number&gt;", you didn't
1055 specify the standard CVS vendor branch number of 1.1.1, and there
1056 has since been a commit on trunk (either a modification or delete),
1057 then your history has been damaged.  This isn't cvs2svn's fault.
1058 CVS simply doesn't record the branch number of the old vendor branch,
1059 it assumes it was 1.1.1.  You will even get the wrong results from
1060 "cvs checkout -D" with a date when the vendor branch was active.</p>
1061
1062 <p>Symptoms of this problem can include:</p>
1063
1064 <ul>
1065 <li>cvs2svn refusing to let you exclude the vendor branch, because
1066 some other branch depends on it</li>
1067 <li>if you did more than one import onto the vendor branch, then
1068 your SVN history "missing" one of the changes on trunk (though
1069 the change will be on the vendor branch).</li>
1070 </ul>
1071
1072 <p>(Note: There are other possible causes for these symptoms, don't
1073 assume you have a non-standard vendor branch number just because
1074 you see these symptoms).</p>
1075
1076 <p>The way to solve this problem is to renumber the vendor branch to
1077 the standard 1.1.1 branch number.  This has to be done before you run
1078 cvs2svn.  To help you do this, there is the "renumber_branch.py"
1079 script in the "contrib" directroy of the cvs2svn distribution.</p>
1080
1081 <p>The typical usage, assuming you used "cvs import -b 1.1.2 ..."
1082 to create your vendor branch, is:</p>
1083 <pre>
1084       contrib/renumber_branch.py 1.1.2 1.1.1 repos/dir/file,v
1085 </pre>
1086 <p>You should only run this on a <b>copy</b> of your CVS repository,
1087 as it edits the repository in-place.  You can fix a single file or a
1088 whole directory tree at a time.</p>
1089
1090 <p>The script will check that the 1.1.1 branch doesn't already exist;
1091 if it does exist then it will fail with an error message.</p>
1092
1093
1094
1095 <h2>Getting help:</h2>
1096
1097 <h3><a name="gettinghelp" title="#gettinghelp">How do I get
1098 help?</a></h3>
1099
1100 <p>There are several sources of help for cvs2svn:</p>
1101
1102 <ul>
1103
1104   <li>The <a href="cvs2svn.html">user manual</a> not only describes
1105   how to run cvs2svn, but also discusses some limitations, pitfalls,
1106   and conversion strategies.  Please note that the <a
1107   href="http://cvs2svn.tigris.org/cvs2svn.html">online manual</a>
1108   describes the latest "bleeding edge" trunk version of the software,
1109   which may be different than the version that you are using.</li>
1110
1111   <li>The <a href="faq.html">frequently asked questions (FAQ) list</a>
1112   is the document that you are now reading.  Please make sure you've
1113   scanned through the list of topics to see if your question is
1114   already answered.</li>
1115
1116   <li>The <a
1117   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">mailing
1118   list archives</a>.  Maybe your question has already
1119   been discussed on either the <tt>user@cvs2svn.tigris.org</tt> or
1120   <tt>dev@cvs2svn.tigris.org</tt> mailing list.</li>
1121
1122   <li>The <a href="mailto:users@cvs2svn.tigris.org"><tt>users@cvs2svn.tigris.org</tt></a>
1123   mailing list can often help with questions about how to configure
1124   and run cvs2svn, conversion strategies, or problems converting your
1125   repository.
1126   Please <a href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">subscribe</a>
1127   to the list so that you can follow ensuing discussions.  Be sure to
1128   include the information listed in <a href="#infoneeded">"What
1129   information should I include when requesting help?"</a></li>
1130
1131   <li>You can also ask questions
1132   on <a href="irc://irc.freenode.net/#cvs2svn">the <tt>#cvs2svn</tt>
1133   channel on irc.freenode.net</a>.</li>
1134
1135   <li>If you think you have found a bug, please refer to <a
1136   href="#reportingbugs">"How do I report a bug?"</a></li>
1137
1138   <li>For individual help with your conversion (especially for
1139   non-open-source projects), <a href="#commercialsupport">commercial
1140   support is available</a>.</li>
1141
1142 </ul>
1143
1144
1145 <h3><a name="infoneeded" title="#infoneeded">What information should I
1146 include when requesting help?</a></h3>
1147
1148 <p>If you ask for help and/or report a bug on a mailing list, it is
1149 important that you include the following information.  Failure to
1150 include important information is the best way to dissuade the
1151 volunteers of the cvs2svn project from trying to help you.</p>
1152
1153 <ol>
1154
1155   <li><em>Exactly what version</em> of cvs2svn are you using?  If you
1156   are not using an official release, please tell us what branch and
1157   revision number from the <a
1158   href="http://cvs2svn.tigris.org/svn/cvs2svn/">svn archive</a> you
1159   are using.  If you have modified cvs2svn, please tell us exactly
1160   what you have changed.</li>
1161
1162   <li>What platform are you using (Linux, BSD, Windows, etc.)?  What
1163   python version (e.g., type <tt>python --version</tt>)?</li>
1164
1165   <li>What is the <em>exact command line</em> that you used to start
1166   the conversion?  If you used the <tt>--options</tt> option, please
1167   attach a copy of the options file that you used.</li>
1168
1169   <li>What happened when you ran the program?  How did that differ
1170   from what you wanted/expected?  Include transcripts and/or error
1171   output if available.</li>
1172
1173   <li>If you think you have found a bug, try to submit a repository
1174   that we can use to reproduce the problem.
1175   See <a href="#testcase">"How can I produce a useful test case?"</a>
1176   for more information.  In most cases, if we cannot reproduce the
1177   problem, there is nothing we can do to help you.</li>
1178
1179 </ol>
1180
1181
1182 <h3><a name="subscribing" title="#subscribing">How do I subscribe to a
1183 mailing list?</a></h3>
1184
1185 <p>It is not so obvious how to subscribe to the cvs2svn mailing
1186 lists.  There are two ways:</p>
1187
1188 <ul>
1189
1190   <li>If you have an account on tigris.org, then you can go to any
1191   cvs2svn project page, click on "Mailing lists" in the "Project
1192   tools" menu on the left-hand column, then click on <a
1193   href="http://cvs2svn.tigris.org/ds/manageSubscriptions.do">"Manage
1194   my subscriptions"</a> (above the list of mailing lists).  On that
1195   page, tick the "Subscribed" checkbox next to the lists to which you
1196   would like to subscribe.</li>
1197
1198   <li>If you do not have a tigris account, then you can subscribe by
1199   sending an email to $LIST-subscribe@cvs2svn.tigris.org, where $LIST
1200   is one of "announce", "users", "dev", "issues", or "commits".  Please
1201   be sure to send the email to $LIST-subscribe and not to the list
1202   itself!  (To unsubscribe, send and email to
1203   $LIST-unsubscribe@cvs2svn.tigris.org.)  More details can be found <a
1204   href="http://help.collab.net/index.jsp?topic=/faq/subscribetomailinglistviaemail.html">here</a>.</li>
1205
1206 </ul>
1207
1208
1209 <h3><a name="reportingbugs" title="#reportingbugs">How do I report a
1210 bug?</a></h3>
1211
1212 <p>cvs2svn is an open source project that is largely developed and
1213 supported by volunteers in their free time.  Therefore please try to
1214 help out by reporting bugs in a way that will enable us to help you
1215 efficiently.</p>
1216
1217 <p>The first question is whether the problem you are experiencing is
1218 caused by a cvs2svn bug at all.  A large fraction of reported "bugs"
1219 are caused by problems with the user's CVS repository, especially mild
1220 forms of repository corruption or <a href="#cvsnt">trying to convert a
1221 CVSNT repository with cvs2svn</a>.  Please also double-check the <a
1222 href="cvs2svn.html">manual</a> to be sure that you are using the
1223 command-line options correctly.</p>
1224
1225 <p>A good way to localize potential repository corruption is to use
1226 the <tt>shrink_test_case.py</tt> script (which is located in the
1227 <tt>contrib</tt> directory of the cvs2svn source tree).  This script
1228 tries to find the minimum subset of files in your repository that
1229 still shows the same problem.  <b>Warning: Only apply this script to a
1230 backup copy of your repository, as it destroys the repository that it
1231 operates on!</b> Often this script can narrow the problem down to a
1232 single file which, as often as not, is corrupt in some way.  Even if
1233 the problem is not in your repository, the shrunk-down test case will
1234 be useful for reporting the bug.  Please see <a href="#testcase">"How
1235 can I produce a useful test case?"</a> and the comments at the top of
1236 <tt>shrink_test_case.py</tt> for information about how to use this
1237 script.</p>
1238
1239 <p>Assuming that you still think you have found a bug, the next step
1240 is to investigate whether the bug is already known.  Please look
1241 through the <a
1242 href="http://cvs2svn.tigris.org/issue_tracker.html">issue tracker</a>
1243 for bugs that sound familiar.  If the bug is already known, then there
1244 is no need to report it (though possibly you could contribute a <a
1245 href="#testcase">useful test case</a> or a workaround).</p>
1246
1247 <p>If your bug seems new, then the best thing to do is report it via
1248 email to
1249 the <a href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">dev@cvs2svn.tigris.org</a>
1250 mailing list.  Be sure to include the information listed
1251 in <a href="#infoneeded">"What information should I include when
1252 requesting help?"</a></p>
1253
1254
1255 <h3><a name="testcase" title="#testcase">How can I produce a useful
1256 test case?</a></h3>
1257
1258 <p>If you need to <a href="#reportingbugs">report a bug</a>, it is
1259 extremely helpful if you can include a test repository with your bug
1260 report.  In most cases, if we cannot reproduce the problem, there is
1261 nothing we can do to help you.  This section describes ways to
1262 overcome the most common problems that people have in producing a
1263 useful test case.  When you have a reasonable-sized test case (say
1264 under 1 MB--the smaller the better), you can just tar it up and attach
1265 it to the email in which you report the bug.</p>
1266
1267 <h4>If the repository is too big and/or contains proprietary information</h4>
1268
1269 <p>You don't want to send us your proprietary information, and we
1270 don't want to receive it either.  Short of open-sourcing your
1271 software, here is a way to strip out most of the proprietary
1272 information and simultaneously reduce the size of the archive
1273 tremendously.</p>
1274
1275 <p>The <tt>destroy_repository.py</tt> script tries to delete as much
1276 information as possible out of your repository while still preserving
1277 its basic structure (and therefore hopefully any cvs2svn bugs).
1278 Specifically, it tries to delete file descriptions, text content, all
1279 nontrivial log messages, and all author names.  It also renames all
1280 files and directories to have generic names (e.g.,
1281 <tt>dir015/file053,v</tt>).  (It does not affect the number and dates
1282 of revisions to the files.)</p>
1283
1284 <ol>
1285
1286   <li>This procedure will <b>destroy the repository</b> that it is
1287   applied to, so be sure to <b>make a backup copy of your
1288   repository and work with the backup!</b></li>
1289
1290   <li>Make sure you have the <tt>destroy_repository.py</tt> script.
1291   If you don't already have it, you should <a
1292   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
1293   source code</a> for cvs2svn (there is no need to install it).  The
1294   script is located in the <tt>contrib</tt> subdirectory.</li>
1295
1296   <li>Run <tt>destroy_repository.py</tt> by typing <pre>
1297 # You did make a backup, right?
1298 /path/to/config/destroy_repository.py /path/to/copy/of/repo
1299 </pre></li>
1300
1301   <li>Verify that the "destroyed" archive does not include any
1302   information that you consider proprietary.  Your data security is
1303   ultimately your responsibility, and we make no guarantees that the
1304   <tt>destroy_repository.py</tt> script works correctly.  You can open
1305   the *,v files using a text editor to see what they contain.</li>
1306
1307   <li>Try converting the "destroyed" repository using cvs2svn, and
1308   ensure that the bug still exists.  Take a note of the exact cvs2svn
1309   command line that you used and include it along with a tarball of
1310   the "destroyed" repository with your bug report.</li>
1311
1312 </ol>
1313
1314 <p>If running <tt>destroy_repository.py</tt> with its default options
1315 causes the bug to go away, consider using
1316 <tt>destroy_repository.py</tt> command-line options to leave part of
1317 the repository information intact.  Run <tt>destroy_repository.py
1318 --help</tt> for more information.</p>
1319
1320
1321 <h4>The repository is still too large</h4>
1322
1323 <p>This step is a tiny bit more work, so if your repository is already
1324 small enough to send you can skip this step.  But this step helps
1325 narrow down the problem (maybe even point you to a corrupt file in
1326 your repository!) so it is still recommended.</p>
1327
1328 <p>The <tt>shrink_test_case.py</tt> script tries to delete as many
1329 files and directories from your repository as possible while
1330 preserving the cvs2svn bug.  To use this command, you need to write a
1331 little test script that tries to convert your repository and checks
1332 whether the bug is still present.  The script should exit successfully
1333 (e.g., "<tt>exit 0</tt>") if the bug is still <em>present</em>, and
1334 fail (e.g., "<tt>exit 1</tt>") if the bug has <em>disappeared</em>.
1335 The form of the test script depends on the bug that you saw, but it
1336 can be as simple as something like this:</p>
1337
1338 <pre>
1339 #! /bin/sh
1340
1341 cvs2svn --dry-run /path/to/copy/of/repo 2>&amp;1 | grep -q 'KeyError'
1342 </pre>
1343
1344 <p>If the bug is more subtle, then the test script obviously needs to
1345 be more involved.</p>
1346
1347 <p>Once the test script is ready, you can shrink your repository via
1348 the following steps:</p>
1349
1350 <ol>
1351
1352   <li>This procedure will <b>destroy the repository</b> that it is
1353   applied to, so be sure to <b>make a backup copy of your
1354   repository and work with the backup!</b></li>
1355
1356   <li>Make sure you have the <tt>shrink_test_case.py</tt> script.
1357   If you don't already have it, you should <a
1358   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
1359   source code</a> for cvs2svn (there is no need to install it).  The
1360   script is located in the <tt>contrib</tt> subdirectory.</li>
1361
1362   <li>Run <tt>shrink_test_case.py</tt> by typing <pre>
1363 # You did make a backup, right?
1364 /path/to/config/shrink_test_case.py /path/to/copy/of/repo testscript.sh
1365 </pre>, where <tt>testscript.sh</tt> is the name of the test script
1366   described above.  This script will execute <tt>testscript.sh</tt>
1367   many times, each time using a subset of the original repository.</li>
1368
1369   <li>If the shrunken repository only consists of one or two files,
1370   look inside the files with a text editor to see whether they are
1371   corrupted in any obvious way.  (Many so-called cvs2svn "bugs" are
1372   actually the result of a corrupt CVS repository.)</li>
1373
1374   <li>Try converting the "shrunk" repository using cvs2svn, to make
1375   sure that the original bug still exists.  Take a note of the exact
1376   cvs2svn command line that you used, and include it along with a
1377   tarball of the "destroyed" repository with your bug report.</li>
1378
1379 </ol>
1380
1381
1382 <h3><a name="commercialsupport" title="#commercialsupport">Does
1383 anybody offer commercial support for cvs2svn/cvs2git
1384 conversions?</a></h3>
1385
1386 <p><b>Disclaimer:</b>These links in this section are provided as a
1387 service to cvs2svn/cvs2git users.  Neither Tigris.org, CollabNet
1388 Inc., nor the cvs2svn team guarantee the correctness, validity or
1389 usefulness of these links.  To add a link to this section, please
1390 submit it to the cvs2svn developers' mailing list.</p>
1391
1392 <p>Following is a list of known sources for commercial support for
1393 cvs2svn/cvs2git conversions:</p>
1394
1395 <ul>
1396
1397   <li>Michael Haggerty, the maintainer of cvs2svn/cvs2git, offers
1398   individual help with conversions, including implementation of new
1399   cvs2svn/cvs2git features, on a consulting basis.  Please contact
1400   Michael <a href="mailto:mhagger@alum.mit.edu?Subject=cvs2svn%20consulting%20request">via
1401   email</a> for more information.</li>
1402
1403 </ul>
1404
1405
1406 </div>
1407 </body>
1408 </html>