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