File: faq.html

package info (click to toggle)
cvs2svn 2.3.0-2
  • links: PTS
  • area: main
  • in suites: squeeze
  • size: 3,528 kB
  • ctags: 2,828
  • sloc: python: 20,721; sh: 509; perl: 121; makefile: 79
file content (1174 lines) | stat: -rw-r--r-- 43,381 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<style type="text/css"> /* <![CDATA[ */
  @import "tigris-branding/css/tigris.css";
  @import "tigris-branding/css/inst.css";
  /* ]]> */</style>
<link rel="stylesheet" type="text/css" media="print"
  href="tigris-branding/css/print.css"/>
<script type="text/javascript" src="tigris-branding/scripts/tigris.js"></script>
<title>cvs2svn FAQ</title>
</head>

<body id="bodycol">
<div class="app">

<h1>cvs2svn FAQ</h1>

<p><strong>General:</strong></p>

<ol>

  <li><a href="#incremental">Does cvs2svn support incremental
    repository conversion?</a></li>

</ol>


<p><strong>Compatibility:</strong></p>

<ol>

  <li><a href="#psyco">Does cvs2svn run under Psyco?</a></li>

</ol>


<p><strong>How-to:</strong></p>

<ol>

  <li><a href="#repoaccess">How can I convert a CVS repository to
    which I only have remote access?</a></li>

  <li><a href="#oneatatime">How can I convert my CVS repository one
    module at a time?</a></li>

  <li><a href="#partialconversion">How can I convert part of a CVS
    repository?</a></li>

  <li><a href="#onetoone">How can I convert separate projects in my
    CVS repository into a single Subversion repository?</a></li>

  <li><a href="#inverted">How can I convert project <tt>foo</tt> so
    that <tt>trunk/tags/branches</tt> are inside of
    <tt>foo</tt>?</a></li>

  <li><a href="#eol-fixup">How do I fix up end-of-line translation
    problems?</a></li>

  <li><a href="#path-symbol-transforms">I want a single project but
    tag-rewriting rules that vary by subdirectory.  Can this be
    done?</a></li>

  <li><a href="#cvsnt">How can I convert a CVSNT repository?</a></li>

  <li><a href="#osxsetup">How do I get cvs2svn to run on OS X
    10.5.5?</a></li>

</ol>


<p><strong>Problems:</strong></p>

<ol>

  <li><a href="#atticprob">I get an error "A CVS repository cannot
    contain both repo/path/file.txt,v and
    repo/path/Attic/file.txt,v".  What can I do?</a></li>

  <li><a href="#gdbm-nfs">gdbm.error: (45, 'Operation not supported')</a></li>

  <li><a href="#apple-single">When converting a CVS repository that
    was used on a Macintosh, some files have incorrect contents in
    SVN.</a></li>

  <li><a href="#rcsmissing">Using cvs2svn 1.3.x, I get an error "The
    command '['co', '-q', '-x,v', '-p1.1', '-kk',
    '/home/cvsroot/myfile,v']' failed" in pass 8.</a></li>

</ol>


<p><strong>Getting help:</strong></p>

<ol>

  <li><a href="#gettinghelp">How do I get help?</a></li>

  <li><a href="#reportingbugs">How do I report a bug?</a></li>

  <li><a href="#testcase">How can I produce a useful test case?</a></li>

  <li><a href="#commercialsupport">Does anybody offer commercial
    support for cvs2svn/cvs2git conversions?</a></li>

</ol>

<hr />


<h2>General:</h2>

<h3><a name="incremental" title="#incremental">Does cvs2svn support
incremental repository conversion?</a></h3>

<p>No.</p>

<p>Explanation: During the transition from CVS to Subversion, it would
sometimes be useful to have the new Subversion repository track
activity in the CVS repository for a period of time until the final
switchover.  This would require each conversion to determine what had
changed in CVS since the last conversion, and add those commits on top
of the Subversion repository.</p>

<p>Unfortunately, cvs2svn/cvs2git does <em>not</em> support
incremental conversions.  With some work it would be possible to add
this feature, but it would be difficult to make it robust.  The
trickiest problem is that CVS allows changes to the repository that
have retroactive effects (e.g., affecting parts of the history that
have already been converted).</p>

<p>Some conversion tools claim to support incremental conversions from
CVS, but as far as is known none of them are reliable.</p>

<p>Volunteers or sponsorship to add support for incremental
conversions to cvs2svn/cvs2git would be welcome.</p>

<hr />


<h2>Compatibility:</h2>

<h3><a name="psyco" title="#psyco">Does cvs2svn run under
Psyco?</a></h3>

<p>No.</p>

<p>Explanation: <a href="http://psyco.sourceforge.net/">Psyco</a> is a
python extension that can speed up the execution of Python code by
compiling parts of it into i386 machine code.  Unfortunately, Psyco is
known <em>not</em> to run cvs2svn correctly (this was last tested with
the Psyco pre-2.0 development branch).  When cvs2svn is run under
Psyco it crashes in <tt>OutputPass</tt> with an error message that
looks something like this:</p>

<pre>
cvs2svn_lib.common.InternalError: ID changed from 2 -> 3 for Trunk, r2
</pre>

