www/cvs2svn.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <style type="text/css"> /* <![CDATA[ */
   6   @import "tigris-branding/css/tigris.css";
   7   @import "tigris-branding/css/inst.css";
   8   /* ]]> */</style>
   9 <link rel="stylesheet" type="text/css" media="print"
  10   href="tigris-branding/css/print.css"/>
  11 <script type="text/javascript" src="tigris-branding/scripts/tigris.js"></script>
  12 <title>cvs2svn Documentation</title>
  13 </head>
  14
  15 <body id="bodycol">
  16 <div class="app">
  17
  18 <h1>cvs2svn Documentation</h1>
  19
  20 <h2>Index</h2>
  21
  22 <ul>
  23
  24   <li><a href="#intro">Introduction</a></li>
  25
  26   <li><a href="#reqs">Requirements</a></li>
  27
  28   <li><a href="#install">Installation</a></li>
  29
  30   <li><a href="#convert">Deciding how much to convert</a></li>
  31
  32   <li><a href="#prep">Prepping your repository</a></li>
  33
  34   <li><a href="#cmd-vs-options">Command line vs. options file</a></li>
  35
  36   <li><a href="#symbols">Symbol handling</a></li>
  37
  38   <li><a href="#cmd-ref">Command line reference</a></li>
  39
  40   <li><a href="#examples">A few examples</a></li>
  41
  42 </ul>
  43
  44 <hr />
  45
  46 <h1><a name="intro">Introduction</a></h1>
  47
  48 <p>cvs2svn is a program that can be used to migrate a CVS repository
  49 to <a href="http://subversion.tigris.org/">Subversion</a> (otherwise
  50 known as "SVN") or <a href="http://git.or.cz/">git</a>.
  51 Documentation:</p>
  52
  53 <ul>
  54
  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>
  58
  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>
  62
  63   <li><a href="cvs2git.html">cvs2git.html</a> describes how to use
  64   cvs2svn to convert your CVS repository to git.</li>
  65
  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>
  74
  75 </ul>
  76
  77
  78 <hr />
  79
  80 <h1><a name="reqs">Requirements</a></h1>
  81
  82 <p>cvs2svn requires the following:</p>
  83
  84 <ul>
  85
  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="http://www.python.org/">http://www.python.org/</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="http://www.cs.purdue.edu/homes/trinkle/RCS/"
 103             >http://www.cs.purdue.edu/homes/trinkle/RCS/</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="http://ccvs.cvshome.org/">http://ccvs.cvshome.org/</a>.
 110     See the <a href="#use-cvs"><tt>--use-cvs</tt> flag</a> for more
 111     details.
 112   </li>
 113
 114 </ul>
 115
 116 <h2>CVSNT repositories</h2>
 117
 118 <p>cvs2svn does not support conversion of <a
 119 href="http://www.cvsnt.org/">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>
 124
 125 <hr />
 126
 127 <h1><a name="install">Installation</a></h1>
 128
 129 <ul>
 130   <li>As root, run 'make install'.</li>
 131
 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>
 135
 136   <li>If you want to create Unix-style manpages for the main programs,
 137     run 'make man'.</li>
 138
 139 </ul>
 140
 141 <hr />
 142
 143 <h1><a name="convert">Deciding how much to convert</a></h1>
 144
 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>
 148
 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>
 160
 161 <ul>
 162
 163   <li>Top-skim (Doesn't require cvs2svn!)</li>
 164
 165   <li>Trunk only</li>
 166
 167   <li>Pick and choose</li>
 168
 169   <li>Full conversion</li>
 170
 171   <li>Smorgasbord</li>
 172
 173   <li>One project at a time</li>
 174
 175 </ul>
 176
 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>
 181
 182
 183 <h2>Top-skimming</h2>
 184
 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>
 196
 197 <blockquote>
 198
 199   <p><b>Pros:</b> Quick, easy, convenient, results in a very compact and
 200   "neat" Subversion repository.</p>
 201
 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>
 205
 206 </blockquote>
 207
 208
 209 <h2>Trunk only</h2>
 210
 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>
 217
 218 <blockquote>
 219
 220   <p><b>Pros:</b>Saves disk space in your new Subversion repository.
 221   Attractive to neatniks.</p>
 222
 223   <p><b>Cons:</b> You've got no branches and no tags in your
 224   Subversion repository.</p>
 225
 226 </blockquote>
 227
 228
 229 <h2>Pick and choose</h2>
 230
 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>
 237
 238 <blockquote>
 239
 240   <p><b>Pros:</b>You only get what you want from your CVS repository.
 241   Saves a some space.</p>
 242
 243   <p><b>Cons:</b>If you forgot something, you'll have to go to your
 244   CVS repository.</p>
 245
 246 </blockquote>
 247
 248
 249 <h2>Full conversion</h2>
 250
 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>
 254
 255 <blockquote>
 256
 257   <p><b>Pros:</b> Converts every last byte of your CVS repository.</p>
 258
 259   <p><b>Cons:</b> Requires more disk space.</p>
 260
 261 </blockquote>
 262
 263
 264 <h2>Smorgasbord</h2>
 265
 266 <p>You can convert your repository (or repositories) piece by piece
 267 using a combination of the above .</p>
 268
 269 <blockquote>
 270
 271   <p><b>Pros:</b> You get exactly what you want.</p>
 272
 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>
 279
 280 </blockquote>
 281
 282
 283 <h2>One project at a time</h2>
 284
 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>
 293
 294 <blockquote>
 295
 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>
 299
 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>
 307
 308 </blockquote>
 309
 310 <hr />
 311
 312 <h1><a name="prep">Prepping your repository</a></h1>
 313
 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>
 321
 322 <h2>End-of-line translation</h2>
 323
 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>
 328
 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>
 338
 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>
 347
 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>
 355
 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>
 361
 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>
 367
 368 </ul>
 369
 370 <h2>Converting part of repository</h2>
 371
 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>
 375
 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>
 381
 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>
 386
 387 <hr />
 388
 389 <h1><a name="cmd-vs-options">Command line vs. options file</a></h1>
 390
 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>
 396
 397 <h2><a name="cmd-line-method">Command line method</a></h2>
 398
 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>
 406
 407
 408 <h2><a name="options-file-method">Options file method</a></h2>
 409
 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>
 415
 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>
 423
 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>
 428
 429 <p>To start a conversion using an options file, invoke cvs2svn like
 430 this:</p>
 431
 432 <pre>
 433    $ cvs2svn --options=OPTIONSFILE
 434 </pre>
 435
 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>
 441
 442 <hr />
 443
 444
 445 <h1><a name="symbols">Symbol handling</a></h1>
 446
 447 <p>cvs2svn converts CVS tags and branches into Subversion tags and
 448 branches.  This section discusses issues related to symbol
 449 handling.</p>
 450
 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>
 461
 462
 463 <h2><a name="symbol-layout">Placement of trunk, branches, and tags
 464 directories</a></h2>
 465
 466 <p>cvs2svn converts CVS branches and tags into Subversion branches and
 467 tags following the <a
 468 href="http://svnbook.red-bean.com/en/1.2/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">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="http://svnbook.red-bean.com/en/1.4/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">repository
 477 layout strategies</a> are discussed in the <a
 478 href="http://svnbook.red-bean.com/">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>
 482
 483
 484 <h2><a name="symbol-exclusion">Excluding tags and branches</a></h2>
 485
 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>
 495
 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>
 501
 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>
 507
 508 <pre>
 509    ERROR: The branch 'BRANCH' cannot be excluded because the following symbols depend on it:
 510        'TAG'
 511        'SUBBRANCH'
 512 </pre>
 513
 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>
 517
 518 <h3>Excluding vendor branches</h3>
 519
 520 <p>There is one more special case related to branch handling.  A <a
 521 href="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)">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>1.1.1.1</tt>,
 525 <tt>1.1.1.2</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>
 533
 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>
 548
 549
 550 <h2><a name="symbol-inconsistencies">Tag/branch inconsistencies</a></h2>
 551
 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>
 559
 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>
 567
 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>
 575
 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>
 584
 585 <p>You have to tell cvs2svn how to fix the inconsistencies then
 586 restart the conversion at <tt>CollateSymbolsPass</tt>.</p>
 587
 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>
 591
 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>
 600
 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>
 603
 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>
 611
 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>
 623
 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>
 632
 633 <hr />
 634
 635
 636 <h1><a name="cmd-ref">Command line reference</a></h1>
 637
 638 <table border="1" cellpadding="10" cellspacing="3" width="80%">
 639
 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>
 648
 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>
 661
 662   <tr>
 663     <th colspan="2">
 664       Configuration via options file
 665     </th>
 666   </tr>
 667
 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>
 674
 675   <tr>
 676     <th colspan="2">
 677       Output options
 678     </th>
 679   </tr>
 680
 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>
 688
 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>
 699
 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>
 705
 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>
 711
 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>
 718
 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>
 726
 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>
 733
 734   <tr>
 735     <th colspan="2">
 736       Conversion options
 737     </th>
 738   </tr>
 739
 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>
 746
 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>
 752
 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>
 758
 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>
 764
 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>
 771
 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>
 778
 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="http://docs.python.org/lib/standard-encodings.html">standard
 789       Python encodings</a>.</td>
 790   </tr>
 791
 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>
 804
 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>
 811
 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>
 818
 819   <tr>
 820     <th colspan="2">
 821       Symbol handling
 822     </th>
 823   </tr>
 824
 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>
 834
 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>
 839
 840 <pre>
 841 cvs2svn --symbol-transform='([0-9])-(.*):release-\1.\2' -s SVN RCS
 842 </pre>
 843
 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>
 847
 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>
 855
 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>
 861
 862 <pre>
 863 project-id symbol conversion svn-path parent-lod-name
 864 </pre>
 865
 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>
 883
 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>
 890
 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>
 896
 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>
 900
 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>
 905
 906         <li>"<tt>branch</tt>": Treat every ambiguous symbol as a
 907           branch.</li>
 908
 909         <li>"<tt>tag</tt>": Treat every ambiguous symbols as a
 910           tag.</li>
 911
 912       </ul>
 913     </td>
 914   </tr>
 915
 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>
 920
 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>
 926
 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>
 932
 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>
 940
 941   <tr>
 942     <th colspan="2">
 943       Subversion properties
 944     </th>
 945   </tr>
 946
 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>
 952
 953   <tr>
 954     <td align="right"><tt>--auto-props=FILE</tt></td>
 955     <td>
 956
 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>
 966
 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>
 972
 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>
 978
 979     </td>
 980   </tr>
 981
 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>
 988
 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>
1000
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>
1009
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 Date Id Revision" if the file's svn:eol-style property
1014       is set (see the <tt>--default-eol</tt> option).  The
1015       <tt>--keywords-off</tt> switch prevents cvs2svn from setting
1016       <tt>svn:keywords</tt> for any file.  (The result for files
1017       that <em>do</em> contain keyword strings is somewhat
1018       unexpected: the keywords will be left with the expansions that
1019       they had when committed to CVS, which is usually the expansion
1020       for the <em>previous</em> revision.)</td>
1021   </tr>
1022
1023   <tr>
1024     <td align="right"><tt>--keep-cvsignore</tt></td>
1025     <td>Include <tt>.cvsignore</tt> files in the output.  (Normally
1026       they are unneeded because cvs2svn sets the corresponding
1027       <tt>svn:ignore</tt> properties.)</td>
1028   </tr>
1029
1030   <tr>
1031     <td align="right"><tt>--cvs-revnums</tt></td>
1032     <td>Record CVS revision numbers as file properties in the
1033       Subversion repository.  (Note that unless it is removed
1034       explicitly, the last CVS revision number will remain associated
1035       with the file even after the file is changed within
1036       Subversion.)</td>
1037   </tr>
1038
1039   <tr>
1040     <th colspan="2">
1041       Extraction options
1042     </th>
1043   </tr>
1044
1045   <tr>
1046     <td align="right">
1047       <a name="use-internal-co"><tt>--use-internal-co</tt></a>
1048     </td>
1049     <td>Use internal code to extract the contents of CVS revisions.
1050       This is the default extraction option.  This is up to 50% faster
1051       than <tt>--use-rcs</tt>, but needs a lot of disk space: roughly
1052       the size of your CVS repository plus the peak size of a complete
1053       checkout of the repository with all branches that existed and
1054       still had commits pending at a given time.  If this option is
1055       used, the <tt>$Log$</tt> keyword is not handled.
1056     </td>
1057   </tr>
1058
1059   <tr>
1060     <td align="right"><a name="use-rcs"><tt>--use-rcs</tt></a></td>
1061     <td>Use RCS's <b><tt>co</tt></b> command to extract the contents
1062       of CVS revisions.  RCS is much faster than CVS, but in certain
1063       rare cases it has problems with data that CVS can handle.
1064       Specifically:
1065       <ul>
1066         <li>RCS can't handle spaces in author names:<br/>
1067           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4"
1068                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4</a>
1069         </li>
1070         <li>"Unterminated keyword" misread by RCS:<br/>
1071           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11"
1072                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11</a>
1073         </li>
1074         <li>RCS handles the "$Log$" keyword differently from CVS:<br/>
1075           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29"
1076                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29</a>
1077         </li>
1078       </ul>
1079       If you are having trouble in <tt>OutputPass</tt> of a
1080       conversion when using the <tt>--use-rcs</tt> option, the first
1081       thing to try is using the <tt>--use-cvs</tt> option instead.
1082     </td>
1083   </tr>
1084
1085   <tr>
1086     <td align="right"><a name="use-cvs"><tt>--use-cvs</tt></a></td>
1087     <td>If RCS <b><tt>co</tt></b> is having trouble extracting CVS
1088       revisions, you may need to pass this flag, which causes cvs2svn
1089       to use CVS instead of RCS to read the repository.  See <a
1090       href="#use-rcs"><tt>--use-rcs</tt></a> for more information.
1091     </td>
1092   </tr>
1093
1094   <tr>
1095     <th colspan="2">
1096       Environment options
1097     </th>
1098   </tr>
1099
1100   <tr>
1101     <td align="right"><tt>--tmpdir=PATH</tt></td>
1102     <td>Use the directory PATH for all of cvs2svn's temporary data
1103       (which can be a <i>lot</i> of data).  The default value is
1104       <tt>cvs2svn-tmp</tt> in the current working directory.</td>
1105   </tr>
1106
1107   <tr>
1108     <td align="right"><tt>--svnadmin=PATH</tt></td>
1109     <td>If the <tt>svnadmin</tt> program is not in your $PATH you
1110       should specify its absolute path with this switch.
1111       <tt>svnadmin</tt> is needed when the <tt>-s/--svnrepos</tt>
1112       output option is used</td>
1113   </tr>
1114
1115   <tr>
1116     <td align="right"><tt>--co=PATH</tt></td>
1117     <td>If the <tt>co</tt> program (a part of RCS) is not in your
1118       $PATH you should specify its absolute path with this switch.
1119       (<tt>co</tt> is needed if the <tt>--use-rcs</tt> extraction
1120       option is used.)</td>
1121   </tr>
1122
1123   <tr>
1124     <td align="right"><tt>--cvs=PATH</tt></td>
1125     <td>If the cvs program is not in your $PATH you should
1126       specify its absolute path with this switch.  (<tt>cvs</tt> is
1127       needed if the <tt>--use-cvs</tt> extraction option is
1128       used.)</td>
1129   </tr>
1130
1131   <tr>
1132     <th colspan="2">
1133       Partial conversions
1134     </th>
1135   </tr>
1136
1137   <tr>
1138     <td align="right"><tt>-p PASS</tt><br/><tt>--pass PASS</tt></td>
1139     <td>Execute only pass PASS of the conversion.  PASS can be
1140     specified by name or by number (see <tt>--help-passes</tt>)</td>
1141   </tr>
1142
1143   <tr>
1144     <td align="right"><tt>-p [START]:[END]</tt><br/><tt>--passes [START]:[END]</tt></td>
1145     <td>Execute passes START through END of the conversion
1146     (inclusive).  START and END can be specified by name or by number
1147     (see <tt>--help-passes</tt>).  If START or END is missing, it
1148     defaults to the first or last pass, respectively.</td>
1149   </tr>
1150
1151   <tr>
1152     <th colspan="2">
1153       Information options
1154     </th>
1155   </tr>
1156
1157   <tr>
1158     <td align="right"><tt>--version</tt></td>
1159     <td>Print the version number.</td>
1160   </tr>
1161
1162   <tr>
1163     <td align="right"><tt>--help</tt>, <tt>-h</tt></td>
1164     <td>Print the usage message and exit with success.</td>
1165   </tr>
1166
1167   <tr>
1168     <td align="right"><tt>--help-passes</tt></td>
1169     <td>Print the numbers and names of the conversion passes and exit
1170     with success.</td>
1171   </tr>
1172
1173   <tr>
1174     <td align="right"><tt>--man</tt></td>
1175     <td>Write the manpage for this program to standard output.</td>
1176   </tr>
1177
1178   <tr>
1179     <td align="right"><tt>--verbose</tt>, <tt>-v</tt></td>
1180     <td>Tell cvs2svn to print lots of information about what
1181       it's doing to STDOUT.  This option can be specified twice to get
1182       debug-level output.</td>
1183   </tr>
1184
1185   <tr>
1186     <td align="right"><tt>--quiet</tt>, <tt>-q</tt></td>
1187     <td>Tell cvs2svn to operate in quiet mode, printing little more
1188       than pass starts and stops to STDOUT.  This option may be
1189       specified twice to suppress all non-error output.</td>
1190   </tr>
1191
1192   <tr>
1193     <td align="right"><tt>--write-symbol-info=PATH</tt></td>
1194     <td>Write symbol statistics and information about how symbols were
1195       converted to PATH during CollateSymbolsPass.  See
1196       <tt>--symbol-hints</tt> for a description of the output
1197       format.</td>
1198   </tr>
1199
1200   <tr>
1201     <td align="right"><tt>--skip-cleanup</tt></td>
1202     <td>Prevent the deletion of the temporary files that cvs2svn
1203       creates in the process of conversion.</td>
1204   </tr>
1205
1206   <tr>
1207     <td align="right"><tt>--profile</tt></td>
1208     <td>Dump Python <a href="http://docs.python.org/library/profile.html"
1209         >cProfile</a> profiling data to the file <tt>cvs2svn.cProfile</tt>.
1210         In Python 2.4 and earlier, if cProfile is not installed, it will
1211         instead dump <a href="http://docs.python.org/library/hotshot.html"
1212         >Hotshot</a> profiling data to the file <tt>cvs2svn.hotshot</tt>.</td>
1213   </tr>
1214
1215 </table>
1216
1217 <hr />
1218
1219 <h1><a name="examples">A Few Examples</a></h1>
1220
1221 <p>To create a new Subversion repository by converting an existing CVS
1222 repository, run the script like this:</p>
1223
1224 <pre>
1225    $ cvs2svn --svnrepos NEW_SVNREPOS CVSREPOS
1226 </pre>
1227
1228 <p>To create a new Subversion repository containing only trunk commits,
1229 and omitting all branches and tags from the CVS repository, do</p>
1230
1231 <pre>
1232    $ cvs2svn --trunk-only --svnrepos NEW_SVNREPOS CVSREPOS
1233 </pre>
1234
1235 <p>To create a Subversion dumpfile (suitable for 'svnadmin load') from
1236 a CVS repository, run it like this:</p>
1237
1238 <pre>
1239    $ cvs2svn --dumpfile DUMPFILE CVSREPOS
1240 </pre>
1241
1242 <p>To use an options file to define all of the conversion parameters,
1243 specify <tt>--options</tt>:</p>
1244
1245 <pre>
1246    $ cvs2svn --options OPTIONSFILE
1247 </pre>
1248
1249 <p>As it works, cvs2svn will create many temporary files in a
1250 temporary directory called "cvs2svn-tmp" (or the directory specified
1251 with <tt>--tmpdir</tt>).  This is normal.  If the entire conversion is
1252 successful, however, those tempfiles will be automatically removed.
1253 If the conversion is not successful, or if you specify the
1254 '--skip-cleanup' option, cvs2svn will leave the temporary files behind
1255 for possible debugging.</p>
1256
1257 </div>
1258 </body>
1259 </html>