Inline select_k_option() method.
[cvs2svn.git] / www / cvs2svn.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "">
3 <html xmlns="">
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 Documentation</title>
13 </head>
15 <body id="bodycol">
16 <div class="app">
18 <h1>cvs2svn Documentation</h1>
20 <h2>Index</h2>
22 <ul>
24 <li><a href="#intro">Introduction</a></li>
26 <li><a href="#reqs">Requirements</a></li>
28 <li><a href="#install">Installation</a></li>
30 <li><a href="#convert">Deciding how much to convert</a></li>
32 <li><a href="#prep">Prepping your repository</a></li>
34 <li><a href="#cmd-vs-options">Command line vs. options file</a></li>
36 <li><a href="#symbols">Symbol handling</a></li>
38 <li><a href="#cmd-ref">Command line reference</a></li>
40 <li><a href="#examples">A few examples</a></li>
42 </ul>
44 <hr />
46 <h1><a name="intro">Introduction</a></h1>
48 <p>cvs2svn is a program that can be used to migrate a CVS repository
49 to <a href="">Subversion</a> (otherwise
50 known as "SVN") or <a href="">git</a>.
51 Documentation:</p>
53 <ul>
55 <li>The <a href="features.html">list of cvs2svn features</a>
56 explains briefly why converting a repository from CVS is nontrivial
57 and gives a comprehensive list of cvs2svn's many features.</li>
59 <li>The document you are currently reading contains a lot of general
60 information about converting from CVS, and specifically how to use
61 cvs2svn to convert your repository to Subversion.</li>
63 <li><a href="cvs2git.html">cvs2git.html</a> describes how to use
64 cvs2svn to convert your CVS repository to git.</li>
66 <li>The <a href="faq.html">FAQ</a> provides frequently asked
67 questions and answers, including important topics such as how to <a
68 href="faq.html#onetoone">convert multiple project</a> within a
69 single repository, how to <a href="faq.html#eol-fixup">fix problems
70 with end-of-line translation</a>, how to <a
71 href="faq.html#gettinghelp">get more help</a> and how to <a
72 href="faq.html#reportingbugs">report bugs</a> including a <a
73 href="faq.html#testcase">useful test case</a>.</li>
75 </ul>
78 <hr />
80 <h1><a name="reqs">Requirements</a></h1>
82 <p>cvs2svn requires the following:</p>
84 <ul>
86 <li>Direct (filesystem) access to a copy of the CVS repository that
87 you want to convert. cvs2svn parses the files in the CVS
88 repository directly, so it is not enough to have remote CVS
89 access. See the <a href="faq.html#repoaccess">FAQ</a> for more
90 information and a possible workaround.
91 </li>
92 <li>Python 2, version 2.4 or later. See <a
93 href=""></a>.
94 (cvs2svn does <strong>not</strong> work with Python 3.x.)
95 </li>
96 <li>A compatible database library, usually gdbm, and the
97 corresponding Python bindings. Neither dumbdbm nor standard dbm
98 is sufficient.
99 </li>
100 <li>If you use the <tt>--use-rcs</tt> option, then RCS's `co'
101 program is required. The RCS home page is
102 <a href=""
103 ></a>.
104 See the <a href="#use-rcs"><tt>--use-rcs</tt> flag</a> for more
105 details.
106 </li>
107 <li>If you use the <tt>--use-cvs</tt> option, then the `cvs' command
108 is required. The CVS home page is
109 <a href=""></a>.
110 See the <a href="#use-cvs"><tt>--use-cvs</tt> flag</a> for more
111 details.
112 </li>
114 </ul>
116 <h2>CVSNT repositories</h2>
118 <p>cvs2svn does not support conversion of <a
119 href="">CVSNT</a> repositories. Some people have
120 indicated success with such conversions, while others have had
121 problems. In other words, <em>such conversions, even if apparently
122 successful, should be checked carefully before use.</em> See the <a
123 href="faq.html#cvsnt">FAQ</a> for more information.</p>
125 <hr />
127 <h1><a name="install">Installation</a></h1>
129 <ul>
130 <li>As root, run 'make install'.</li>
132 <li>Or, if you do not wish to install cvs2svn on your system, you
133 can simply run it out of this directory. As long as it can find
134 the 'cvs2svn_rcsparse' library, it should be happy.</li>
136 <li>If you want to create Unix-style manpages for the main programs,
137 run 'make man'.</li>
139 </ul>
141 <hr />
143 <h1><a name="convert">Deciding how much to convert</a></h1>
145 <p>If you're looking to switch an existing CVS repository to
146 Subversion, you have a number of choices for migrating your existing
147 CVS data to a Subversion repository, depending on your needs.</p>
149 <p>There are a few basic routes to choose when switching from CVS to
150 Subversion, and the one you choose will depend on how much historical
151 data you want in your Subversion repository. You may be content to
152 refer to your existing (soon-to-be-converted-to-read-only) CVS
153 repository for "pre-Subversion" data and start working with a new
154 Subversion repository. Maybe you prefer to squeeze every last drop of
155 data out of your CVS repository into your Subversion repository. Then
156 again, perhaps you want a conversion somewhere in between these two.
157 Based on these needs, we've come up with these different recommended
158 paths for converting your CVS repository to a Subversion
159 repository.</p>
161 <ul>
163 <li>Top-skim (Doesn't require cvs2svn!)</li>
165 <li>Trunk only</li>
167 <li>Pick and choose</li>
169 <li>Full conversion</li>
171 <li>Smorgasbord</li>
173 <li>One project at a time</li>
175 </ul>
177 <p>If you decide that top-skimming doesn't meet your needs and you're
178 going to use cvs2svn (yay!), then be sure to read the section below on
179 <a href="#prep">prepping your repository</a> before you start your
180 conversion.</p>
183 <h2>Top-skimming</h2>
185 <p>This is the quickest and easiest way to get started in your new
186 repository. You're basically going to export the latest revision of
187 your cvs repository, possibly do some rearranging, and then import the
188 resulting files into your Subversion repository. Typically, if you
189 top-skim, that means you'll be either be keeping your old CVS
190 repository around as a read-only reference for older data or just
191 tossing that historical data outright (Note to you data packrats who
192 have just stopped breathing, please take a deep breath and put down
193 the letter opener. You don't <i>have</i> to do this yourself--it's
194 just that some people don't feel the same way you do about historical
195 data. They're really not <i>bad</i> people. Really.).</p>
197 <blockquote>
199 <p><b>Pros:</b> Quick, easy, convenient, results in a very compact and
200 "neat" Subversion repository.</p>
202 <p><b>Cons:</b> You've got no historical data, no branches, and no tags
203 in your Subversion repository. If you want any of this data, you'll
204 have to go back into the CVS Repository and get it.</p>
206 </blockquote>
209 <h2>Trunk only</h2>
211 <p>If you decide that you'd like to have the main development line of
212 your historical data in your Subversion repository but don't need to
213 carry over the tags and branches, you may want to skip converting your
214 CVS tags and branches entirely and only convert the "trunk" of your
215 repository. To do this, you'll use the <tt>--trunk-only</tt> switch
216 to cvs2svn.</p>
218 <blockquote>
220 <p><b>Pros:</b>Saves disk space in your new Subversion repository.
221 Attractive to neatniks.</p>
223 <p><b>Cons:</b> You've got no branches and no tags in your
224 Subversion repository.</p>
226 </blockquote>
229 <h2>Pick and choose</h2>
231 <p>Let's say, for example, that you want to convert your CVS repository's
232 historical data but you have no use for the myriad daily build tags
233 that you've got in your CVS repository. In addition to that, you want
234 some branches but would prefer to ignore others. In this case, you'll
235 want to use the <tt>--exclude</tt> switch to instruct cvs2svn which
236 branches and tags it should ignore. </p>
238 <blockquote>
240 <p><b>Pros:</b>You only get what you want from your CVS repository.
241 Saves a some space.</p>
243 <p><b>Cons:</b>If you forgot something, you'll have to go to your
244 CVS repository.</p>
246 </blockquote>
249 <h2>Full conversion</h2>
251 <p>If you want to convert your entire CVS repository, including all
252 tags and branches, you want a full conversion. This is cvs2svn's
253 default behavior.</p>
255 <blockquote>
257 <p><b>Pros:</b> Converts every last byte of your CVS repository.</p>
259 <p><b>Cons:</b> Requires more disk space.</p>
261 </blockquote>
264 <h2>Smorgasbord</h2>
266 <p>You can convert your repository (or repositories) piece by piece
267 using a combination of the above .</p>
269 <blockquote>
271 <p><b>Pros:</b> You get exactly what you want.</p>
273 <p><b>Cons:</b> Importing converted repositories multiple times into
274 a single Subversion repository will likely break date-based range
275 commands (e.g. <tt>svn diff -r {2002-02-17:2002-03-18}</tt>) since
276 Subversion does a binary search through the repository for dates.
277 While this is not the end of the world, it can be a minor
278 inconvenience.</p>
280 </blockquote>
283 <h2>One project at a time</h2>
285 <p>If you have many diverse projects in your CVS repository and you
286 don't want to move them all to Subversion at once, you may want to
287 convert to Subversion one project at a time. This requires a few
288 extra steps, but it can make the conversion of a large CVS repository
289 much more manageable. See <a href="faq.html#oneatatime">How can I
290 convert my CVS repository one module at a time?</a> on the cvs2svn FAQ
291 for a detailed example on converting your CVS repository one project
292 at a time.</p>
294 <blockquote>
296 <p><b>Pros:</b>Allows multiple projects in a single repository to
297 convert to Subversion according to a schedule that works best for
298 them.</p>
300 <p><b>Cons:</b>Requires some extra steps to accomplish the
301 conversion. Importing converted repositories multiple times into a
302 single Subversion repository will likely break date-based range
303 commands (e.g. <tt>svn diff -r {2002-02-17:2002-03-18}</tt>) since
304 Subversion does a binary search through the repository for dates.
305 While this is not the end of the world, it can be a minor
306 inconvenience.</p>
308 </blockquote>
310 <hr />
312 <h1><a name="prep">Prepping your repository</a></h1>
314 <p>There are a number of reasons that you may need to prep your CVS
315 Repository. If you decide that you need to change part of your CVS
316 repository, we <b>strongly</b> recommend working on a <b>copy</b> of
317 it instead of working on the real thing. cvs2svn itself does not make
318 any changes to your CVS repository, but if you start moving things
319 around and deleting things in a CVS repository, it's all too easy to
320 shoot yourself in the foot.</p>
322 <h2>End-of-line translation</h2>
324 <p>One of the most important topics to consider when converting a
325 repository is the distinction between binary and text files. If you
326 accidentally treat a binary file as text <strong>your repository
327 contents will be corrupted</strong>.</p>
329 <p>Text files are handled differently than binary files by both CVS
330 and Subversion. When a text file is checked out, the character used
331 to denote the end of line ("EOL") is converted to the local computer's
332 format. This is usually the most convenient behavior for text files.
333 Moreover, both CVS and Subversion allow "keywords" in text files (such
334 as <tt>$Id$</tt>), which are expanded with version control information
335 when the file is checked out. However, if line-end translation or
336 keyword expansion is applied to a binary file, the file will usually
337 be corrupted.</p>
339 <p>CVS treats a file as text unless you specifically tell it that the
340 file is binary. You can tell CVS that a file is binary by using the
341 command <tt>cvs admin -kb <i>filename</i></tt>. But often CVS users
342 forget to specify which files are binary, and as long as the
343 repository is only used under Unix, they may never notice a problem,
344 because the internal format of CVS is the same as the Unix format.
345 But Subversion is not as forgiving as CVS if you tell it to treat a
346 binary file as text.</p>
348 <p>If you have been conscientious about marking files as binary in
349 CVS, then you should be able to use <tt>--default-eol=native</tt>. If
350 you have been sloppy, then you have a few choices:</p>
351 <ul>
352 <li>Convert your repository with cvs2svn's default options. Your
353 text files will be treated as binary, but that usually isn't very
354 harmful (at least no information will be lost).</li>
356 <li>Mend your slovenly ways by fixing your CVS repository
357 <em>before</em> conversion: run <tt>cvs admin -kb
358 <i>filename</i></tt> for each binary file in the repository. Then
359 you can use <tt>--default-eol=native</tt> along with the
360 anal-retentive folks.</li>
362 <li>Use cvs2svn options to help cvs2svn deduce which files are
363 binary <em>during</em> the conversion. The useful options are
364 <tt>--eol-from-mime-type</tt>, <tt>--keywords-off</tt>,
365 <tt>--auto-props</tt>, and <tt>--default-eol</tt>. See the <a
366 href="faq.html#eol-fixup">FAQ</a> for more information.</li>
368 </ul>
370 <h2>Converting part of repository</h2>
372 <p>If you want to convert a subdirectory in your repository, you can
373 just point cvs2svn at the subdirectory and go. There is no need to
374 delete the unwanted directories from the CVS repository.</p>
376 <p>If the subdirectory that you are converting contains any files that
377 you <i>don't</i> want converted into your new Subversion repository,
378 you should delete them or move them aside. Such files can be deleted
379 from HEAD after the conversion, but they will still be visible in the
380 repository history.</p>
382 <p>Lastly, even though you can move and copy files and directories
383 around in Subversion, you may want to do some rearranging of project
384 directories before running your conversion to get the desired
385 repository project organization.</p>
387 <hr />
389 <h1><a name="cmd-vs-options">Command line vs. options file</a></h1>
391 <p>There are two ways to specify the options that define a conversion:
392 via the cvs2svn command line, or via an options file. The command
393 line is useful for simple conversions, but the options file method is
394 recommended for nontrivial conversions as it gives the user more
395 flexibility.</p>
397 <h2><a name="cmd-line-method">Command line method</a></h2>
399 <p>A command-line conversion allows the use of all of the command line
400 options listed <a href="#cmd-ref">below</a> (except for
401 <tt>--options</tt>). This method allows almost all of the built-in
402 conversion options to be selected, with the primary limitation that it
403 does not support multiproject conversions. However, it may require a
404 <em>long</em> command line to specify all of the options for a
405 complicated conversion.</p>
408 <h2><a name="options-file-method">Options file method</a></h2>
410 <p>The options file method allows full control of the conversion
411 process, including multiproject conversions. It also allows expert
412 users to customize the conversion even more radically by writing
413 Python code. Finally, the options file used in the conversion can be
414 retained as permanent record of the options used in a conversion.</p>
416 <p>To use the options file method, you need to create a file defining
417 all of the options that are to be used for the conversion. A
418 heavily-commented sample options file,
419 <tt>cvs2svn-example.options</tt>, is included in the cvs2svn
420 distribution. The easiest way to create your own options file is to
421 make a copy of the sample file and modify it as directed by the
422 comments in that file.</p>
424 <p><strong>Note:</strong> The options file format changes frequently.
425 Please be sure to base your options file on the
426 <tt>cvs2svn-example.options</tt> file from the version of cvs2svn that
427 you plan to use.</p>
429 <p>To start a conversion using an options file, invoke cvs2svn like
430 this:</p>
432 <pre>
433 $ cvs2svn --options=OPTIONSFILE
434 </pre>
436 <p>Only the following options are allowed in combination with
437 <tt>--options</tt>: <tt>-h/--help</tt>, <tt>--help-passes</tt>,
438 <tt>--version</tt>, <tt>-v/--verbose</tt>, <tt>-q/--quiet</tt>,
439 <tt>-p/--pass/--passes</tt>, <tt>--dry-run</tt>, and
440 <tt>--profile</tt>.</p>
442 <hr />
445 <h1><a name="symbols">Symbol handling</a></h1>
447 <p>cvs2svn converts CVS tags and branches into Subversion tags and
448 branches. This section discusses issues related to symbol
449 handling.</p>
451 <p><strong>HINT:</strong> If there are problems with symbol usage in
452 your repository, they are usually reported during
453 <tt>CollateSymbolsPass</tt> of the conversion, causing the conversion
454 to be interrupted. However, it is not necessary to restart the whole
455 conversion to fix the problems. Usually it is adequate to adjust the
456 symbol-handling options then re-start cvs2svn starting at
457 <tt>CollateSymbolsPass</tt>, by adding the option "<tt>-p
458 CollateSymbolsPass:</tt>". This trick can save a lot of time if you
459 have a large repository, as it might take a few iterations before you
460 find the best set of options to convert your repository.</p>
463 <h2><a name="symbol-layout">Placement of trunk, branches, and tags
464 directories</a></h2>
466 <p>cvs2svn converts CVS branches and tags into Subversion branches and
467 tags following the <a
468 href="">standard
469 Subversion convention</a>. For single-project conversions, the
470 default is to put the trunk, branches, and tags directories at the top
471 level of the repository tree, though this behavior can be changed by
472 using the <tt>--trunk</tt>, <tt>--branches</tt>, and <tt>--tags</tt>
473 options. For multiproject conversions, you must specify the location
474 of each project's trunk, branches, and tags directory in the options
475 file; <a
476 href="">repository
477 layout strategies</a> are discussed in the <a
478 href="">Subversion book</a>. For even
479 finer control over the conversion, you can use a
480 <tt>--symbol-hints</tt> file to specify the SVN path to be used for
481 each CVS tag and branch.</p>
484 <h2><a name="symbol-exclusion">Excluding tags and branches</a></h2>
486 <p>Often a CVS repository contains tags and branches that will not be
487 needed after the conversion to Subversion. You can instruct cvs2svn
488 to exclude such symbols from the conversion, in which case they will
489 not be present in the resulting Subversion repository. Please be
490 careful when doing this; excluding symbols causes information that was
491 present in CVS to be omitted in Subversion, thereby discarding
492 potentially useful historical information. Also be aware that if you
493 exclude a branch, then all CVS revisions that were committed to that
494 branch will also be excluded.</p>
496 <p>To exclude a tag or branch, use the option
497 <tt>--exclude=SYMBOL</tt>. You can also exclude a whole group of
498 symbols matching a specified regular expression; for example,
499 <tt>--exclude='RELEASE_0_.*'</tt>. (The regular expression has to
500 match the <em>whole</em> symbol name for the rule to apply.)</p>
502 <p>However, please note the following restriction. If a branch has a
503 subbranch or a tag on it, then the branch cannot be excluded unless
504 the dependent symbol is also excluded. cvs2svn checks for this
505 situation; if it occurs then <tt>CollateSymbolsPass</tt> outputs an
506 error message like the following:</p>
508 <pre>
509 ERROR: The branch 'BRANCH' cannot be excluded because the following symbols depend on it:
510 'TAG'
512 </pre>
514 <p>In such a case you can either exclude the dependent symbol(s) (in
515 this case by using <tt>--exclude=TAG --exclude=SUBBRANCH</tt>) or
516 <em>not</em> exclude 'BRANCH'.</p>
518 <h3>Excluding vendor branches</h3>
520 <p>There is one more special case related to branch handling. A <a
521 href="">vendor
522 branch</a> is a CVS branch that is used to track source code received
523 from an outside source. A vendor branch typically has CVS branch
524 number <tt>1.1.1</tt> and revision numbers <tt></tt>,
525 <tt></tt>, etc. Vendor branches are created automatically
526 whenever the <tt>cvs import</tt> command is used. Vendor branches
527 have the strange property that, under certain circumstances, a file
528 that appears on a vendor branch also implicitly exists on trunk.
529 cvs2svn knows all about vendor branches and does its best to ensure
530 that a file that appears on a vendor branch is also copied to trunk,
531 to give Subversion behavior that is as close as possible to the CVS
532 behavior.</p>
534 <p>However, often vendor branches exist for reasons unrelated to
535 tracking outside sources. Indeed, some CVS documentation recommends
536 using the <tt>cvs import</tt> command to import your own code into
537 your CVS repository (which is arguably a misuse of the <tt>cvs
538 import</tt> command). Vendor branches created by this practice are
539 useless and would only serve to clutter up your Subversion repository.
540 Therefore, cvs2svn allows vendor branches to be excluded, in which
541 case the vendor branch revisions are grafted onto the history of
542 trunk. This is allowed <em>even if</em> other branches or tags appear
543 to sprout from the vendor branch, in which case the dependent tags are
544 grafted to trunk as well. Such branches can be recognized in the
545 <tt>--write-symbol-info</tt> by looking for a symbol that is a "pure
546 import" in the same number of files that it appears as a branch. It
547 is typically advantageous to exclude such branches.</p>
550 <h2><a name="symbol-inconsistencies">Tag/branch inconsistencies</a></h2>
552 <p>In CVS, the same symbol can appear as a tag in some files (e.g.,
553 <tt>cvs tag SYMBOL file1.txt</tt>) and a branch in others (e.g.,
554 <tt>cvs tag -b SYMBOL file2.txt</tt>). Subversion takes a more global
555 view of your repository, and therefore works better when each symbol
556 is used in a self-consistent way--either always as a branch or always
557 as a tag. cvs2svn provides features to help you resolve these
558 ambiguities.</p>
560 <p>If your repository contains inconsistently-used symbols, then
561 <tt>CollateSymbolsPass</tt>, by default, uses heuristics to decide
562 which symbols to convert as branches and which as tags. Often this
563 behavior will be adequate, and you don't have to do anything special.
564 You can use the <tt>--write-symbol-info=<i>filename</i></tt> option to
565 cause cvs2svn to list all of the symbols in your repository and how it
566 chose to convert them to <tt><i>filename</i></tt>.</p>
568 <p>However, if you want to take finer control over how symbols are
569 converted, you can do so. The first step is probably to change the
570 default symbol handling style from <tt>heuristic</tt> (the default
571 value) to <tt>strict</tt> using the option
572 <tt>--symbol-default=strict</tt>. With the <tt>strict</tt> setting,
573 cvs2svn prints error messages and aborts the conversion if there are
574 any ambiguous symbols. The error messages look like this:</p>
576 <pre>
577 ERROR: It is not clear how the following symbols should be converted.
578 Use --symbol-hints, --force-tag, --force-branch, --exclude, and/or
579 --symbol-default to resolve the ambiguity.
580 'SYMBOL1' is a tag in 1 files, a branch in 2 files and has commits in 0 files
581 'SYMBOL2' is a tag in 2 files, a branch in 1 files and has commits in 0 files
582 'SYMBOL3' is a tag in 1 files, a branch in 2 files and has commits in 1 files
583 </pre>
585 <p>You have to tell cvs2svn how to fix the inconsistencies then
586 restart the conversion at <tt>CollateSymbolsPass</tt>.</p>
588 <p>There are three ways to deal with an inconsistent symbol: treat it
589 as a tag, treat it as a branch, or exclude it from the conversion
590 altogether.</p>
592 <p>In the example above, the symbol 'SYMBOL1' was used as a branch in
593 two files but used as a tag in only one file. Therefore, it might
594 make sense to convert it as a branch, by using the option
595 <tt>--force-branch=SYMBOL1</tt>. However, no revisions were committed
596 on this branch, so it would also be possible to convert it as a tag,
597 by using the option <tt>--force-tag=SYMBOL1</tt>. If the symbol is
598 not needed at all, it can be excluded by using
599 <tt>--exclude=SYMBOL1</tt>.</p>
601 <p>Similarly, 'SYMBOL2' was used more often as a tag, but can still be
602 converted as a branch or a tag, or excluded.</p>
604 <p><tt>SYMBOL3</tt>, on the other hand, was sometimes used as a
605 branch, and at least one revision was committed on the branch. It can
606 be converted as a branch, using <tt>--force-branch=SYMBOL3</tt>. But
607 it cannot be converted as a tag (because tags are not allowed to have
608 revisions on them). If it is excluded, using
609 <tt>--exclude=SYMBOL3</tt>, then both the branch and the revisions on
610 the branch will be left out of the Subversion repository.</p>
612 <p>If you are not so picky about which symbols are converted as tags
613 and which as branches, you can ask cvs2svn to decide by itself. To do
614 this, specify the <tt>--symbol-default=OPTION</tt>, where
615 <tt>OPTION</tt> can be either "<tt>heuristic</tt>" (the default;
616 decide how to treat each ambiguous symbol based on whether it was used
617 more often as a branch or as a tag in CVS), "<tt>branch</tt>" (treat
618 every ambiguous symbol as a branch), or "<tt>tag</tt>" (treat every
619 ambiguous symbol as a tag). You can use the <tt>--force-branch</tt>
620 and <tt>--force-tag</tt> options to specify the treatment of
621 particular symbols, in combination with <tt>--symbol-default</tt> to
622 specify the default to be used for other ambiguous symbols.</p>
624 <p>Finally, you can have cvs2svn write a text file showing how each
625 symbol was converted by using the <tt>--write-symbol-info</tt> option.
626 If you disagree with any of cvs2svn's choices, you can make a copy of
627 this file, edit it, then pass it to cvs2svn by using the
628 <tt>--symbol-hints</tt> option. In this manner you can influence how
629 each symbol is converted and also the parent line of development of
630 each symbol (the line of development from which the symbol
631 sprouts).</p>
633 <hr />
636 <h1><a name="cmd-ref">Command line reference</a></h1>
638 <table border="1" cellpadding="10" cellspacing="3" width="80%">
640 <tr>
641 <td colspan="2">
642 <strong>USAGE:</strong><br/>
643 <tt>cvs2svn [OPTIONS]... [-s SVN-REPOS-PATH|--dumpfile=PATH|--dry-run]
644 CVS-REPOS-PATH</tt><br/>
645 <tt>cvs2svn [OPTIONS]... --options=PATH</tt><br/>
646 </td>
647 </tr>
649 <tr>
650 <td align="right"><tt>CVS-REPOS-PATH</tt></td>
651 <td>The filesystem path of the part of the CVS repository that you
652 want to convert. It is not possible to convert a CVS repository
653 to which you only have remote access; see <a
654 href="faq.html#repoaccess">the FAQ</a> for details. This
655 doesn't have to be the top level directory of a CVS repository;
656 it can point at a project within a repository, in which case
657 only that project will be converted. This path or one of its
658 parent directories has to contain a subdirectory called CVSROOT
659 (though the CVSROOT directory can be empty).</td>
660 </tr>
662 <tr>
663 <th colspan="2">
664 Configuration via options file
665 </th>
666 </tr>
668 <tr>
669 <td align="right"><tt>--options=PATH</tt></td>
670 <td>Read the conversion options from the specified file. See
671 section <a href="#options-file-method">options file method</a>
672 for more information.</td>
673 </tr>
675 <tr>
676 <th colspan="2">
677 Output options
678 </th>
679 </tr>
681 <tr>
682 <td align="right"><tt>-s PATH</tt><br/><tt>--svnrepos PATH</tt></td>
683 <td>Write the output of the conversion into a Subversion
684 repository located at PATH. This option causes a new Subversion
685 repository to be created at PATH unless the
686 <tt>--existing-svnrepos</tt> option is also used.</td>
687 </tr>
689 <tr>
690 <td align="right"><tt>--existing-svnrepos</tt></td>
691 <td>Load the converted CVS repository into an existing Subversion
692 repository, instead of creating a new repository. (This option
693 should be used in combination with
694 <tt>-s</tt>/<tt>--svnrepos</tt>.) The repository must either be
695 empty or contain no paths that overlap with those that will
696 result from the conversion. Please note that you need write
697 permission for the repository files.</td>
698 </tr>
700 <tr>
701 <td align="right"><tt>--fs-type=TYPE</tt></td>
702 <td>Pass the <tt>--fs-type=TYPE</tt> option to "svnadmin
703 create" if creating a new Subversion repository.</td>
704 </tr>
706 <tr>
707 <td align="right"><tt>--bdb-txn-nosync</tt></td>
708 <td>Pass the <tt>--bdb-txn-nosync</tt> switch to "svnadmin
709 create" if creating a new Subversion repository.</td>
710 </tr>
712 <tr>
713 <td align="right"><tt>--create-option=OPT</tt></td>
714 <td>Pass OPT to "svnadmin create" if creating a new Subversion
715 repository (can be specified multiple times to pass multiple
716 options).</td>
717 </tr>
719 <tr>
720 <td align="right"><tt>--dumpfile=PATH</tt></td>
721 <td>Output the converted CVS repository into a Subversion dumpfile
722 instead of a Subversion repository (useful for importing a CVS
723 repository into an existing Subversion repository). PATH is the
724 filename in which to store the dumpfile.</td>
725 </tr>
727 <tr>
728 <td align="right"><tt>--dry-run</tt></td>
729 <td>Do not create a repository or a dumpfile; just print the details
730 of what cvs2svn would do if it were really converting your
731 repository.</td>
732 </tr>
734 <tr>
735 <th colspan="2">
736 Conversion options
737 </th>
738 </tr>
740 <tr>
741 <td align="right"><tt>--trunk-only</tt></td>
742 <td>Convert only the main line of development from the CVS
743 repository (commonly referred to in Subversion parlance as
744 "trunk"), ignoring all tags and branches.</td>
745 </tr>
747 <tr>
748 <td align="right"><tt>--trunk=PATH</tt></td>
749 <td>The top-level path to use for trunk in the Subversion
750 repository. The default value is "trunk".</td>
751 </tr>
753 <tr>
754 <td align="right"><tt>--branches=PATH</tt></td>
755 <td>The top-level path to use for branches in the Subversion
756 repository. The default value is "branches".</td>
757 </tr>
759 <tr>
760 <td align="right"><tt>--tags=PATH</tt></td>
761 <td>The top-level path to use for tags in the Subversion
762 repository. The default value is "tags".</td>
763 </tr>
765 <tr>
766 <td align="right"><tt>--include-empty-directories</tt></td>
767 <td>Treat empty subdirectories within the CVS repository as actual
768 directories, creating them when the parent directory is created
769 and removing them if and when the parent directory is pruned.</td>
770 </tr>
772 <tr>
773 <td align="right"><tt>--no-prune</tt></td>
774 <td>When all files are deleted from a directory in the Subversion
775 repository, don't delete the empty directory (the default is to
776 delete any empty directories.</td>
777 </tr>
779 <tr>
780 <td align="right"><tt>--encoding=ENC</tt></td>
781 <td>Use ENC as the encoding for filenames, log messages, and
782 author names in the CVS repos. (By using an <tt>--options</tt>
783 file, it is possible to specify one set of encodings to use for
784 filenames and a second set for log messages and author names.)
785 This option may be specified multiple times, in which case the
786 encodings are tried in order until one succeeds. Default:
787 ascii. Other possible values include the <a
788 href="">standard
789 Python encodings</a>.</td>
790 </tr>
792 <tr>
793 <td align="right"><tt>--fallback-encoding=ENC</tt></td>
794 <td>If none of the encodings specified with <tt>--encoding</tt>
795 succeed in decoding an author name or log message, then fall
796 back to using ENC in lossy 'replace' mode. Use of this option
797 may cause information to be lost, but at least it allows the
798 conversion to run to completion. This option only affects the
799 encoding of log messages and author names; there is no fallback
800 encoding for filenames. (By using an <tt>--options</tt> file,
801 it is possible to specify a fallback encoding for filenames.)
802 Default: disabled.</td>
803 </tr>
805 <tr>
806 <td align="right"><tt>--no-cross-branch-commits</tt></td>
807 <td>Prevent the creation of SVN commits that affect multiple
808 branches or trunk and a branch. Instead, break such changesets
809 into multiple commits, one per branch.</td>
810 </tr>
812 <tr>
813 <td align="right"><tt>--retain-conflicting-attic-files</tt></td>
814 <td>If a file appears both inside an outside of the CVS attic,
815 retain the attic version in an SVN subdirectory called `Attic'.
816 (Normally this situation is treated as a fatal error.)</td>
817 </tr>
819 <tr>
820 <th colspan="2">
821 Symbol handling
822 </th>
823 </tr>
825 <tr>
826 <td align="right"><tt>--symbol-transform=PAT:SUB</tt></td>
827 <td><p>Transform RCS/CVS symbol names before entering them into
828 Subversion. PAT is a Python regular expression pattern that is
829 matched against the entire symbol name. If it matches, the
830 symbol is replaced with SUB, which is a replacement pattern
831 using Python's reference syntax. You may specify any number of
832 these options; they will be applied in the order given on the
833 command line.</p>
835 <p>This option can be useful if you're converting a repository in
836 which the developer used directory-wide symbol names like 1_0, 1_1
837 and 2_1 as a kludgy form of release tagging (the C-x v s command
838 in Emacs VC mode encourages this practice). A command like</p>
840 <pre>
841 cvs2svn --symbol-transform='([0-9])-(.*):release-\1.\2' -s SVN RCS
842 </pre>
844 <p>will transform a local CVS repository into a local SVN repository,
845 performing the following sort of mappings of RCS symbolic names to
846 SVN tags:</p>
848 <pre>
849 1-0 &rarr; release-1.0
850 1-1 &rarr; release-1.1
851 2-0 &rarr; release-2.0
852 </pre>
853 </td>
854 </tr>
856 <tr>
857 <td align="right"><tt>--symbol-hints=PATH</tt></td>
858 <td><p>Read symbol conversion hints from PATH. The format of PATH is
859 the same as the format output by <tt>--write-symbol-info</tt>,
860 namely a text file with four whitespace-separated columns:</p>
862 <pre>
863 project-id symbol conversion svn-path parent-lod-name
864 </pre>
866 <p><i>project-id</i> is the numerical ID of the project to which
867 the symbol belongs, counting from 0. <i>project-id</i> can be
868 set to '.' if project-specificity is not needed.
869 <i>symbol-name</i> is the name of the symbol being specified.
870 <i>conversion</i> specifies how the symbol should be converted,
871 and can be one of the values 'branch', 'tag', or 'exclude'. If
872 <i>conversion</i> is '.', then this rule does not affect how the
873 symbol is converted. <i>svn-path</i> is the name of the SVN
874 path to which this line of development should be written. If
875 <i>svn-path</i> is omitted or '.', then this rule does not
876 affect the SVN path of this symbol. <i>parent-lod-name</i> is
877 the name of the symbol from which this symbol should sprout, or
878 '.trunk.' if the symbol should sprout from trunk. If
879 <i>parent-lod-name</i> is omitted or '.', then this rule does
880 not affect the preferred parent of this symbol. The file may
881 contain blank lines or comment lines (lines whose first
882 non-whitespace character is '#').</p>
884 <p>The simplest way to use this option is to run the conversion
885 through CollateSymbolsPass with <tt>--write-symbol-info</tt>
886 option, copy the symbol info and edit it to create a hints file,
887 then re-start the conversion at <tt>CollateSymbolsPass</tt> with
888 this option enabled.</p></td>
889 </tr>
891 <tr>
892 <td align="right"><tt>--symbol-default=OPT</tt></td>
893 <td>Specify how to convert ambiguous symbols (i.e., those that
894 appear in the CVS archive as both branches and tags).
895 <tt>OPT</tt> is one of the following:<ul>
897 <li>"<tt>heuristic</tt>": Decide how to treat each ambiguous
898 symbol based on whether it was used more often as a branch
899 or tag in CVS. (This is the default behavior.)</li>
901 <li>"<tt>strict</tt>": No default; every ambiguous symbol has
902 to be resolved manually using <tt>--symbol-hints</tt>,
903 <tt>--force-branch</tt>, <tt>--force-tag</tt>, or
904 <tt>--exclude</tt>.</li>
906 <li>"<tt>branch</tt>": Treat every ambiguous symbol as a
907 branch.</li>
909 <li>"<tt>tag</tt>": Treat every ambiguous symbols as a
910 tag.</li>
912 </ul>
913 </td>
914 </tr>
916 <tr>
917 <td align="right"><tt>--force-branch=REGEXP</tt></td>
918 <td>Force symbols whose names match REGEXP to be branches.</td>
919 </tr>
921 <tr>
922 <td align="right"><tt>--force-tag=REGEXP</tt></td>
923 <td>Force symbols whose names match REGEXP to be tags. This will
924 cause an error if such a symbol has commits on it.</td>
925 </tr>
927 <tr>
928 <td align="right"><tt>--exclude=REGEXP</tt></td>
929 <td>Exclude branches and tags whose names match REGEXP from
930 the conversion.</td>
931 </tr>
933 <tr>
934 <td align="right"><tt>--keep-trivial-imports</tt></td>
935 <td>Do not exclude branches that were only used for a single
936 import. (By default such branches are excluded because they
937 are usually created by the inappropriate use of <tt>cvs
938 import</tt>.)</td>
939 </tr>
941 <tr>
942 <th colspan="2">
943 Subversion properties
944 </th>
945 </tr>
947 <tr>
948 <td align="right"><tt>--username=NAME</tt></td>
949 <td>Use NAME as the author for cvs2svn-synthesized commits (the
950 default value is no author at all.</td>
951 </tr>
953 <tr>
954 <td align="right"><tt>--auto-props=FILE</tt></td>
955 <td>
957 <p>Specify a file in the format of Subversion's config file,
958 whose <tt>[auto-props]</tt> section can be used to set
959 arbitrary properties on files in the Subversion repository
960 based on their filenames. (The <tt>[auto-props]</tt> section
961 header must be present; other sections of the config file,
962 including the <tt>enable-auto-props</tt> setting, are
963 ignored.) Filenames are matched to the filename patterns
964 case-insensitively, consistent with Subversion's behavior.
965 The auto-props file might have content like this:</p>
967 <pre>
968 [auto-props]
969 *.txt = svn:mime-type=text/plain;svn:eol-style=native
970 *.doc = svn:mime-type=application/msword;!svn:eol-style
971 </pre>
973 <p>Please note that cvs2svn allows properties to be explicitly
974 <em>unset</em>: if cvs2svn sees a setting like
975 <tt>!svn:eol-style</tt> (with a leading exclamation point), it
976 forces the property to remain <em>unset</em>, even if later
977 rules would otherwise set the property.</p>
979 </td>
980 </tr>
982 <tr>
983 <td align="right"><tt>--mime-types=FILE</tt></td>
984 <td>Specify an apache-style mime.types file for setting
985 <tt>svn:mime-type</tt> properties on files in the Subversion
986 repository.</td>
987 </tr>
989 <tr>
990 <td align="right"><tt>--eol-from-mime-type</tt></td>
991 <td>For files that don't have the <tt>kb</tt> expansion mode but
992 have a known mime type, set the eol-style based on the mime
993 type. For such files, set the <tt>svn:eol-style</tt> property
994 to "native" if the mime type begins with "text/", and leave it
995 unset (i.e., no EOL translation) otherwise. Files with unknown
996 mime types are not affected by this option. This option has no
997 effect unless the <tt>--mime-types</tt> option is also
998 specified.</td>
999 </tr>
1001 <tr>
1002 <td align="right"><tt>--default-eol=STYLE</tt></td>
1003 <td>Set <tt>svn:eol-style</tt> to STYLE for files that don't have
1004 the <tt>kb</tt> expansion mode and whose end-of-line translation
1005 mode hasn't been determined by one of the other options. STYLE
1006 can be "<tt>binary</tt>" (default), "<tt>native</tt>",
1007 "<tt>CRLF</tt>", "<tt>LF</tt>", or "<tt>CR</tt>".</td>
1008 </tr>
1010 <tr>
1011 <td align="right"><tt>--keywords-off</tt></td>
1012 <td>By default, cvs2svn sets <tt>svn:keywords</tt> on CVS files to
1013 "author id date" if the mode of the RCS file in question is
1014 either kv, kvl or <b>not</b> kb. If you use the
1015 <tt>--keywords-off</tt> switch, cvs2svn will not set
1016 <tt>svn:keywords</tt> for any file. While this will not touch
1017 the keywords in the contents of your files, Subversion will not
1018 expand them.</td>
1019 </tr>
1021 <tr>
1022 <td align="right"><tt>--keep-cvsignore</tt></td>
1023 <td>Include <tt>.cvsignore</tt> files in the output. (Normally
1024 they are unneeded because cvs2svn sets the corresponding
1025 <tt>svn:ignore</tt> properties.)</td>
1026 </tr>
1028 <tr>
1029 <td align="right"><tt>--cvs-revnums</tt></td>
1030 <td>Record CVS revision numbers as file properties in the
1031 Subversion repository. (Note that unless it is removed
1032 explicitly, the last CVS revision number will remain associated
1033 with the file even after the file is changed within
1034 Subversion.)</td>
1035 </tr>
1037 <tr>
1038 <th colspan="2">
1039 Extraction options
1040 </th>
1041 </tr>
1043 <tr>
1044 <td align="right">
1045 <a name="use-internal-co"><tt>--use-internal-co</tt></a>
1046 </td>
1047 <td>Use internal code to extract the contents of CVS revisions.
1048 This is the default extraction option. This is up to 50% faster
1049 than <tt>--use-rcs</tt>, but needs a lot of disk space: roughly
1050 the size of your CVS repository plus the peak size of a complete
1051 checkout of the repository with all branches that existed and
1052 still had commits pending at a given time. If this option is
1053 used, the <tt>$Log$</tt> keyword is not handled.
1054 </td>
1055 </tr>
1057 <tr>
1058 <td align="right"><a name="use-rcs"><tt>--use-rcs</tt></a></td>
1059 <td>Use RCS's <b><tt>co</tt></b> command to extract the contents
1060 of CVS revisions. RCS is much faster than CVS, but in certain
1061 rare cases it has problems with data that CVS can handle.
1062 Specifically:
1063 <ul>
1064 <li>RCS can't handle spaces in author names:<br/>
1065 <a href=""
1066 ></a>
1067 </li>
1068 <li>"Unterminated keyword" misread by RCS:<br/>
1069 <a href=""
1070 ></a>
1071 </li>
1072 <li>RCS handles the "$Log$" keyword differently from CVS:<br/>
1073 <a href=""
1074 ></a>
1075 </li>
1076 </ul>
1077 If you are having trouble in <tt>OutputPass</tt> of a
1078 conversion when using the <tt>--use-rcs</tt> option, the first
1079 thing to try is using the <tt>--use-cvs</tt> option instead.
1080 </td>
1081 </tr>
1083 <tr>
1084 <td align="right"><a name="use-cvs"><tt>--use-cvs</tt></a></td>
1085 <td>If RCS <b><tt>co</tt></b> is having trouble extracting CVS
1086 revisions, you may need to pass this flag, which causes cvs2svn
1087 to use CVS instead of RCS to read the repository. See <a
1088 href="#use-rcs"><tt>--use-rcs</tt></a> for more information.
1089 </td>
1090 </tr>
1092 <tr>
1093 <th colspan="2">
1094 Environment options
1095 </th>
1096 </tr>
1098 <tr>
1099 <td align="right"><tt>--tmpdir=PATH</tt></td>
1100 <td>Use the directory PATH for all of cvs2svn's temporary data
1101 (which can be a <i>lot</i> of data). The default value is
1102 <tt>cvs2svn-tmp</tt> in the current working directory.</td>
1103 </tr>
1105 <tr>
1106 <td align="right"><tt>--svnadmin=PATH</tt></td>
1107 <td>If the <tt>svnadmin</tt> program is not in your $PATH you
1108 should specify its absolute path with this switch.
1109 <tt>svnadmin</tt> is needed when the <tt>-s/--svnrepos</tt>
1110 output option is used</td>
1111 </tr>
1113 <tr>
1114 <td align="right"><tt>--co=PATH</tt></td>
1115 <td>If the <tt>co</tt> program (a part of RCS) is not in your
1116 $PATH you should specify its absolute path with this switch.
1117 (<tt>co</tt> is needed if the <tt>--use-rcs</tt> extraction
1118 option is used.)</td>
1119 </tr>
1121 <tr>
1122 <td align="right"><tt>--cvs=PATH</tt></td>
1123 <td>If the cvs program is not in your $PATH you should
1124 specify its absolute path with this switch. (<tt>cvs</tt> is
1125 needed if the <tt>--use-cvs</tt> extraction option is
1126 used.)</td>
1127 </tr>
1129 <tr>
1130 <th colspan="2">
1131 Partial conversions
1132 </th>
1133 </tr>
1135 <tr>
1136 <td align="right"><tt>-p PASS</tt><br/><tt>--pass PASS</tt></td>
1137 <td>Execute only pass PASS of the conversion. PASS can be
1138 specified by name or by number (see <tt>--help-passes</tt>)</td>
1139 </tr>
1141 <tr>
1142 <td align="right"><tt>-p [START]:[END]</tt><br/><tt>--passes [START]:[END]</tt></td>
1143 <td>Execute passes START through END of the conversion
1144 (inclusive). START and END can be specified by name or by number
1145 (see <tt>--help-passes</tt>). If START or END is missing, it
1146 defaults to the first or last pass, respectively.</td>
1147 </tr>
1149 <tr>
1150 <th colspan="2">
1151 Information options
1152 </th>
1153 </tr>
1155 <tr>
1156 <td align="right"><tt>--version</tt></td>
1157 <td>Print the version number.</td>
1158 </tr>
1160 <tr>
1161 <td align="right"><tt>--help</tt>, <tt>-h</tt></td>
1162 <td>Print the usage message and exit with success.</td>
1163 </tr>
1165 <tr>
1166 <td align="right"><tt>--help-passes</tt></td>
1167 <td>Print the numbers and names of the conversion passes and exit
1168 with success.</td>
1169 </tr>
1171 <tr>
1172 <td align="right"><tt>--man</tt></td>
1173 <td>Write the manpage for this program to standard output.</td>
1174 </tr>
1176 <tr>
1177 <td align="right"><tt>--verbose</tt>, <tt>-v</tt></td>
1178 <td>Tell cvs2svn to print lots of information about what
1179 it's doing to STDOUT. This option can be specified twice to get
1180 debug-level output.</td>
1181 </tr>
1183 <tr>
1184 <td align="right"><tt>--quiet</tt>, <tt>-q</tt></td>
1185 <td>Tell cvs2svn to operate in quiet mode, printing little more
1186 than pass starts and stops to STDOUT. This option may be
1187 specified twice to suppress all non-error output.</td>
1188 </tr>
1190 <tr>
1191 <td align="right"><tt>--write-symbol-info=PATH</tt></td>
1192 <td>Write symbol statistics and information about how symbols were
1193 converted to PATH during CollateSymbolsPass. See
1194 <tt>--symbol-hints</tt> for a description of the output
1195 format.</td>
1196 </tr>
1198 <tr>
1199 <td align="right"><tt>--skip-cleanup</tt></td>
1200 <td>Prevent the deletion of the temporary files that cvs2svn
1201 creates in the process of conversion.</td>
1202 </tr>
1204 <tr>
1205 <td align="right"><tt>--profile</tt></td>
1206 <td>Dump Python <a href=""
1207 >cProfile</a> profiling data to the file <tt>cvs2svn.cProfile</tt>.
1208 In Python 2.4 and earlier, if cProfile is not installed, it will
1209 instead dump <a href=""
1210 >Hotshot</a> profiling data to the file <tt>cvs2svn.hotshot</tt>.</td>
1211 </tr>
1213 </table>
1215 <hr />
1217 <h1><a name="examples">A Few Examples</a></h1>
1219 <p>To create a new Subversion repository by converting an existing CVS
1220 repository, run the script like this:</p>
1222 <pre>
1223 $ cvs2svn --svnrepos NEW_SVNREPOS CVSREPOS
1224 </pre>
1226 <p>To create a new Subversion repository containing only trunk commits,
1227 and omitting all branches and tags from the CVS repository, do</p>
1229 <pre>
1230 $ cvs2svn --trunk-only --svnrepos NEW_SVNREPOS CVSREPOS
1231 </pre>
1233 <p>To create a Subversion dumpfile (suitable for 'svnadmin load') from
1234 a CVS repository, run it like this:</p>
1236 <pre>
1237 $ cvs2svn --dumpfile DUMPFILE CVSREPOS
1238 </pre>
1240 <p>To use an options file to define all of the conversion parameters,
1241 specify <tt>--options</tt>:</p>
1243 <pre>
1244 $ cvs2svn --options OPTIONSFILE
1245 </pre>
1247 <p>As it works, cvs2svn will create many temporary files in a
1248 temporary directory called "cvs2svn-tmp" (or the directory specified
1249 with <tt>--tmpdir</tt>). This is normal. If the entire conversion is
1250 successful, however, those tempfiles will be automatically removed.
1251 If the conversion is not successful, or if you specify the
1252 '--skip-cleanup' option, cvs2svn will leave the temporary files behind
1253 for possible debugging.</p>
1255 </div>
1256 </body>
1257 </html>