<p>The Psyco team <a
href="https://sourceforge.net/tracker/?func=detail&amp;aid=2827082&amp;group_id=41036&amp;atid=429622">has
been informed about the problem</a>.</p>

<hr />


<h2>How-to:</h2>

<h3><a name="repoaccess" title="#repoaccess">How can I convert a CVS
repository to which I only have remote access?</a></h3>

<p>cvs2svn requires direct, filesystem access to a copy of the CVS
repository that you want to convert.  The reason for this requirement
is that cvs2svn directly parses the <tt>*,v</tt> files that make up
the CVS repository.</p>

<p>Many remote hosting sites provide access to backups of your CVS
repository, which could be used for a cvs2svn conversion.  For
example:</p>

<ul>
  <li><a href="http://sourceforge.net">SourceForge</a> allows CVS
    content to be accessed via
    <a href="http://sourceforge.net/docs/E04/en/#rsync">rsync</a>.  In
    fact, they provide <a
    href="http://sourceforge.net/docman/display_doc.php?docid=31070&amp;group_id=1#import">complete instructions</a>
    for migrating a SourceForge project from CVS to SVN.</li>
  <li>...<i>(other examples welcome)</i></li>
</ul>

<p>If your provider does not provide any way to download your CVS
repository, there are two known tools that claim to be able to
clone a CVS repository via the CVS protocol:</p>

<ul>

  <li><a href="http://samba.org/ftp/tridge/rtc/cvsclone.l">cvsclone</a></li>

  <li><a href="http://cvs.m17n.org/~akr/cvssuck/">CVSsuck</a></li>

</ul>

<p>It should be possible to use one of these tools to fetch a copy of
your CVS repository from your provider, then to use cvs2svn to convert
the copy.  However, the developers of cvs2svn do not have any
experience with these tools, so you are on your own here.  If you try
one of them, please tell us about your experience on the <a
href="mailto:users@cvs2svn.tigris.org">users mailing list</a>.</p>


<h3><a name="oneatatime" title="#oneatatime">How can I convert my CVS
repository one module at a time?</a></h3>

<p>If you need to convert certain CVS modules (in one large
repository) to Subversion <b>now</b> and other modules <b>later</b>,
you may want to convert your repository one module at a time.  This
situation is typically encountered in large organizations where each
project has a separate lifecycle and schedule, and a one-step
conversion process is not practical.
</p>

<p>First you have to decide whether you want to put your converted
projects into a single Subversion repositories or multiple ones.  This
decision mostly depends on the degree of coupling between the projects
and is beyond the scope of this FAQ.  See <a
href="http://svnbook.red-bean.com/en/1.2/svn.reposadmin.projects.html#svn.reposadmin.projects.chooselayout">the
Subversion book</a> for a discussion of repository organization.
</p>

<p>If you decide to convert your projects into separate Subversion
repositories, then please follow the instructions in <a
href="#partialconversion">How can I convert part of a CVS
repository?</a> once for each repository.
</p>

<p>If you decide to put more than one CVS project into a single
Subversion repository, then please follow the instructions in <a
href="#onetoone">How can I convert separate projects in my CVS
repository into a single Subversion repository?</a>.
</p>


<h3><a name="partialconversion" title="#partialconversion">How can I
convert part of a CVS repository?</a></h3>

<p>This is easy: simply run cvs2svn normally, passing it the path of
the project subdirectory within the CVS repository.  Since cvs2svn
ignores any files outside of the path it is given, other projects
within the CVS repository will be excluded from the conversion.
</p>

<p>Example: You have a CVS repository at path <tt>/path/cvsrepo</tt>
with projects in subdirectories <tt>/path/cvsrepo/foo</tt> and
<tt>/path/cvsrepo/bar</tt>, and you want to create a new Subversion
repository at <tt>/path/foo-svn</tt> that includes only the
<tt>foo</tt> project:
</p>

<pre>
    $ cvs2svn -s /path/foo-svn /path/cvsrepo/foo
</pre>


<h3><a name="onetoone" title="#onetoone">How can I convert separate
projects in my CVS repository into a single Subversion
repository?</a></h3>

<p>cvs2svn supports multiproject conversions, but you have to use the
<a href="cvs2svn.html#options-file-method">options file method</a> to
start the conversion.  In your options file, you simply call
<tt>run_options.add_project()</tt> once for each sub-project in your
repository.  For example, if your CVS repository has the layout:</p>

<pre>
  /project_a
  /project_b
</pre>

  <p>and you want your Subversion repository to be laid out like this:</p>

<pre>
   project_a/
      trunk/
         ...
      branches/
         ...
      tags/
         ...
   project_b/
      trunk/
         ...
      branches/
         ...
      tags/
         ...
</pre>

<p>then you need to have a section like this in your options file:</p>

<pre>
run_options.add_project(
    'my/cvsrepo/project_a',
    trunk_path='project_a/trunk',
    branches_path='project_a/branches',
    tags_path='project_a/tags',
    symbol_transforms=[
        #...whatever...
        ],
    symbol_strategy_rules=[
        #...whatever...
        ],
    )
run_options.add_project(
    'my/cvsrepo/project_b',
    trunk_path='project_b/trunk',
    branches_path='project_b/branches',
    tags_path='project_b/tags',
    symbol_transforms=[
        #...whatever...
        ],
    symbol_strategy_rules=[
        #...whatever...
        ],
    )
