www/faq.html

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