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