</pre>


<h3><a name="inverted" title="#inverted">How can I convert project
    <tt>foo</tt> so that <tt>trunk/tags/branches</tt> are inside of
    <tt>foo</tt>?</a></h3>

  <p>If <tt>foo</tt> is the only project that you want to convert,
    then either run cvs2svn like this:</p>

<pre>
   $ cvs2svn --trunk=foo/trunk --branches=foo/branches --tags=foo/tags CVSREPO/foo
</pre>

  <p>or use an options file that defines a project like this:</p>

<pre>
run_options.add_project(
    'my/cvsrepo/foo',
    trunk_path='foo/trunk',
    branches_path='foo/branches',
    tags_path='foo/tags',
    symbol_transforms=[
        #...whatever...
        ],
    symbol_strategy_rules=[
        #...whatever...
        ],
    )
</pre>

  <p>If <tt>foo</tt> is not the only project that you want to convert,
    then you need to do a multiproject conversion; see <a
    href="#onetoone">How can I convert separate projects in my CVS
    repository into a single Subversion repository?</a> for more
    information.</p>


<h3><a name="eol-fixup" title="#eol-fixup">How do I fix up end-of-line
  translation problems?</a></h3>

  <p>Warning: cvs2svn's handling of end-of-line options changed
    between version 1.5.x and version 2.0.x.  <strong>This
    documentation applies to version 2.0.x and later.</strong>  The
    documentation applying to an earlier version can be found in the
    <tt>www</tt> directory of that release of cvs2svn.</p>

  <p>Starting with version 2.0, the default behavior of cvs2svn is to
    treat all files as binary except those explicitly determined to be
    text.  (Previous versions treated files as text unless they were
    determined to be binary.)  This behavior was changed because,
    generally speaking, it is safer to treat a text file as binary
    than vice versa.</p>

  <p>However, it is often preferred to set
    <tt>svn:eol-style=native</tt> for text files, so that their
    end-of-file format is converted to that of the client platform
    when the file is checked out.  This section describes how to
    get the settings that you want.</p>

  <p>If a file is marked as binary in CVS (with <tt>cvs admin
    -kb</tt>, then cvs2svn will always treat the file as binary.  For
    other files, cvs2svn has a number of options that can help choose
    the correct end-of-line translation parameters during the
    conversion:</p>

    <table border="1" cellpadding="10" cellspacing="3" width="80%">

      <tr>
        <td align="right"><tt>--auto-props=FILE</tt></td>
        <td>

	  <p>Set arbitrary Subversion properties on files based on the
            auto-props section of a file in svn config format.  The
            auto-props file might have content like this:</p>

<pre>
[auto-props]
*.txt = svn:mime-type=text/plain;svn:eol-style=native
*.doc = svn:mime-type=application/msword;!svn:eol-style
</pre>

          <p>This option can also be used in combination with
            <tt>--eol-from-mime-type</tt>.</p>

          <p>To force end-of-line translation off, use a setting of
            the form <tt>!svn:eol-style</tt> (with a leading
            exclamation point).</p>

	</td>
      </tr>

      <tr>
        <td align="right"><tt>--mime-types=FILE</tt></td>
        <td><p>Specifies an Apache-style mime.types file for setting
          files' <tt>svn:mime-type</tt> property based on the file
          extension.  The mime-types file might have content like
          this:</p>
<pre>
text/plain              txt
application/msword      doc
</pre>
          <p>This option only has an effect on <tt>svn:eol-style</tt>
          if it is used in combination with
          <tt>--eol-from-mime-type</tt>.</p></td>
      </tr>

      <tr>
        <td align="right"><tt>--eol-from-mime-type</tt></td>
        <td>Set <tt>svn:eol-style</tt> based on the file's mime type
          (if known).  If the mime type starts with "<tt>text/</tt>",
          then the file is treated as a text file; otherwise, it is
          treated as binary.  This option is useful in combination with
          <tt>--auto-props</tt> or <tt>--mime-types</tt>.</td>
      </tr>

      <tr>
        <td align="right"><tt>--default-eol=STYLE</tt></td>
        <td>Usually cvs2svn treats a file as binary unless one of the
          other rules determines that it is not binary and it is not
          marked as binary in CVS.  But if this option is specified,
          then cvs2svn uses the specified style as the default.  STYLE
          can be 'binary' (default), 'native', 'CRLF', 'LF', or 'CR'.
          If you have been diligent about annotating binary files in
          CVS, or if you are confident that the above options will
          catch all of your binary files, then
          <tt>--default-style=native</tt> should give good
          results.</td>
      </tr>

    </table>

  <p>If you don't use any of these options, then cvs2svn will not
    arrange any line-end translation whatsoever.  The file contents in
    the SVN repository should be the same as the contents you would
    get if checking out with CVS on the machine on which cvs2svn is
    run.  This also means that the EOL characters of text files will
    be the same no matter where the SVN data are checked out (i.e.,
    not translated to the checkout machine's EOL format).</p>

  <p>To do a better job, you can use <tt>--auto-props</tt>,
    <tt>--mime-types</tt>, and <tt>--eol-from-mime-type</tt> to
    specify exactly which properties to set on each file based on its
    filename.</p>

  <p>For total control over setting properties on files, you can use
    the <a
    href="cvs2svn.html#options-file-method"><tt>--options</tt>-file
    method</a> and write your own <tt>SVNPropertySetter</tt> in
    Python.  For example,</p>
<pre>
from cvs2svn_lib.property_setters import SVNPropertySetter

class MyPropertySetter(SVNPropertySetter):
  def set_properties(self, s_item):
    if s_item.cvs_rev.cvs_file.cvs_path.startswith('path/to/funny/files/'):
      s_item.svn_props['svn:mime-type'] = 'text/plain'
      s_item.svn_props['svn:eol-style'] = 'CRLF'

ctx.svn_property_setters.append(MyPropertySetter())
</pre>
  <p>See the file <tt>cvs2svn_lib/property_setters.py</tt> for more
    examples.</p>


<h3><a name="path-symbol-transforms" title="#path-symbol-transforms">I
  want a single project but tag-rewriting rules that vary by
  subdirectory.  Can this be done?</a></h3>

  <p>This is an example of how the cvs2svn conversion can be
    customized using Python.</p>

  <p>Suppose you want to write symbol transform rules that are more
    complicated than "replace REGEXP with PATTERN".  This can easily
    be done by adding just a little bit of Python code to your <a
    href="cvs2svn.html#options-file-method">options file</a>.</p>

  <p>When a symbol is encountered, cvs2svn iterates through the list
    of <tt>SymbolTransform</tt> objects defined for the project.  For
    each one, it calls <tt>symbol_transform.transform(cvs_file,
    symbol_name, revision)</tt>.  That method can return
    any legal symbol name, which will be used in the conversion
    instead of the original name.</p>

  <p>To use this feature, you will have to use an <a
    href="cvs2svn.html#options-file-method">options file</a> to start
    the conversion.  You then write a new SymbolTransform class that
    inherits from RegexpSymbolTransform but checks the path before
    deciding whether to transform the symbol.  Add the following to
    your options file:</p>

<pre>
from cvs2svn_lib.symbol_transform import RegexpSymbolTransform

class MySymbolTransform(RegexpSymbolTransform):
    def __init__(self, path, pattern, replacement):
        """Transform only symbols that occur within the specified PATH."""

        self.path = path
        RegexpSymbolTransform.__init__(self, pattern, replacement)

    def transform(self, cvs_file, symbol_name, revision):
        # Is the file is within the path we are interested in?
        if cvs_file.cvs_path.startswith(path + '/'):
            # Yes -> Allow RegexpSymbolTransform to transform the symbol:
            return RegexpSymbolTransform.transform(
                    self, cvs_file, symbol_name, revision)
        else:
            # No -> Return the symbol unchanged:
            return symbol_name

# Note that we use a Python loop to fill the list of symbol_transforms:
symbol_transforms = []
for subdir in ['project1', 'project2', 'project3']:
    symbol_transforms.append(
        MySymbolTransform(
            subdir,
            r'release-(\d+)_(\d+)',
            r'%s-release-\1.\2' % subdir))

# Now register the project, using our own symbol transforms:
run_options.add_project(
    'your_cvs_path',
    trunk_path='trunk',
    branches_path='branches',
    tags_path='tags',
    symbol_transforms=symbol_transforms))
</pre>

  <p>This example causes any symbol under "project1" that looks like
    "release-3_12" to be transformed into a symbol named
    "project1-release-3.12", whereas if the same symbol appears under
    "project2" it will be transformed into
    "project2-release-3.12".</p>


<h3><a name="cvsnt" title="#cvsnt">How can I convert a CVSNT
    repository?</a></h3>

  <p><a href="http://www.cvsnt.org/">CVSNT</a> is a version control
    system that started out by adding support for running CVS under
    Windows NT.  Since then it has made numerous extensions to the RCS
    file format, to the point where CVS compatibility does not imply
    CVSNT compatibility with any degree of certainty.</p>

  <p>cvs2svn <em>might</em> happen to successfully convert a CVSNT
    repository, especially if the repository has never had any
    CVSNT-only features used on it, but <b>this use is not supported
    and should not be expected to work</b>.</p>

  <p>If you want to experiment with converting a CVSNT repository,
    then please consider the following suggestions:</p>

  <ul>
    <li>Use cvs2svn's <tt>--use-cvs</tt> option.</li>

    <li>Use CVSNT's version of the <tt>cvs</tt> executable (i.e.,
      ensure that the first <tt>cvs</tt> program in your $PATH is the
      one that came with CVSNT).</li>

    <li>Carefully check the result of the conversion before you rely
      on it, <em>even if the conversion completed without any
      errors or warnings</em>.</li>

  </ul>

  <p>Patches to support the conversion of CVSNT repositories would, of
    course, be welcome.</p>


