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>How-to:</strong></p>
  21
  22 <ol>
  23
  24   <li><a href="#repoaccess">How can I convert a CVS repository to
  25     which I only have remote access?</a></li>
  26
  27   <li><a href="#oneatatime">How can I convert my CVS repository one
  28     module at a time?</a></li>
  29
  30   <li><a href="#partialconversion">How can I convert part of a CVS
  31     repository?</a></li>
  32
  33   <li><a href="#onetoone">How can I convert separate projects in my
  34     CVS repository into a single Subversion repository?</a></li>
  35
  36   <li><a href="#inverted">How can I convert project <tt>foo</tt> so
  37     that <tt>trunk/tags/branches</tt> are inside of
  38     <tt>foo</tt>?</a></li>
  39
  40   <li><a href="#eol-fixup">How do I fix up end-of-line translation
  41     problems?</a></li>
  42
  43   <li><a href="#path-symbol-transforms">I want a single project but
  44     tag-rewriting rules that vary by subdirectory.  Can this be
  45     done?</a></li>
  46
  47   <li><a href="#cvsnt">How can I convert a CVSNT repository?</a></li>
  48
  49   <li><a href="#osxsetup">How do I get cvs2svn to run on OS X
  50     10.5.5?</a></li>
  51
  52 </ol>
  53
  54 <p><strong>Problems:</strong></p>
  55
  56 <ol>
  57
  58   <li><a href="#atticprob">I get an error "A CVS repository cannot
  59     contain both repo/path/file.txt,v and
  60     repo/path/Attic/file.txt,v".  What can I do?</a></li>
  61
  62   <li><a href="#gdbm-nfs">gdbm.error: (45, 'Operation not supported')</a></li>
  63
  64   <li><a href="#apple-single">When converting a CVS repository that
  65     was used on a Macintosh, some files have incorrect contents in
  66     SVN.</a></li>
  67
  68   <li><a href="#rcsmissing">Using cvs2svn 1.3.x, I get an error "The
  69     command '['co', '-q', '-x,v', '-p1.1', '-kk',
  70     '/home/cvsroot/myfile,v']' failed" in pass 8.</a></li>
  71
  72 </ol>
  73
  74 <p><strong>Getting help:</strong></p>
  75
  76 <ol>
  77
  78   <li><a href="#gettinghelp">How do I get help?</a></li>
  79
  80   <li><a href="#reportingbugs">How do I report a bug?</a></li>
  81
  82   <li><a href="#testcase">How can I produce a useful test case?</a></li>
  83
  84 </ol>
  85
  86 <hr />
  87
  88 <h2>How-to:</h2>
  89
  90 <h3><a name="repoaccess" title="#repoaccess">How can I convert a CVS
  91 repository to which I only have remote access?</a></h3>
  92
  93 <p>cvs2svn requires direct, filesystem access to a copy of the CVS
  94 repository that you want to convert.  The reason for this requirement
  95 is that cvs2svn directly parses the <tt>*,v</tt> files that make up
  96 the CVS repository.</p>
  97
  98 <p>Many remote hosting sites provide access to backups of your CVS
  99 repository, which could be used for a cvs2svn conversion.  For
 100 example:</p>
 101
 102 <ul>
 103   <li><a href="http://sourceforge.net">SourceForge</a> allows CVS
 104     content to be accessed via
 105     <a href="http://sourceforge.net/docs/E04/en/#rsync">rsync</a>.  In
 106     fact, they provide <a
 107     href="http://sourceforge.net/docman/display_doc.php?docid=31070&amp;group_id=1#import">complete instructions</a>
 108     for migrating a SourceForge project from CVS to SVN.</li>
 109   <li>...<i>(other examples welcome)</i></li>
 110 </ul>
 111
 112 <p>If your provider does not provide any way to download your CVS
 113 repository, there is a possible workaround.  The <a
 114 href="http://cvs.m17n.org/~akr/cvssuck/">CVSsuck</a> tool claims to be
 115 able to mirror a remote CVS repository using only CVS commands.  It
 116 should be possible to use this tool to fetch a copy of your CVS
 117 repository from your provider, then to use cvs2svn to convert the
 118 copy.  However, the developers of cvs2svn do not have any experience
 119 with this tool, so you are on your own here.  If you try this method,
 120 please tell us about your experience on the <a
 121 href="mailto:users@cvs2svn.tigris.org">users mailing list</a>.</p>
 122
 123
 124 <h3><a name="oneatatime" title="#oneatatime">How can I convert my CVS
 125 repository one module at a time?</a></h3>
 126
 127 <p>If you need to convert certain CVS modules (in one large
 128 repository) to Subversion <b>now</b> and other modules <b>later</b>,
 129 you may want to convert your repository one module at a time.  This
 130 situation is typically encountered in large organizations where each
 131 project has a separate lifecycle and schedule, and a one-step
 132 conversion process is not practical.
 133 </p>
 134
 135 <p>First you have to decide whether you want to put your converted
 136 projects into a single Subversion repositories or multiple ones.  This
 137 decision mostly depends on the degree of coupling between the projects
 138 and is beyond the scope of this FAQ.  See <a
 139 href="http://svnbook.red-bean.com/en/1.2/svn.reposadmin.projects.html#svn.reposadmin.projects.chooselayout">the
 140 Subversion book</a> for a discussion of repository organization.
 141 </p>
 142
 143 <p>If you decide to convert your projects into separate Subversion
 144 repositories, then please follow the instructions in <a
 145 href="#partialconversion">How can I convert part of a CVS
 146 repository?</a> once for each repository.
 147 </p>
 148
 149 <p>If you decide to put more than one CVS project into a single
 150 Subversion repository, then please follow the instructions in <a
 151 href="#onetoone">How can I convert separate projects in my CVS
 152 repository into a single Subversion repository?</a>.
 153 </p>
 154
 155
 156 <h3><a name="partialconversion" title="#partialconversion">How can I
 157 convert part of a CVS repository?</a></h3>
 158
 159 <p>This is easy: simply run cvs2svn normally, passing it the path of
 160 the project subdirectory within the CVS repository.  Since cvs2svn
 161 ignores any files outside of the path it is given, other projects
 162 within the CVS repository will be excluded from the conversion.
 163 </p>
 164
 165 <p>Example: You have a CVS repository at path <tt>/path/cvsrepo</tt>
 166 with projects in subdirectories <tt>/path/cvsrepo/foo</tt> and
 167 <tt>/path/cvsrepo/bar</tt>, and you want to create a new Subversion
 168 repository at <tt>/path/foo-svn</tt> that includes only the
 169 <tt>foo</tt> project:
 170 </p>
 171
 172 <pre>
 173     $ cvs2svn -s /path/foo-svn /path/cvsrepo/foo
 174 </pre>
 175
 176
 177
 178 <h3><a name="onetoone" title="#onetoone">How can I convert separate
 179 projects in my CVS repository into a single Subversion
 180 repository?</a></h3>
 181
 182 <p>cvs2svn supports multiproject conversions, but you have to use the
 183 <a href="cvs2svn.html#options-file-method">options file method</a> to
 184 start the conversion.  In your options file, you simply call
 185 <tt>run_options.add_project()</tt> once for each sub-project in your
 186 repository.  For example, if your CVS repository has the layout:</p>
 187
 188 <pre>
 189   /project_a
 190   /project_b
 191 </pre>
 192
 193   <p>and you want your Subversion repository to be laid out like this:</p>
 194
 195 <pre>
 196    project_a/
 197       trunk/
 198          ...
 199       branches/
 200          ...
 201       tags/
 202          ...
 203    project_b/
 204       trunk/
 205          ...
 206       branches/
 207          ...
 208       tags/
 209          ...
 210 </pre>
 211
 212 <p>then you need to have a section like this in your options file:</p>
 213
 214 <pre>
 215 run_options.add_project(
 216     'my/cvsrepo/project_a',
 217     trunk_path='project_a/trunk',
 218     branches_path='project_a/branches',
 219     tags_path='project_a/tags',
 220     symbol_transforms=[
 221         #...whatever...
 222         ],
 223     symbol_strategy_rules=[
 224         #...whatever...
 225         ],
 226     )
 227 run_options.add_project(
 228     'my/cvsrepo/project_b',
 229     trunk_path='project_b/trunk',
 230     branches_path='project_b/branches',
 231     tags_path='project_b/tags',
 232     symbol_transforms=[
 233         #...whatever...
 234         ],
 235     symbol_strategy_rules=[
 236         #...whatever...
 237         ],
 238     )
 239 </pre>
 240
 241 <h3><a name="inverted" title="#inverted">How can I convert project
 242     <tt>foo</tt> so that <tt>trunk/tags/branches</tt> are inside of
 243     <tt>foo</tt>?</a></h3>
 244
 245   <p>If <tt>foo</tt> is the only project that you want to convert,
 246     then either run cvs2svn like this:</p>
 247
 248 <pre>
 249    $ cvs2svn --trunk=foo/trunk --branches=foo/branches --tags=foo/tags CVSREPO/foo
 250 </pre>
 251
 252   <p>or use an options file that defines a project like this:</p>
 253
 254 <pre>
 255 run_options.add_project(
 256     'my/cvsrepo/foo',
 257     trunk_path='foo/trunk',
 258     branches_path='foo/branches',
 259     tags_path='foo/tags',
 260     symbol_transforms=[
 261         #...whatever...
 262         ],
 263     symbol_strategy_rules=[
 264         #...whatever...
 265         ],
 266     )
 267 </pre>
 268
 269   <p>If <tt>foo</tt> is not the only project that you want to convert,
 270     then you need to do a multiproject conversion; see <a
 271     href="#onetoone">How can I convert separate projects in my CVS
 272     repository into a single Subversion repository?</a> for more
 273     information.</p>
 274
 275
 276 <h3><a name="eol-fixup" title="#eol-fixup">How do I fix up end-of-line
 277   translation problems?</a></h3>
 278
 279   <p>Warning: cvs2svn's handling of end-of-line options changed
 280     between version 1.5.x and version 2.0.x.  <strong>This
 281     documentation applies to version 2.0.x and later.</strong>  The
 282     documentation applying to an earlier version can be found in the
 283     <tt>www</tt> directory of that release of cvs2svn.</p>
 284
 285   <p>Starting with version 2.0, the default behavior of cvs2svn is to
 286     treat all files as binary except those explicitly determined to be
 287     text.  (Previous versions treated files as text unless they were
 288     determined to be binary.)  This behavior was changed because,
 289     generally speaking, it is safer to treat a text file as binary
 290     than vice versa.</p>
 291
 292   <p>However, it is often preferred to set
 293     <tt>svn:eol-style=native</tt> for text files, so that their
 294     end-of-file format is converted to that of the client platform
 295     when the file is checked out.  This section describes how to
 296     get the settings that you want.</p>
 297
 298   <p>If a file is marked as binary in CVS (with <tt>cvs admin
 299     -kb</tt>, then cvs2svn will always treat the file as binary.  For
 300     other files, cvs2svn has a number of options that can help choose
 301     the correct end-of-line translation parameters during the
 302     conversion:</p>
 303
 304     <table border="1" cellpadding="10" cellspacing="3" width="80%">
 305
 306       <tr>
 307         <td align="right"><tt>--auto-props=FILE</tt></td>
 308         <td>
 309
 310           <p>Set arbitrary Subversion properties on files based on the
 311             auto-props section of a file in svn config format.  The
 312             auto-props file might have content like this:</p>
 313
 314 <pre>
 315 [auto-props]
 316 *.txt = svn:mime-type=text/plain;svn:eol-style=native
 317 *.doc = svn:mime-type=application/msword;!svn:eol-style
 318 </pre>
 319
 320           <p>This option can also be used in combination with
 321             <tt>--eol-from-mime-type</tt>.</p>
 322
 323           <p>To force end-of-line translation off, use a setting of
 324             the form <tt>!svn:eol-style</tt> (with a leading
 325             exclamation point).</p>
 326
 327         </td>
 328       </tr>
 329
 330       <tr>
 331         <td align="right"><tt>--mime-types=FILE</tt></td>
 332         <td><p>Specifies an Apache-style mime.types file for setting
 333           files' <tt>svn:mime-type</tt> property based on the file
 334           extension.  The mime-types file might have content like
 335           this:</p>
 336 <pre>
 337 text/plain              txt
 338 application/msword      doc
 339 </pre>
 340           <p>This option only has an effect on <tt>svn:eol-style</tt>
 341           if it is used in combination with
 342           <tt>--eol-from-mime-type</tt>.</p></td>
 343       </tr>
 344
 345       <tr>
 346         <td align="right"><tt>--eol-from-mime-type</tt></td>
 347         <td>Set <tt>svn:eol-style</tt> based on the file's mime type
 348           (if known).  If the mime type starts with "<tt>text/</tt>",
 349           then the file is treated as a text file; otherwise, it is
 350           treated as binary.  This option is useful in combination with
 351           <tt>--auto-props</tt> or <tt>--mime-types</tt>.</td>
 352       </tr>
 353
 354       <tr>
 355         <td align="right"><tt>--default-eol=STYLE</tt></td>
 356         <td>Usually cvs2svn treats a file as binary unless one of the
 357           other rules determines that it is not binary and it is not
 358           marked as binary in CVS.  But if this option is specified,
 359           then cvs2svn uses the specified style as the default.  STYLE
 360           can be 'binary' (default), 'native', 'CRLF', 'LF', or 'CR'.
 361           If you have been diligent about annotating binary files in
 362           CVS, or if you are confident that the above options will
 363           catch all of your binary files, then
 364           <tt>--default-style=native</tt> should give good
 365           results.</td>
 366       </tr>
 367
 368     </table>
 369
 370   <p>If you don't use any of these options, then cvs2svn will not
 371     arrange any line-end translation whatsoever.  The file contents in
 372     the SVN repository should be the same as the contents you would
 373     get if checking out with CVS on the machine on which cvs2svn is
 374     run.  This also means that the EOL characters of text files will
 375     be the same no matter where the SVN data are checked out (i.e.,
 376     not translated to the checkout machine's EOL format).</p>
 377
 378   <p>To do a better job, you can use <tt>--auto-props</tt>,
 379     <tt>--mime-types</tt>, and <tt>--eol-from-mime-type</tt> to
 380     specify exactly which properties to set on each file based on its
 381     filename.</p>
 382
 383   <p>For total control over setting properties on files, you can use
 384     the <a
 385     href="cvs2svn.html#options-file-method"><tt>--options</tt>-file
 386     method</a> and write your own <tt>SVNPropertySetter</tt> in
 387     Python.  For example,</p>
 388 <pre>
 389 from cvs2svn_lib.property_setters import SVNPropertySetter
 390
 391 class MyPropertySetter(SVNPropertySetter):
 392   def set_properties(self, s_item):
 393     if s_item.cvs_rev.cvs_file.cvs_path.startswith('path/to/funny/files/'):
 394       s_item.svn_props['svn:mime-type'] = 'text/plain'
 395       s_item.svn_props['svn:eol-style'] = 'CRLF'
 396
 397 ctx.svn_property_setters.append(MyPropertySetter())
 398 </pre>
 399   <p>See the file <tt>cvs2svn_lib/property_setters.py</tt> for more
 400     examples.</p>
 401
 402
 403 <h3><a name="path-symbol-transforms" title="#path-symbol-transforms">I
 404   want a single project but tag-rewriting rules that vary by
 405   subdirectory.  Can this be done?</a></h3>
 406
 407   <p>This is an example of how the cvs2svn conversion can be
 408     customized using Python.</p>
 409
 410   <p>Suppose you want to write symbol transform rules that are more
 411     complicated than "replace REGEXP with PATTERN".  This can easily
 412     be done by adding just a little bit of Python code to your <a
 413     href="cvs2svn.html#options-file-method">options file</a>.</p>
 414
 415   <p>When a symbol is encountered, cvs2svn iterates through the list
 416     of <tt>SymbolTransform</tt> objects defined for the project.  For
 417     each one, it calls <tt>symbol_transform.transform(cvs_file,
 418     symbol_name, revision)</tt>.  That method can return
 419     any legal symbol name, which will be used in the conversion
 420     instead of the original name.</p>
 421
 422   <p>To use this feature, you will have to use an <a
 423     href="cvs2svn.html#options-file-method">options file</a> to start
 424     the conversion.  You then write a new SymbolTransform class that
 425     inherits from RegexpSymbolTransform but checks the path before
 426     deciding whether to transform the symbol.  Add the following to
 427     your options file:</p>
 428
 429 <pre>
 430 from cvs2svn_lib.symbol_transform import RegexpSymbolTransform
 431
 432 class MySymbolTransform(RegexpSymbolTransform):
 433     def __init__(self, path, pattern, replacement):
 434         """Transform only symbols that occur within the specified PATH."""
 435
 436         self.path = path
 437         RegexpSymbolTransform.__init__(self, pattern, replacement)
 438
 439     def transform(self, cvs_file, symbol_name, revision):
 440         # Is the file is within the path we are interested in?
 441         if cvs_file.cvs_path.startswith(path + '/'):
 442             # Yes -> Allow RegexpSymbolTransform to transform the symbol:
 443             return RegexpSymbolTransform.transform(
 444                     self, cvs_file, symbol_name, revision)
 445         else:
 446             # No -> Return the symbol unchanged:
 447             return symbol_name
 448
 449 # Note that we use a Python loop to fill the list of symbol_transforms:
 450 symbol_transforms = []
 451 for subdir in ['project1', 'project2', 'project3']:
 452     symbol_transforms.append(
 453         MySymbolTransform(
 454             subdir,
 455             r'release-(\d+)_(\d+)',
 456             r'%s-release-\1.\2' % subdir))
 457
 458 # Now register the project, using our own symbol transforms:
 459 run_options.add_project(
 460     'your_cvs_path',
 461     trunk_path='trunk',
 462     branches_path='branches',
 463     tags_path='tags',
 464     symbol_transforms=symbol_transforms))
 465 </pre>
 466
 467   <p>This example causes any symbol under "project1" that looks like
 468     "release-3_12" to be transformed into a symbol named
 469     "project1-release-3.12", whereas if the same symbol appears under
 470     "project2" it will be transformed into
 471     "project2-release-3.12".</p>
 472
 473
 474 <h3><a name="cvsnt" title="#cvsnt">How can I convert a CVSNT
 475     repository?</a></h3>
 476
 477   <p><a href="http://www.cvsnt.org/">CVSNT</a> is a version control
 478     system that started out by adding support for running CVS under
 479     Windows NT.  Since then it has made numerous extensions to the RCS
 480     file format, to the point where CVS compatibility does not imply
 481     CVSNT compatibility with any degree of certainty.</p>
 482
 483   <p>cvs2svn <em>might</em> happen to successfully convert a CVSNT
 484     repository, especially if the repository has never had any
 485     CVSNT-only features used on it, but <b>this use is not supported
 486     and should not be expected to work</b>.</p>
 487
 488   <p>If you want to experiment with converting a CVSNT repository,
 489     then please consider the following suggestions:</p>
 490
 491   <ul>
 492     <li>Use cvs2svn's <tt>--use-cvs</tt> option.</li>
 493
 494     <li>Use CVSNT's version of the <tt>cvs</tt> executable (i.e.,
 495       ensure that the first <tt>cvs</tt> program in your $PATH is the
 496       one that came with CVSNT).</li>
 497
 498     <li>Carefully check the result of the conversion before you rely
 499       on it, <em>even if the conversion completed without any
 500       errors or warnings</em>.</li>
 501
 502   </ul>
 503
 504   <p>Patches to support the conversion of CVSNT repositories would, of
 505     course, be welcome.</p>
 506
 507 <hr />
 508
 509 <h2>Problems:</h2>
 510
 511 <h3><a name="atticprob" title="#atticprob">I get an error "A CVS
 512     repository cannot contain both repo/path/file.txt,v and
 513     repo/path/Attic/file.txt,v".  What can I do?</a></h3>
 514
 515 <p>Background: Normally, if you have a file called
 516 <tt>path/file.txt</tt> in your project, CVS stores its history in a
 517 file called <tt>repo/path/file.txt,v</tt>.  But if <tt>file.txt</tt>
 518 is deleted on the main line of development, CVS moves its history file
 519 to a special <tt>Attic</tt> subdirectory:
 520 <tt>repo/path/Attic/file.txt,v</tt>.  (If the file is recreated, then
 521 it is moved back out of the <tt>Attic</tt> subdirectory.)  Your
 522 repository should never contain both of these files at the same
 523 time.</p>
 524
 525 <p>This cvs2svn error message thus indicates a mild form of corruption
 526 in your CVS repository.  The file has two conflicting histories, and
 527 even CVS does not know the correct history of <tt>path/file.txt</tt>.
 528 The corruption was probably created by using tools other than CVS to
 529 backup or manipulate the files in your repository.  With a little work
 530 you can learn more about the two histories by viewing each of the
 531 <tt>file.txt,v</tt> files in a text editor.</p>
 532
 533 <p>There are four straightforward approaches to fixing the repository
 534 corruption, but each has potential disadvantages.  Remember to <b>make
 535 a backup</b> before starting.  Never run cvs2svn on a live CVS
 536 repository--always work on a copy of your repository.</p>
 537
 538 <ol>
 539   <li>Restart the conversion with the
 540     <tt>--retain-conflicting-attic-files</tt> option.  This causes the
 541     non-attic and attic versions of the file to be converted
 542     separately, with the <tt>Attic</tt> version stored to a new
 543     subdirectory as <tt>path/Attic/file.txt</tt>.  This approach
 544     avoids losing any history, but by moving the <tt>Attic</tt>
 545     version of the file to a different subdirectory it might cause
 546     historical revisions to be broken.</li>
 547
 548   <li>Remove the <tt>Attic</tt> version of the file and restart the
 549     conversion.  Sometimes it represents an old version of the file
 550     that was deleted long ago, and it won't be missed.  But this
 551     completely discards one of the file's histories, probably causing
 552     <tt>file.txt</tt> to be missing in older historical revisions.
 553     (For what it's worth, this is probably how CVS would behave in
 554     this situation.)
 555
 556     <pre>
 557       # You did make a backup, right?
 558       $ rm repo/path/Attic/file.txt,v
 559     </pre></li>
 560
 561   <li>Remove the non-<tt>Attic</tt> version of the file and restart
 562     the conversion.  This might be appropriate if the
 563     non-<tt>Attic</tt> version has less important content than the
 564     <tt>Attic</tt> version.  But this completely discards one of the
 565     file's histories, probably causing <tt>file.txt</tt> to be missing
 566     in recent historical revisions.
 567
 568     <pre>
 569       # You did make a backup, right?
 570       $ rm repo/path/file.txt,v
 571     </pre></li>
 572
 573   <li>Rename the non-<tt>Attic</tt> version of the file and restart
 574     the conversion.  This avoids losing history, but it changes the
 575     name of the non-<tt>Attic</tt> version of the file to
 576     <tt>file-not-from-Attic.txt</tt> whenever it appeared, and might
 577     thereby cause revisions to be broken.
 578
 579     <pre>
 580       # You did make a backup, right?
 581       $ mv repo/path/file.txt,v repo/path/file-not-from-Attic.txt,v
 582     </pre></li>
 583
 584 </ol>
 585
 586 <p>If you run cvs2svn on a case-insensitive operating system, it is
 587 possible to get this error even if the filename of the file in
 588 Attic has different case than the one out of the Attic.  This could
 589 happen, for example, if the CVS repository was served from a
 590 case-sensitive operating system at some time.  A workaround for this
 591 problem is to copy the CVS repository to a case-sensitive operating
 592 system and convert it there.
 593 </p>
 594
 595
 596 <h3><a name="gdbm-nfs" title="#gdbm-nfs">gdbm.error: (45, 'Operation
 597     not supported')</a></h3>
 598
 599 <p>This has been reported to be caused by trying to create gdbm
 600 databases on an NFS partition.  Apparently gdbm does not support
 601 databases on NFS partitions.  The workaround is to use the
 602 <tt>--tmpdir</tt> option to choose a local partition for cvs2svn to
 603 write its temporary files.</p>
 604
 605 <h3><a name="apple-single" title="#apple-single">When converting a CVS
 606     repository that was used on a Macintosh, the contents of some
 607     files are incorrect in SVN.</a></h3>
 608
 609 <p>Some Macintosh CVS clients use a nonstandard trick to store the
 610 resource fork of files in CVS: instead of storing the file contents
 611 directly, store an <a
 612 href="http://rfc.net/rfc1740.html">AppleSingle</a> data stream
 613 containing both the data fork and resource fork.  When checking the
 614 file out, the client unpacks the AppleSingle data and writes the two
 615 forks separately to disk.  By default, cvs2svn treats the file
 616 contents literally, so when you check the file out of Subversion, the
 617 file contains the combined data in AppleSingle format rather than only
 618 the data fork of the file as expected.</p>
 619
 620 <p>Subversion does not have any special facilities for dealing with
 621 Macintosh resource forks, so there is nothing cvs2svn can do to
 622 preserve both forks of your data.  However, sometimes the resource
 623 fork is not needed.  If you would like to discard the resource fork
 624 and only record the data fork in Subversion, then start your
 625 conversion using the <a
 626 href="cvs2svn.html#options-file-method">options file method</a> and
 627 set the following option to <tt>True</tt> in your options file:</p>
 628
 629 <pre>
 630       ctx.decode_apple_single = True
 631 </pre>
 632
 633 <p>There is more information about this option in the comments in
 634 <tt>cvs2svn-example.options</tt>.</p>
 635
 636 <h3><a name="rcsmissing" title="#installrcs">Using cvs2svn 1.3.x, I
 637     get an error "The command '['co', '-q', '-x,v', '-p1.1', '-kk',
 638     '/home/cvsroot/myfile,v']' failed" in pass 8.</a></h3>
 639
 640 <p><i>What are you using cvs2svn version 1.3.x for anyway?
 641 Upgrade!</i></p>
 642
 643 <p>But if you must, either install RCS, or ensure that CVS is
 644 installed and use cvs2svn's <a
 645 href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt></a> option.</p>
 646
 647
 648 <h2>Getting help:</h2>
 649
 650 <h3><a name="gettinghelp" title="#gettinghelp">How do I get
 651 help?</a></h3>
 652
 653 <p>There are several sources of help for cvs2svn:</p>
 654
 655 <ul>
 656
 657   <li>The <a href="cvs2svn.html">user manual</a> not only describes
 658   how to run cvs2svn, but also discusses some limitations, pitfalls,
 659   and conversion strategies.  Please note that the <a
 660   href="http://cvs2svn.tigris.org/cvs2svn.html">online manual</a>
 661   describes the latest "bleeding edge" trunk version of the software,
 662   which may be different than the version that you are using.</li>
 663
 664   <li>The <a href="faq.html">frequently asked questions (FAQ) list</a>
 665   is the document that you are now reading.  Please make sure you've
 666   scanned through the list of topics to see if your question is
 667   already answered.</li>
 668
 669   <li>The <a
 670   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">mailing
 671   list archives</a>.  Maybe your question has
 672   been discussed on either the <tt>user@cvs2svn.tigris.org</tt> or
 673   <tt>dev@cvs2svn.tigris.org</tt> mailing list.</li>
 674
 675   <li>If you need help with running cvs2svn or problems converting
 676   your repository, the <a
 677   href="mailto:users@cvs2svn.tigris.org"><tt>users@cvs2svn.tigris.org</tt></a>
 678   mailing list is the first place to send inquiries.  Please <a
 679   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">subscribe</a>
 680   to the list so that you can follow ensuing discussions.</li>
 681
 682   <li>You can also ask questions on IRC at <a
 683   href="irc://irc.freenode.net/"><tt>irc.freenode.net</tt></a>,
 684   channel <tt>#cvs2svn</tt>.</li>
 685
 686   <li>If you think you have found a bug, please refer to <a
 687   href="#reportingbugs">"How do I report a bug?"</a></li>
 688
 689 </ul>
 690
 691 <h3><a name="reportingbugs" title="#reportingbugs">How do I report a
 692 bug?</a></h3>
 693
 694 <p>cvs2svn is an open source project that is largely developed and
 695 supported by volunteers in their free time.  Therefore please try to
 696 help out by reporting bugs in a way that will enable us to help you
 697 efficiently.</p>
 698
 699 <p>The first question is whether the problem you are experiencing is
 700 caused by a cvs2svn bug at all.  A large fraction of reported "bugs"
 701 are caused by problems with the user's CVS repository, especially mild
 702 forms of repository corruption or <a href="#cvsnt">trying to convert a
 703 CVSNT repository with cvs2svn</a>.  Please also double-check the <a
 704 href="cvs2svn.html">manual</a> to be sure that you are using the
 705 command-line options correctly.</p>
 706
 707 <p>A good way to localize potential repository corruption is to use
 708 the <tt>shrink_test_case.py</tt> script (which is located in the
 709 <tt>contrib</tt> directory of the cvs2svn source tree).  This script
 710 tries to find the minimum subset of files in your repository that
 711 still shows the same problem.  <b>Warning: Only apply this script to a
 712 backup copy of your repository, as it destroys the repository that it
 713 operates on!</b> Often this script can narrow the problem down to a
 714 single file which, as often as not, is corrupt in some way.  Even if
 715 the problem is not in your repository, the shrunk-down test case will
 716 be useful for reporting the bug.  Please see <a href="#testcase">"How
 717 can I produce a useful test case?"</a> and the comments at the top of
 718 <tt>shrink_test_case.py</tt> for information about how to use this
 719 script.</p>
 720
 721 <p>Assuming that you still think you have found a bug, the next step
 722 is to investigate whether the bug is already known.  Please look
 723 through the <a
 724 href="http://cvs2svn.tigris.org/issue_tracker.html">issue tracker</a>
 725 for bugs that sound familiar.  If the bug is already known, then there
 726 is no need to report it (though possibly you could contribute a <a
 727 href="#testcase">useful test case</a> or a workaround).</p>
 728
 729 <p>If your bug seems new, then the best thing to do is report it via
 730 email to the <a
 731 href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">dev@cvs2svn.tigris.org</a>
 732 mailing list.  Be sure to include the following information in your
 733 message:</p>
 734
 735 <ol>
 736
 737   <li><em>Exactly what version</em> of cvs2svn are you using?  If you
 738   are not using an official release, please tell us what branch and
 739   revision number from the <a
 740   href="http://cvs2svn.tigris.org/svn/cvs2svn/">svn archive</a> you
 741   are using.  If you have modified cvs2svn, please tell us exactly
 742   what you have changed.</li>
 743
 744   <li>What platform are you using (Linux, BSD, Windows, etc.)?  What
 745   python version (e.g., type <tt>python --version</tt>)?</li>
 746
 747   <li>What is the <em>exact command line</em> that you used to start
 748   the conversion?  If you used the <tt>--options</tt> option, please
 749   attach a copy of the options file that you used.</li>
 750
 751   <li>What happened when you ran the program?  Why do you think the
 752   behavior was wrong?  Include transcripts and/or error output if
 753   available.</li>
 754
 755   <li>If at all possible, include a test case repository that we can
 756   use to reproduce the problem.  See <a href="#testcase">"How can I
 757   produce a useful test case?"</a> for more information.  In most
 758   cases, if we cannot reproduce the problem, there is nothing we can
 759   do to help you.</li>
 760
 761 </ol>
 762
 763
 764 <h3><a name="testcase" title="#testcase">How can I produce a useful
 765 test case?</a></h3>
 766
 767 <p>If you need to <a href="#reportingbugs">report a bug</a>, it is
 768 extremely helpful if you can include a test repository with your bug
 769 report.  In most cases, if we cannot reproduce the problem, there is
 770 nothing we can do to help you.  This section describes ways to
 771 overcome the most common problems that people have in producing a
 772 useful test case.  When you have a reasonable-sized test case (say
 773 under 1 MB--the smaller the better), you can just tar it up and attach
 774 it to the email in which you report the bug.</p>
 775
 776 <h4>If the repository is too big and/or contains proprietary information</h4>
 777
 778 <p>You don't want to send us your proprietary information, and we
 779 don't want to receive it either.  Short of open-sourcing your
 780 software, here is a way to strip out most of the proprietary
 781 information and simultaneously reduce the size of the archive
 782 tremendously.</p>
 783
 784 <p>The <tt>destroy_repository.py</tt> script tries to delete as much
 785 information as possible out of your repository while still preserving
 786 its basic structure (and therefore hopefully any cvs2svn bugs).
 787 Specifically, it tries to delete file descriptions, text content, all
 788 nontrivial log messages, and all author names.  It also renames all
 789 files and directories to have generic names (e.g.,
 790 <tt>dir015/file053,v</tt>).  (It does not affect the number and dates
 791 of revisions to the files.)</p>
 792
 793 <ol>
 794
 795   <li>This procedure will <b>destroy the repository</b> that it is
 796   applied to, so be sure to <b>make a backup copy of your
 797   repository and work with the backup!</b></li>
 798
 799   <li>Make sure you have the <tt>destroy_repository.py</tt> script.
 800   If you don't already have it, you should <a
 801   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
 802   source code</a> for cvs2svn (there is no need to install it).  The
 803   script is located in the <tt>contrib</tt> subdirectory.</li>
 804
 805   <li>Run <tt>destroy_repository.py</tt> by typing <pre>
 806 # You did make a backup, right?
 807 /path/to/config/destroy_repository.py /path/to/copy/of/repo
 808 </pre></li>
 809
 810   <li>Verify that the "destroyed" archive does not include any
 811   information that you consider proprietary.  Your data security is
 812   ultimately your responsibility, and we make no guarantees that the
 813   <tt>destroy_repository.py</tt> script works correctly.  You can open
 814   the *,v files using a text editor to see what they contain.</li>
 815
 816   <li>Try converting the "destroyed" repository using cvs2svn, and
 817   ensure that the bug still exists.  Take a note of the exact cvs2svn
 818   command line that you used and include it along with a tarball of
 819   the "destroyed" repository with your bug report.</li>
 820
 821 </ol>
 822
 823 <p>If running <tt>destroy_repository.py</tt> with its default options
 824 causes the bug to go away, consider using
 825 <tt>destroy_repository.py</tt> command-line options to leave part of
 826 the repository information intact.  Run <tt>destroy_repository.py
 827 --help</tt> for more information.</p>
 828
 829
 830 <h4>The repository is still too large</h4>
 831
 832 <p>This step is a tiny bit more work, so if your repository is already
 833 small enough to send you can skip this step.  But this step helps
 834 narrow down the problem (maybe even point you to a corrupt file in
 835 your repository!) so it is still recommended.</p>
 836
 837 <p>The <tt>shrink_test_case.py</tt> script tries to delete as many
 838 files and directories from your repository as possible while
 839 preserving the cvs2svn bug.  To use this command, you need to write a
 840 little test script that tries to convert your repository and checks
 841 whether the bug is still present.  The script should exit successfully
 842 (e.g., "<tt>exit 0</tt>") if the bug is still <em>present</em>, and
 843 fail (e.g., "<tt>exit 1</tt>") if the bug has <em>disappeared</em>.
 844 The form of the test script depends on the bug that you saw, but it
 845 can be as simple as something like this:</p>
 846
 847 <pre>
 848 #! /bin/sh
 849
 850 cvs2svn --dry-run /path/to/copy/of/repo 2>&amp;1 | grep -q 'KeyError'
 851 </pre>
 852
 853 <p>If the bug is more subtle, then the test script obviously needs to
 854 be more involved.</p>
 855
 856 <p>Once the test script is ready, you can shrink your repository via
 857 the following steps:</p>
 858
 859 <ol>
 860
 861   <li>This procedure will <b>destroy the repository</b> that it is
 862   applied to, so be sure to <b>make a backup copy of your
 863   repository and work with the backup!</b></li>
 864
 865   <li>Make sure you have the <tt>shrink_test_case.py</tt> script.
 866   If you don't already have it, you should <a
 867   href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
 868   source code</a> for cvs2svn (there is no need to install it).  The
 869   script is located in the <tt>contrib</tt> subdirectory.</li>
 870
 871   <li>Run <tt>shrink_test_case.py</tt> by typing <pre>
 872 # You did make a backup, right?
 873 /path/to/config/shrink_test_case.py /path/to/copy/of/repo testscript.sh
 874 </pre>, where <tt>testscript.sh</tt> is the name of the test script
 875   described above.  This script will execute <tt>testscript.sh</tt>
 876   many times, each time using a subset of the original repository.</li>
 877
 878   <li>If the shrunken repository only consists of one or two files,
 879   look inside the files with a text editor to see whether they are
 880   corrupted in any obvious way.  (Many so-called cvs2svn "bugs" are
 881   actually the result of a corrupt CVS repository.)</li>
 882
 883   <li>Try converting the "shrunk" repository using cvs2svn, to make
 884   sure that the original bug still exists.  Take a note of the exact
 885   cvs2svn command line that you used, and include it along with a
 886   tarball of the "destroyed" repository with your bug report.</li>
 887
 888 </ol>
 889
 890
 891 <h3><a name="osxsetup" title="#osxsetup">How do I get cvs2svn to run
 892 on OS X 10.5.5?</a></h3>
 893
 894 <p>Attempting to run cvs2svn on a standard OS X 10.5.5 installation
 895 yields the following error:</p>
 896
 897 <blockquote> <p> ERROR: cvs2svn uses the anydbm package, which depends on
 898 lower level dbm libraries.  Your system has dbm, with which cvs2svn is
 899 known to have problems.  To use cvs2svn, you must install a Python dbm
 900 library other than dumbdbm or dbm.  See <a
 901 href="http://python.org/doc/current/lib/module-anydbm.html">http://python.org/doc/current/lib/module-anydbm.html</a>
 902 for more information. </p> </blockquote>
 903
 904 <p>The problem is that the standard distribution of python on OS X
 905 10.5.5 does not include any other dbm libraries other than the
 906 standard dbm.  In order for cvs2svn to work, we need to install the
 907 gdbm library, in addition to a new version of python that enables the
 908 python gdbm module. Here is the procedure for a successful
 909 installation of cvs2svn and all supporting libs:</p>
 910
 911 <ol>
 912
 913   <li>Download the gdbm-1.8.3 (or greater) source, unarchive and
 914     change directory to gdbm-1.8.3. We need to install the gdbm
 915     libraries so python's gdbm module can use them.
 916
 917   <ol>
 918
 919     <li>Type <code>./configure</code></li>
 920
 921     <li>Edit "Makefile" so that the owner and group are not the
 922         non-existing "bin" owner and group by changing
 923
 924 <pre>
 925 BINOWN = bin
 926 BINGRP = bin
 927 </pre>
 928 to
 929 <pre>
 930 BINOWN = root
 931 BINGRP = admin
 932 </pre>
 933
 934     </li>
 935
 936     <li>Type "make"</li>
 937
 938     <li>Type "sudo make install"</li>
 939
 940   </ol>
 941
 942   </li>
 943
 944   <li>Download the Python2.6 (or greater) source, unarchive, and
 945   change directory to Python2.6.  We need to enable python gdbm
 946   support which is not enabled in the default OS X 10.5.5 installation
 947   of python, as the gdbm libs are not included.  However, we just
 948   installed the gdbm libs in step 1, so we can now compile python with
 949   gdbm support.
 950
 951   <ol>
 952
 953     <li>Edit the file "Modules/Setup" by uncommenting the line which
 954       links against gdbm by changing
 955
 956 <pre>
 957 #gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 958 </pre>
 959 to
 960 <pre>
 961 gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
 962 </pre>
 963     </li>
 964
 965     <li>Edit the file "Modules/Setup" by uncommenting the line to
 966       create shared libs by changing
 967
 968 <pre>
 969 #*shared*
 970 </pre>
 971 to
 972 <pre>
 973 *shared*
 974 </pre>
 975     </li>
 976
 977     <li>Type <code>./configure --enable-framework
 978     --enable-universalsdk --enable-shared</code> in the top-level
 979     Python2.6 directory.  This will configure the installation of
 980     python as a shared OS X framework, and usable with OS X GUI
 981     frameworks and SDKs.  By default, python will be installed in
 982     "/Library/Frameworks/Python.framework", which is what we
 983     want.</li>
 984
 985     <li>Type <code>make</code></li>
 986
 987     <li>Type <code>sudo make install</code></li>
 988
 989     <li>Type <code>cd /usr/local/bin; sudo ln -s python2.6 python</code></li>
 990
 991     <li>Make sure "/usr/local/bin" is at the front of your search path
 992     in ~/.profile or ~/.bashrc etc.</li>
 993
 994     <li>Type <code>source ~/.profle</code> or <code>source
 995     ~/.bashrc</code> etc. or alternatively, just open a new shell
 996     window.  When you type <code>which python</code> it should give
 997     you the new version in "/usr/local/bin" <strong>not</strong> the
 998     one in "/usr/bin".</li>
 999