<h3><a name="osxsetup" title="#osxsetup">How do I get cvs2svn to run
on OS X 10.5.5?</a></h3>

<p>Attempting to run cvs2svn on a standard OS X 10.5.5 installation
yields the following error:</p>

<blockquote> <p> ERROR: cvs2svn uses the anydbm package, which depends on
lower level dbm libraries.  Your system has dbm, with which cvs2svn is
known to have problems.  To use cvs2svn, you must install a Python dbm
library other than dumbdbm or dbm.  See <a
href="http://python.org/doc/current/lib/module-anydbm.html">http://python.org/doc/current/lib/module-anydbm.html</a>
for more information. </p> </blockquote>

<p>The problem is that the standard distribution of python on OS X
10.5.5 does not include any other dbm libraries other than the
standard dbm.  In order for cvs2svn to work, we need to install the
gdbm library, in addition to a new version of python that enables the
python gdbm module.</p>

<p>The precompiled versions of python for OS X available from
python.org or activestate.com (currently version 2.6.2) do not have
gdbm support turned on.  To check for gdbm support, check for the
library module (<code>libgdmmodule.so</code>) within the python
installation.</p>

<p>Here is the procedure for a successful installation of cvs2svn and
all supporting libs:</p>

<ol>

  <li>Download the gdbm-1.8.3 (or greater) source, unarchive and
    change directory to gdbm-1.8.3. We need to install the gdbm
    libraries so python's gdbm module can use them.

  <ol>

    <li>Type <code>./configure</code></li>

    <li>Edit "Makefile" so that the owner and group are not the
        non-existing "bin" owner and group by changing

<pre>
BINOWN = bin
BINGRP = bin
</pre>
to
<pre>
BINOWN = root
BINGRP = admin
</pre>

    </li>

    <li>Type "make"</li>

    <li>Type "sudo make install"</li>

  </ol>

  </li>

  <li>Download the Python2.6 (or greater) source, unarchive, and
  change directory to Python2.6.  We need to enable python gdbm
  support which is not enabled in the default OS X 10.5.5 installation
  of python, as the gdbm libs are not included.  However, we just
  installed the gdbm libs in step 1, so we can now compile python with
  gdbm support.

  <ol>

    <li>Edit the file "Modules/Setup" by uncommenting the line which
      links against gdbm by changing

<pre>
#gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
</pre>
to
<pre>
gdbm gdbmmodule.c -I/usr/local/include -L/usr/local/lib -lgdbm
</pre>
    </li>

    <li>Edit the file "Modules/Setup" by uncommenting the line to
      create shared libs by changing

<pre>
#*shared*
</pre>
to
<pre>
*shared*
</pre>
    </li>

    <li>Type <code>./configure --enable-framework
    --enable-universalsdk</code> in the top-level
    Python2.6 directory.  This will configure the installation of
    python as a shared OS X framework, and usable with OS X GUI
    frameworks and SDKs. You may have problems building if you don't
    have the SDKs that support the PPC platform. If you do, just
    specify <code>--disable-universalsdk</code>.
    By default, python will be installed in
    "/Library/Frameworks/Python.framework", which is what we
    want.</li>

    <li>Type <code>make</code></li>

    <li>Type <code>sudo make install</code></li>

    <li>Type <code>cd /usr/local/bin; sudo ln -s python2.6 python</code></li>

    <li>Make sure "/usr/local/bin" is at the front of your search path
    in ~/.profile or ~/.bashrc etc.</li>

    <li>Type <code>source ~/.profle</code> or <code>source
    ~/.bashrc</code> etc. or alternatively, just open a new shell
    window.  When you type <code>which python</code> it should give
    you the new version in "/usr/local/bin" <strong>not</strong> the
    one in "/usr/bin".</li>

  </ol>

  </li>

  <li>Download the cvs2svn-2.2.0 (or greater) source, unarchive and
  change directory to cvs2svn-2.2.0.  Many people can't get cvs2svn to
  work except in the installation directory.  The reason for this is
  that the installation places copies of cvs2svn, cvs2svn_libs, and
  cvs2svn_rcsparse in the /Library/Frameworks/Python.framework
  hierarchy.  All we need to do is make a link in /usr/local/bin
  pointing to the location of cvs2svn in the python framework
  hierarchy.  And for good measure we also make links to the lib and
  include directories:

  <ol>

    <li>Type <code>sudo make install</code></li>

    <li>Create the required links by typing the following:

<pre>
sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/bin/cvs2svn /usr/local/bin/cvs2svn
sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6 /usr/local/lib/python2.6
sudo ln -s /Library/Frameworks/Python.framework/Versions/2.6/include/python2.6 /usr/local/include/python2.6
</pre>

    </li>

  </ol>

  </li>

</ol>

<p>The installation is complete. Change directory out of the
cvs2svn-2.2.0 installation directory, and you should be able to run
cvs2svn. Be careful *not* to copy the version of cvs2svn in the
cvs2svn-2.2.0 installation directory to /usr/local/bin, as this has a
different python environment setting at the top of the file than the
one that was installed in the /Library/Frameworks/Python.framework
hierarchy. Follow the instructions exactly, and it should work.
</p>


<hr />

<h2>Problems:</h2>

<h3><a name="atticprob" title="#atticprob">I get an error "A CVS
    repository cannot contain both repo/path/file.txt,v and
    repo/path/Attic/file.txt,v".  What can I do?</a></h3>

<p>Background: Normally, if you have a file called
<tt>path/file.txt</tt> in your project, CVS stores its history in a
file called <tt>repo/path/file.txt,v</tt>.  But if <tt>file.txt</tt>
is deleted on the main line of development, CVS moves its history file
to a special <tt>Attic</tt> subdirectory:
<tt>repo/path/Attic/file.txt,v</tt>.  (If the file is recreated, then
it is moved back out of the <tt>Attic</tt> subdirectory.)  Your
repository should never contain both of these files at the same
time.</p>