1000   </ol>
1001
1002   </li>
1003
1004   <li>Download the cvs2svn-2.2.0 (or greater) source, unarchive and
1005   change directory to cvs2svn-2.2.0.  Many people can't get cvs2svn to
1006   work except in the installation directory.  The reason for this is
1007   that the installation places copies of cvs2svn, cvs2svn_libs, and
1008   cvs2svn_rcsparse in the /Library/Frameworks/Python.framework
1009   hierarchy.  All we need to do is make a link in /usr/local/bin
1010   pointing to the location of cvs2svn in the python framework
1011   hierarchy.  And for good measure we also make links to the lib and
1012   include directories:
1013
1014   <ol>
1015
1016     <li>Type <code>sudo make install</code></li>
1017
1018     <li>Create the required links by typing the following:
1019
1020 <pre>
1021 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/bin/cvs2svn /usr/local/bin/cvs2svn
1022 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6 /usr/local/lib/python2.6
1023 sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/include/python2.6 /usr/local/include/python2.6
1024 </pre>
1025
1026     </li>
1027
1028   </ol>
1029
1030   </li>
1031
1032 </ol>
1033
1034 <p>The installation is complete. Change directory out of the
1035 cvs2svn-2.2.0 installation directory, and you should be able to run
1036 cvs2svn. Be careful *not* to copy the version of cvs2svn in the
1037 cvs2svn-2.2.0 installation directory to /usr/local/bin, as this has a
1038 different python environment setting at the top of the file than the
1039 one that was installed in the /Library/Frameworks/Python.framework
1040 hierarchy. Follow the instructions exactly, and it should work.
1041 </p>
1042
1043 </div>
1044 </body>
1045 </html>