<p>This cvs2svn error message thus indicates a mild form of corruption
in your CVS repository.  The file has two conflicting histories, and
even CVS does not know the correct history of <tt>path/file.txt</tt>.
The corruption was probably created by using tools other than CVS to
backup or manipulate the files in your repository.  With a little work
you can learn more about the two histories by viewing each of the
<tt>file.txt,v</tt> files in a text editor.</p>

<p>There are four straightforward approaches to fixing the repository
corruption, but each has potential disadvantages.  Remember to <b>make
a backup</b> before starting.  Never run cvs2svn on a live CVS
repository--always work on a copy of your repository.</p>

<ol>
  <li>Restart the conversion with the
    <tt>--retain-conflicting-attic-files</tt> option.  This causes the
    non-attic and attic versions of the file to be converted
    separately, with the <tt>Attic</tt> version stored to a new
    subdirectory as <tt>path/Attic/file.txt</tt>.  This approach
    avoids losing any history, but by moving the <tt>Attic</tt>
    version of the file to a different subdirectory it might cause
    historical revisions to be broken.</li>

  <li>Remove the <tt>Attic</tt> version of the file and restart the
    conversion.  Sometimes it represents an old version of the file
    that was deleted long ago, and it won't be missed.  But this
    completely discards one of the file's histories, probably causing
    <tt>file.txt</tt> to be missing in older historical revisions.
    (For what it's worth, this is probably how CVS would behave in
    this situation.)

    <pre>
      # You did make a backup, right?
      $ rm repo/path/Attic/file.txt,v
    </pre></li>

  <li>Remove the non-<tt>Attic</tt> version of the file and restart
    the conversion.  This might be appropriate if the
    non-<tt>Attic</tt> version has less important content than the
    <tt>Attic</tt> version.  But this completely discards one of the
    file's histories, probably causing <tt>file.txt</tt> to be missing
    in recent historical revisions.

    <pre>
      # You did make a backup, right?
      $ rm repo/path/file.txt,v
    </pre></li>

  <li>Rename the non-<tt>Attic</tt> version of the file and restart
    the conversion.  This avoids losing history, but it changes the
    name of the non-<tt>Attic</tt> version of the file to
    <tt>file-not-from-Attic.txt</tt> whenever it appeared, and might
    thereby cause revisions to be broken.

    <pre>
      # You did make a backup, right?
      $ mv repo/path/file.txt,v repo/path/file-not-from-Attic.txt,v
    </pre></li>

</ol>

<p>If you run cvs2svn on a case-insensitive operating system, it is
possible to get this error even if the filename of the file in
Attic has different case than the one out of the Attic.  This could
happen, for example, if the CVS repository was served from a
case-sensitive operating system at some time.  A workaround for this
problem is to copy the CVS repository to a case-sensitive operating
system and convert it there.
</p>


<h3><a name="gdbm-nfs" title="#gdbm-nfs">gdbm.error: (45, 'Operation
    not supported')</a></h3>

<p>This has been reported to be caused by trying to create gdbm
databases on an NFS partition.  Apparently gdbm does not support
databases on NFS partitions.  The workaround is to use the
<tt>--tmpdir</tt> option to choose a local partition for cvs2svn to
write its temporary files.</p>


<h3><a name="apple-single" title="#apple-single">When converting a CVS
    repository that was used on a Macintosh, the contents of some
    files are incorrect in SVN.</a></h3>

<p>Some Macintosh CVS clients use a nonstandard trick to store the
resource fork of files in CVS: instead of storing the file contents
directly, store an <a
href="http://rfc.net/rfc1740.html">AppleSingle</a> data stream
containing both the data fork and resource fork.  When checking the
file out, the client unpacks the AppleSingle data and writes the two
forks separately to disk.  By default, cvs2svn treats the file
contents literally, so when you check the file out of Subversion, the
file contains the combined data in AppleSingle format rather than only
the data fork of the file as expected.</p>

<p>Subversion does not have any special facilities for dealing with
Macintosh resource forks, so there is nothing cvs2svn can do to
preserve both forks of your data.  However, sometimes the resource
fork is not needed.  If you would like to discard the resource fork
and only record the data fork in Subversion, then start your
conversion using the <a
href="cvs2svn.html#options-file-method">options file method</a> and
set the following option to <tt>True</tt> in your options file:</p>

<pre>
      ctx.decode_apple_single = True
</pre>

<p>There is more information about this option in the comments in
<tt>cvs2svn-example.options</tt>.</p>


<h3><a name="rcsmissing" title="#installrcs">Using cvs2svn 1.3.x, I
    get an error "The command '['co', '-q', '-x,v', '-p1.1', '-kk',
    '/home/cvsroot/myfile,v']' failed" in pass 8.</a></h3>

<p><i>What are you using cvs2svn version 1.3.x for anyway?
Upgrade!</i></p>

<p>But if you must, either install RCS, or ensure that CVS is
installed and use cvs2svn's <a
href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt></a> option.</p>


<h2>Getting help:</h2>

<h3><a name="gettinghelp" title="#gettinghelp">How do I get
help?</a></h3>

<p>There are several sources of help for cvs2svn:</p>

<ul>

  <li>The <a href="cvs2svn.html">user manual</a> not only describes
  how to run cvs2svn, but also discusses some limitations, pitfalls,
  and conversion strategies.  Please note that the <a
  href="http://cvs2svn.tigris.org/cvs2svn.html">online manual</a>
  describes the latest "bleeding edge" trunk version of the software,
  which may be different than the version that you are using.</li>

  <li>The <a href="faq.html">frequently asked questions (FAQ) list</a>
  is the document that you are now reading.  Please make sure you've
  scanned through the list of topics to see if your question is
  already answered.</li>

  <li>The <a
  href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">mailing
  list archives</a>.  Maybe your question has
  been discussed on either the <tt>user@cvs2svn.tigris.org</tt> or
  <tt>dev@cvs2svn.tigris.org</tt> mailing list.</li>

  <li>If you need help with running cvs2svn or problems converting
  your repository, the <a
  href="mailto:users@cvs2svn.tigris.org"><tt>users@cvs2svn.tigris.org</tt></a>
  mailing list is the first place to send inquiries.  Please <a
  href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">subscribe</a>
  to the list so that you can follow ensuing discussions.</li>

  <li>You can also ask questions on IRC at <a
  href="irc://irc.freenode.net/"><tt>irc.freenode.net</tt></a>,
  channel <tt>#cvs2svn</tt>.</li>

  <li>If you think you have found a bug, please refer to <a
  href="#reportingbugs">"How do I report a bug?"</a></li>

</ul>


<h3><a name="reportingbugs" title="#reportingbugs">How do I report a
bug?</a></h3>

<p>cvs2svn is an open source project that is largely developed and
supported by volunteers in their free time.  Therefore please try to
help out by reporting bugs in a way that will enable us to help you
efficiently.</p>

<p>The first question is whether the problem you are experiencing is
caused by a cvs2svn bug at all.  A large fraction of reported "bugs"
are caused by problems with the user's CVS repository, especially mild
forms of repository corruption or <a href="#cvsnt">trying to convert a
CVSNT repository with cvs2svn</a>.  Please also double-check the <a
href="cvs2svn.html">manual</a> to be sure that you are using the
command-line options correctly.</p>

<p>A good way to localize potential repository corruption is to use
the <tt>shrink_test_case.py</tt> script (which is located in the
<tt>contrib</tt> directory of the cvs2svn source tree).  This script
tries to find the minimum subset of files in your repository that
still shows the same problem.  <b>Warning: Only apply this script to a
backup copy of your repository, as it destroys the repository that it
operates on!</b> Often this script can narrow the problem down to a
single file which, as often as not, is corrupt in some way.  Even if
the problem is not in your repository, the shrunk-down test case will
be useful for reporting the bug.  Please see <a href="#testcase">"How
can I produce a useful test case?"</a> and the comments at the top of
<tt>shrink_test_case.py</tt> for information about how to use this
script.</p>

<p>Assuming that you still think you have found a bug, the next step
is to investigate whether the bug is already known.  Please look
through the <a
href="http://cvs2svn.tigris.org/issue_tracker.html">issue tracker</a>
for bugs that sound familiar.  If the bug is already known, then there
is no need to report it (though possibly you could contribute a <a
href="#testcase">useful test case</a> or a workaround).</p>

<p>If your bug seems new, then the best thing to do is report it via
email to the <a
href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">dev@cvs2svn.tigris.org</a>
mailing list.  Be sure to include the following information in your
message:</p>

<ol>

  <li><em>Exactly what version</em> of cvs2svn are you using?  If you
  are not using an official release, please tell us what branch and
  revision number from the <a
  href="http://cvs2svn.tigris.org/svn/cvs2svn/">svn archive</a> you
  are using.  If you have modified cvs2svn, please tell us exactly
  what you have changed.</li>

  <li>What platform are you using (Linux, BSD, Windows, etc.)?  What
  python version (e.g., type <tt>python --version</tt>)?</li>

  <li>What is the <em>exact command line</em> that you used to start
  the conversion?  If you used the <tt>--options</tt> option, please
  attach a copy of the options file that you used.</li>

  <li>What happened when you ran the program?  Why do you think the
  behavior was wrong?  Include transcripts and/or error output if
  available.</li>

  <li>If at all possible, include a test case repository that we can
  use to reproduce the problem.  See <a href="#testcase">"How can I
  produce a useful test case?"</a> for more information.  In most
  cases, if we cannot reproduce the problem, there is nothing we can
  do to help you.</li>

</ol>


<h3><a name="testcase" title="#testcase">How can I produce a useful
test case?</a></h3>

<p>If you need to <a href="#reportingbugs">report a bug</a>, it is
extremely helpful if you can include a test repository with your bug
report.  In most cases, if we cannot reproduce the problem, there is
nothing we can do to help you.  This section describes ways to
overcome the most common problems that people have in producing a
useful test case.  When you have a reasonable-sized test case (say
under 1 MB--the smaller the better), you can just tar it up and attach
it to the email in which you report the bug.</p>

<h4>If the repository is too big and/or contains proprietary information</h4>

<p>You don't want to send us your proprietary information, and we
don't want to receive it either.  Short of open-sourcing your
software, here is a way to strip out most of the proprietary
information and simultaneously reduce the size of the archive
tremendously.</p>

<p>The <tt>destroy_repository.py</tt> script tries to delete as much
information as possible out of your repository while still preserving
its basic structure (and therefore hopefully any cvs2svn bugs).
Specifically, it tries to delete file descriptions, text content, all
nontrivial log messages, and all author names.  It also renames all
files and directories to have generic names (e.g.,
<tt>dir015/file053,v</tt>).  (It does not affect the number and dates
of revisions to the files.)</p>

<ol>

  <li>This procedure will <b>destroy the repository</b> that it is
  applied to, so be sure to <b>make a backup copy of your
  repository and work with the backup!</b></li>

  <li>Make sure you have the <tt>destroy_repository.py</tt> script.
  If you don't already have it, you should <a
  href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
  source code</a> for cvs2svn (there is no need to install it).  The
  script is located in the <tt>contrib</tt> subdirectory.</li>

  <li>Run <tt>destroy_repository.py</tt> by typing <pre>
# You did make a backup, right?
/path/to/config/destroy_repository.py /path/to/copy/of/repo
</pre></li>

  <li>Verify that the "destroyed" archive does not include any
  information that you consider proprietary.  Your data security is
  ultimately your responsibility, and we make no guarantees that the
  <tt>destroy_repository.py</tt> script works correctly.  You can open
  the *,v files using a text editor to see what they contain.</li>

  <li>Try converting the "destroyed" repository using cvs2svn, and
  ensure that the bug still exists.  Take a note of the exact cvs2svn
  command line that you used and include it along with a tarball of
  the "destroyed" repository with your bug report.</li>

</ol>

<p>If running <tt>destroy_repository.py</tt> with its default options
causes the bug to go away, consider using
<tt>destroy_repository.py</tt> command-line options to leave part of
the repository information intact.  Run <tt>destroy_repository.py
--help</tt> for more information.</p>


<h4>The repository is still too large</h4>

<p>This step is a tiny bit more work, so if your repository is already
small enough to send you can skip this step.  But this step helps
narrow down the problem (maybe even point you to a corrupt file in
your repository!) so it is still recommended.</p>

<p>The <tt>shrink_test_case.py</tt> script tries to delete as many
files and directories from your repository as possible while
preserving the cvs2svn bug.  To use this command, you need to write a
little test script that tries to convert your repository and checks
whether the bug is still present.  The script should exit successfully
(e.g., "<tt>exit 0</tt>") if the bug is still <em>present</em>, and
fail (e.g., "<tt>exit 1</tt>") if the bug has <em>disappeared</em>.
The form of the test script depends on the bug that you saw, but it
can be as simple as something like this:</p>

<pre>
#! /bin/sh

cvs2svn --dry-run /path/to/copy/of/repo 2>&amp;1 | grep -q 'KeyError'
</pre>

<p>If the bug is more subtle, then the test script obviously needs to
be more involved.</p>

<p>Once the test script is ready, you can shrink your repository via
the following steps:</p>

<ol>

  <li>This procedure will <b>destroy the repository</b> that it is
  applied to, so be sure to <b>make a backup copy of your
  repository and work with the backup!</b></li>

  <li>Make sure you have the <tt>shrink_test_case.py</tt> script.
  If you don't already have it, you should <a
  href="http://cvs2svn.tigris.org/servlets/ProjectSource">download the
  source code</a> for cvs2svn (there is no need to install it).  The
  script is located in the <tt>contrib</tt> subdirectory.</li>

  <li>Run <tt>shrink_test_case.py</tt> by typing <pre>
# You did make a backup, right?
/path/to/config/shrink_test_case.py /path/to/copy/of/repo testscript.sh
</pre>, where <tt>testscript.sh</tt> is the name of the test script
  described above.  This script will execute <tt>testscript.sh</tt>
  many times, each time using a subset of the original repository.</li>

  <li>If the shrunken repository only consists of one or two files,
  look inside the files with a text editor to see whether they are
  corrupted in any obvious way.  (Many so-called cvs2svn "bugs" are
  actually the result of a corrupt CVS repository.)</li>

  <li>Try converting the "shrunk" repository using cvs2svn, to make
  sure that the original bug still exists.  Take a note of the exact
  cvs2svn command line that you used, and include it along with a
  tarball of the "destroyed" repository with your bug report.</li>

</ol>


<h3><a name="commercialsupport" title="#commercialsupport">Does
anybody offer commercial support for cvs2svn/cvs2git
conversions?</a></h3>

<p><b>Disclaimer:</b>These links in this section are provided as a
service to cvs2svn/cvs2git users.  Neither Tigris.org, CollabNet
Inc., nor the cvs2svn team guarantee the correctness, validity or
usefulness of these links.  To add a link to this section, please
submit it to the cvs2svn developers' mailing list.</p>

<p>Following is a list of known sources for commercial support for
cvs2svn/cvs2git conversions:</p>

<ul>

  <li>Michael Haggerty, the maintainer of cvs2svn/cvs2git, offers
  individual help with conversions, including implementation of new
  cvs2svn/cvs2git features, on a consulting basis.  Please contact
  Michael <a href="email:mhagger@alum.mit.edu">via email</a> for more
  information.</li>

</ul>


</div>
</body>
</html>