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 <p><strong>Note:</strong> If you want to customize your conversion
 443 using your own Python classes, these classes must be defined in a
 444 separate Python file then imported into the options file.
 445 See <a href="faq.html#options-code">the FAQ</a> for more details.</p>
 446
 447 <hr />
 448
 449
 450 <h1><a name="symbols">Symbol handling</a></h1>
 451
 452 <p>cvs2svn converts CVS tags and branches into Subversion tags and
 453 branches.  This section discusses issues related to symbol
 454 handling.</p>
 455
 456 <p><strong>HINT:</strong> If there are problems with symbol usage in
 457 your repository, they are usually reported during
 458 <tt>CollateSymbolsPass</tt> of the conversion, causing the conversion
 459 to be interrupted.  However, it is not necessary to restart the whole
 460 conversion to fix the problems.  Usually it is adequate to adjust the
 461 symbol-handling options then re-start cvs2svn starting at
 462 <tt>CollateSymbolsPass</tt>, by adding the option "<tt>-p
 463 CollateSymbolsPass:</tt>".  This trick can save a lot of time if you
 464 have a large repository, as it might take a few iterations before you
 465 find the best set of options to convert your repository.</p>
 466
 467
 468 <h2><a name="symbol-layout">Placement of trunk, branches, and tags
 469 directories</a></h2>
 470
 471 <p>cvs2svn converts CVS branches and tags into Subversion branches and
 472 tags following the <a
 473 href="http://svnbook.red-bean.com/en/1.2/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">standard
 474 Subversion convention</a>.  For single-project conversions, the
 475 default is to put the trunk, branches, and tags directories at the top
 476 level of the repository tree, though this behavior can be changed by
 477 using the <tt>--trunk</tt>, <tt>--branches</tt>, and <tt>--tags</tt>
 478 options.  For multiproject conversions, you must specify the location
 479 of each project's trunk, branches, and tags directory in the options
 480 file; <a
 481 href="http://svnbook.red-bean.com/en/1.4/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">repository
 482 layout strategies</a> are discussed in the <a
 483 href="http://svnbook.red-bean.com/">Subversion book</a>.  For even
 484 finer control over the conversion, you can use a
 485 <tt>--symbol-hints</tt> file to specify the SVN path to be used for
 486 each CVS tag and branch.</p>
 487
 488
 489 <h2><a name="symbol-exclusion">Excluding tags and branches</a></h2>
 490
 491 <p>Often a CVS repository contains tags and branches that will not be
 492 needed after the conversion to Subversion.  You can instruct cvs2svn
 493 to exclude such symbols from the conversion, in which case they will
 494 not be present in the resulting Subversion repository.  Please be
 495 careful when doing this; excluding symbols causes information that was
 496 present in CVS to be omitted in Subversion, thereby discarding
 497 potentially useful historical information.  Also be aware that if you
 498 exclude a branch, then all CVS revisions that were committed to that
 499 branch will also be excluded.</p>
 500
 501 <p>To exclude a tag or branch, use the option
 502 <tt>--exclude=SYMBOL</tt>.  You can also exclude a whole group of
 503 symbols matching a specified regular expression; for example,
 504 <tt>--exclude='RELEASE_0_.*'</tt>.  (The regular expression has to
 505 match the <em>whole</em> symbol name for the rule to apply.)</p>
 506
 507 <p>However, please note the following restriction.  If a branch has a
 508 subbranch or a tag on it, then the branch cannot be excluded unless
 509 the dependent symbol is also excluded.  cvs2svn checks for this
 510 situation; if it occurs then <tt>CollateSymbolsPass</tt> outputs an
 511 error message like the following:</p>
 512
 513 <pre>
 514    ERROR: The branch 'BRANCH' cannot be excluded because the following symbols depend on it:
 515        'TAG'
 516        'SUBBRANCH'
 517 </pre>
 518
 519 <p>In such a case you can either exclude the dependent symbol(s) (in
 520 this case by using <tt>--exclude=TAG --exclude=SUBBRANCH</tt>) or
 521 <em>not</em> exclude 'BRANCH'.</p>
 522
 523 <h3>Excluding vendor branches</h3>
 524
 525 <p>There is one more special case related to branch handling.  A <a
 526 href="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)">vendor
 527 branch</a> is a CVS branch that is used to track source code received
 528 from an outside source.  A vendor branch typically has CVS branch
 529 number <tt>1.1.1</tt> and revision numbers <tt>1.1.1.1</tt>,
 530 <tt>1.1.1.2</tt>, etc.  Vendor branches are created automatically
 531 whenever the <tt>cvs import</tt> command is used.  Vendor branches
 532 have the strange property that, under certain circumstances, a file
 533 that appears on a vendor branch also implicitly exists on trunk.
 534 cvs2svn knows all about vendor branches and does its best to ensure
 535 that a file that appears on a vendor branch is also copied to trunk,
 536 to give Subversion behavior that is as close as possible to the CVS
 537 behavior.</p>
 538
 539 <p>However, often vendor branches exist for reasons unrelated to
 540 tracking outside sources.  Indeed, some CVS documentation recommends
 541 using the <tt>cvs import</tt> command to import your own code into
 542 your CVS repository (which is arguably a misuse of the <tt>cvs
 543 import</tt> command).  Vendor branches created by this practice are
 544 useless and would only serve to clutter up your Subversion repository.
 545 Therefore, cvs2svn allows vendor branches to be excluded, in which
 546 case the vendor branch revisions are grafted onto the history of
 547 trunk.  This is allowed <em>even if</em> other branches or tags appear
 548 to sprout from the vendor branch, in which case the dependent tags are
 549 grafted to trunk as well.  Such branches can be recognized in the
 550 <tt>--write-symbol-info</tt> by looking for a symbol that is a "pure
 551 import" in the same number of files that it appears as a branch.  It
 552 is typically advantageous to exclude such branches.</p>
 553
 554
 555 <h2><a name="symbol-inconsistencies">Tag/branch inconsistencies</a></h2>
 556
 557 <p>In CVS, the same symbol can appear as a tag in some files (e.g.,
 558 <tt>cvs tag SYMBOL file1.txt</tt>) and a branch in others (e.g.,
 559 <tt>cvs tag -b SYMBOL file2.txt</tt>).  Subversion takes a more global
 560 view of your repository, and therefore works better when each symbol
 561 is used in a self-consistent way--either always as a branch or always
 562 as a tag.  cvs2svn provides features to help you resolve these
 563 ambiguities.</p>
 564
 565 <p>If your repository contains inconsistently-used symbols, then
 566 <tt>CollateSymbolsPass</tt>, by default, uses heuristics to decide
 567 which symbols to convert as branches and which as tags.  Often this
 568 behavior will be adequate, and you don't have to do anything special.
 569 You can use the <tt>--write-symbol-info=<i>filename</i></tt> option to
 570 cause cvs2svn to list all of the symbols in your repository and how it
 571 chose to convert them to <tt><i>filename</i></tt>.</p>
 572
 573 <p>However, if you want to take finer control over how symbols are
 574 converted, you can do so.  The first step is probably to change the
 575 default symbol handling style from <tt>heuristic</tt> (the default
 576 value) to <tt>strict</tt> using the option
 577 <tt>--symbol-default=strict</tt>.  With the <tt>strict</tt> setting,
 578 cvs2svn prints error messages and aborts the conversion if there are
 579 any ambiguous symbols.  The error messages look like this:</p>
 580
 581 <pre>
 582    ERROR: It is not clear how the following symbols should be converted.
 583    Use --symbol-hints, --force-tag, --force-branch, --exclude, and/or
 584    --symbol-default to resolve the ambiguity.
 585        'SYMBOL1' is a tag in 1 files, a branch in 2 files and has commits in 0 files
 586        'SYMBOL2' is a tag in 2 files, a branch in 1 files and has commits in 0 files
 587        'SYMBOL3' is a tag in 1 files, a branch in 2 files and has commits in 1 files
 588 </pre>
 589
 590 <p>You have to tell cvs2svn how to fix the inconsistencies then
 591 restart the conversion at <tt>CollateSymbolsPass</tt>.</p>
 592
 593 <p>There are three ways to deal with an inconsistent symbol: treat it
 594 as a tag, treat it as a branch, or exclude it from the conversion
 595 altogether.</p>
 596
 597 <p>In the example above, the symbol 'SYMBOL1' was used as a branch in
 598 two files but used as a tag in only one file.  Therefore, it might
 599 make sense to convert it as a branch, by using the option
 600 <tt>--force-branch=SYMBOL1</tt>.  However, no revisions were committed
 601 on this branch, so it would also be possible to convert it as a tag,
 602 by using the option <tt>--force-tag=SYMBOL1</tt>.  If the symbol is
 603 not needed at all, it can be excluded by using
 604 <tt>--exclude=SYMBOL1</tt>.</p>
 605
 606 <p>Similarly, 'SYMBOL2' was used more often as a tag, but can still be
 607 converted as a branch or a tag, or excluded.</p>
 608
 609 <p><tt>SYMBOL3</tt>, on the other hand, was sometimes used as a
 610 branch, and at least one revision was committed on the branch.  It can
 611 be converted as a branch, using <tt>--force-branch=SYMBOL3</tt>.  But
 612 it cannot be converted as a tag (because tags are not allowed to have
 613 revisions on them).  If it is excluded, using
 614 <tt>--exclude=SYMBOL3</tt>, then both the branch and the revisions on
 615 the branch will be left out of the Subversion repository.</p>
 616
 617 <p>If you are not so picky about which symbols are converted as tags
 618 and which as branches, you can ask cvs2svn to decide by itself.  To do
 619 this, specify the <tt>--symbol-default=OPTION</tt>, where
 620 <tt>OPTION</tt> can be either "<tt>heuristic</tt>" (the default;
 621 decide how to treat each ambiguous symbol based on whether it was used
 622 more often as a branch or as a tag in CVS), "<tt>branch</tt>" (treat
 623 every ambiguous symbol as a branch), or "<tt>tag</tt>" (treat every
 624 ambiguous symbol as a tag).  You can use the <tt>--force-branch</tt>
 625 and <tt>--force-tag</tt> options to specify the treatment of
 626 particular symbols, in combination with <tt>--symbol-default</tt> to
 627 specify the default to be used for other ambiguous symbols.</p>
 628
 629 <p>Finally, you can have cvs2svn write a text file showing how each
 630 symbol was converted by using the <tt>--write-symbol-info</tt> option.
 631 If you disagree with any of cvs2svn's choices, you can make a copy of
 632 this file, edit it, then pass it to cvs2svn by using the
 633 <tt>--symbol-hints</tt> option.  In this manner you can influence how
 634 each symbol is converted and also the parent line of development of
 635 each symbol (the line of development from which the symbol
 636 sprouts).</p>
 637
 638 <hr />
 639
 640
 641 <h1><a name="cmd-ref">Command line reference</a></h1>
 642
 643 <table border="1" cellpadding="10" cellspacing="3" width="80%">
 644
 645   <tr>
 646     <td colspan="2">
 647       <strong>USAGE:</strong><br/>
 648       <tt>cvs2svn [OPTIONS]... [-s SVN-REPOS-PATH|--dumpfile=PATH|--dry-run]
 649       CVS-REPOS-PATH</tt><br/>
 650       <tt>cvs2svn [OPTIONS]... --options=PATH</tt><br/>
 651     </td>
 652   </tr>
 653
 654   <tr>
 655     <td align="right"><tt>CVS-REPOS-PATH</tt></td>
 656     <td>The filesystem path of the part of the CVS repository that you
 657       want to convert.  It is not possible to convert a CVS repository
 658       to which you only have remote access; see <a
 659       href="faq.html#repoaccess">the FAQ</a> for details.  This
 660       doesn't have to be the top level directory of a CVS repository;
 661       it can point at a project within a repository, in which case
 662       only that project will be converted.  This path or one of its
 663       parent directories has to contain a subdirectory called CVSROOT
 664       (though the CVSROOT directory can be empty).</td>
 665   </tr>
 666
 667   <tr>
 668     <th colspan="2">
 669       Configuration via options file
 670     </th>
 671   </tr>
 672
 673   <tr>
 674     <td align="right"><tt>--options=PATH</tt></td>
 675     <td>Read the conversion options from the specified file.  See
 676       section <a href="#options-file-method">options file method</a>
 677       for more information.</td>
 678   </tr>
 679
 680   <tr>
 681     <th colspan="2">
 682       Output options
 683     </th>
 684   </tr>
 685
 686   <tr>
 687     <td align="right"><tt>-s PATH</tt><br/><tt>--svnrepos PATH</tt></td>
 688     <td>Write the output of the conversion into a Subversion
 689       repository located at PATH.  This option causes a new Subversion
 690       repository to be created at PATH unless the
 691       <tt>--existing-svnrepos</tt> option is also used.</td>
 692   </tr>
 693
 694   <tr>
 695     <td align="right"><tt>--existing-svnrepos</tt></td>
 696     <td>Load the converted CVS repository into an existing Subversion
 697       repository, instead of creating a new repository.  (This option
 698       should be used in combination with
 699       <tt>-s</tt>/<tt>--svnrepos</tt>.)  The repository must either be
 700       empty or contain no paths that overlap with those that will
 701       result from the conversion.  Please note that you need write
 702       permission for the repository files.</td>
 703   </tr>
 704
 705   <tr>
 706     <td align="right"><tt>--fs-type=TYPE</tt></td>
 707     <td>Pass the <tt>--fs-type=TYPE</tt> option to "svnadmin
 708       create" if creating a new Subversion repository.</td>
 709   </tr>
 710
 711   <tr>
 712     <td align="right"><tt>--bdb-txn-nosync</tt></td>
 713     <td>Pass the <tt>--bdb-txn-nosync</tt> switch to "svnadmin
 714       create" if creating a new Subversion repository.</td>
 715   </tr>
 716
 717   <tr>
 718     <td align="right"><tt>--create-option=OPT</tt></td>
 719     <td>Pass OPT to "svnadmin create" if creating a new Subversion
 720       repository (can be specified multiple times to pass multiple
 721       options).</td>
 722   </tr>
 723
 724   <tr>
 725     <td align="right"><tt>--dumpfile=PATH</tt></td>
 726     <td>Output the converted CVS repository into a Subversion dumpfile
 727       instead of a Subversion repository (useful for importing a CVS
 728       repository into an existing Subversion repository).  PATH is the
 729       filename in which to store the dumpfile.</td>
 730   </tr>
 731
 732   <tr>
 733     <td align="right"><tt>--dry-run</tt></td>
 734     <td>Do not create a repository or a dumpfile; just print the details
 735       of what cvs2svn would do if it were really converting your
 736       repository.</td>
 737   </tr>
 738
 739   <tr>
 740     <th colspan="2">
 741       Conversion options
 742     </th>
 743   </tr>
 744
 745   <tr>
 746     <td align="right"><tt>--trunk-only</tt></td>
 747     <td>Convert only the main line of development from the CVS
 748       repository (commonly referred to in Subversion parlance as
 749       "trunk"), ignoring all tags and branches.</td>
 750   </tr>
 751
 752   <tr>
 753     <td align="right"><tt>--trunk=PATH</tt></td>
 754     <td>The top-level path to use for trunk in the Subversion
 755       repository.  The default value is "trunk".</td>
 756   </tr>
 757
 758   <tr>
 759     <td align="right"><tt>--branches=PATH</tt></td>
 760     <td>The top-level path to use for branches in the Subversion
 761       repository.  The default value is "branches".</td>
 762   </tr>
 763
 764   <tr>
 765     <td align="right"><tt>--tags=PATH</tt></td>
 766     <td>The top-level path to use for tags in the Subversion
 767       repository.  The default value is "tags".</td>
 768   </tr>
 769
 770   <tr>
 771     <td align="right"><tt>--include-empty-directories</tt></td>
 772     <td>Treat empty subdirectories within the CVS repository as actual
 773       directories, creating them when the parent directory is created
 774       and removing them if and when the parent directory is pruned.</td>
 775   </tr>
 776
 777   <tr>
 778     <td align="right"><tt>--no-prune</tt></td>
 779     <td>When all files are deleted from a directory in the Subversion
 780       repository, don't delete the empty directory (the default is to
 781       delete any empty directories.</td>
 782   </tr>
 783
 784   <tr>
 785     <td align="right"><tt>--encoding=ENC</tt></td>
 786     <td>Use ENC as the encoding for filenames, log messages, and
 787       author names in the CVS repos.  (By using an <tt>--options</tt>
 788       file, it is possible to specify one set of encodings to use for
 789       filenames and a second set for log messages and author names.)
 790       This option may be specified multiple times, in which case the
 791       encodings are tried in order until one succeeds.  Default:
 792       ascii.  Other possible values include the <a
 793       href="http://docs.python.org/lib/standard-encodings.html">standard
 794       Python encodings</a>.</td>
 795   </tr>
 796
 797   <tr>
 798     <td align="right"><tt>--fallback-encoding=ENC</tt></td>
 799     <td>If none of the encodings specified with <tt>--encoding</tt>
 800       succeed in decoding an author name or log message, then fall
 801       back to using ENC in lossy 'replace' mode.  Use of this option
 802       may cause information to be lost, but at least it allows the
 803       conversion to run to completion.  This option only affects the
 804       encoding of log messages and author names; there is no fallback
 805       encoding for filenames.  (By using an <tt>--options</tt> file,
 806       it is possible to specify a fallback encoding for filenames.)
 807       Default: disabled.</td>
 808   </tr>
 809
 810   <tr>
 811     <td align="right"><tt>--no-cross-branch-commits</tt></td>
 812     <td>Prevent the creation of SVN commits that affect multiple
 813       branches or trunk and a branch.  Instead, break such changesets
 814       into multiple commits, one per branch.</td>
 815   </tr>
 816
 817   <tr>
 818     <td align="right"><tt>--retain-conflicting-attic-files</tt></td>
 819     <td>If a file appears both inside an outside of the CVS attic,
 820       retain the attic version in an SVN subdirectory called `Attic'.
 821       (Normally this situation is treated as a fatal error.)</td>
 822   </tr>
 823
 824   <tr>
 825     <th colspan="2">
 826       Symbol handling
 827     </th>
 828   </tr>
 829
 830   <tr>
 831     <td align="right"><tt>--symbol-transform=PAT:SUB</tt></td>
 832     <td><p>Transform RCS/CVS symbol names before entering them into
 833       Subversion.  PAT is a Python regular expression pattern that is
 834       matched against the entire symbol name.  If it matches, the
 835       symbol is replaced with SUB, which is a replacement pattern
 836       using Python's reference syntax.  You may specify any number of
 837       these options; they will be applied in the order given on the
 838       command line.</p>
 839
 840       <p>This option can be useful if you're converting a repository in
 841       which the developer used directory-wide symbol names like 1_0, 1_1
 842       and 2_1 as a kludgy form of release tagging (the C-x v s command
 843       in Emacs VC mode encourages this practice).  A command like</p>
 844
 845 <pre>
 846 cvs2svn --symbol-transform='([0-9])-(.*):release-\1.\2' -s SVN RCS
 847 </pre>
 848
 849       <p>will transform a local CVS repository into a local SVN repository,
 850       performing the following sort of mappings of RCS symbolic names to
 851       SVN tags:</p>
 852
 853 <pre>
 854 1-0 &rarr; release-1.0
 855 1-1 &rarr; release-1.1
 856 2-0 &rarr; release-2.0
 857 </pre>
 858     </td>
 859   </tr>
 860
 861   <tr>
 862     <td align="right"><tt>--symbol-hints=PATH</tt></td>
 863     <td><p>Read symbol conversion hints from PATH.  The format of PATH is
 864       the same as the format output by <tt>--write-symbol-info</tt>,
 865       namely a text file with four whitespace-separated columns:</p>
 866
 867 <pre>
 868 project-id symbol conversion svn-path parent-lod-name
 869 </pre>
 870
 871       <p><i>project-id</i> is the numerical ID of the project to which
 872       the symbol belongs, counting from 0.  <i>project-id</i> can be
 873       set to '.' if project-specificity is not needed.
 874       <i>symbol-name</i> is the name of the symbol being specified.
 875       <i>conversion</i> specifies how the symbol should be converted,
 876       and can be one of the values 'branch', 'tag', or 'exclude'.  If
 877       <i>conversion</i> is '.', then this rule does not affect how the
 878       symbol is converted.  <i>svn-path</i> is the name of the SVN
 879       path to which this line of development should be written.  If
 880       <i>svn-path</i> is omitted or '.', then this rule does not
 881       affect the SVN path of this symbol.  <i>parent-lod-name</i> is
 882       the name of the symbol from which this symbol should sprout, or
 883       '.trunk.' if the symbol should sprout from trunk.  If
 884       <i>parent-lod-name</i> is omitted or '.', then this rule does
 885       not affect the preferred parent of this symbol.  The file may
 886       contain blank lines or comment lines (lines whose first
 887       non-whitespace character is '#').</p>
 888
 889       <p>The simplest way to use this option is to run the conversion
 890       through CollateSymbolsPass with <tt>--write-symbol-info</tt>
 891       option, copy the symbol info and edit it to create a hints file,
 892       then re-start the conversion at <tt>CollateSymbolsPass</tt> with
 893       this option enabled.</p></td>
 894   </tr>
 895
 896   <tr>
 897     <td align="right"><tt>--symbol-default=OPT</tt></td>
 898     <td>Specify how to convert ambiguous symbols (i.e., those that
 899       appear in the CVS archive as both branches and tags).
 900       <tt>OPT</tt> is one of the following:<ul>
 901
 902         <li>"<tt>heuristic</tt>": Decide how to treat each ambiguous
 903           symbol based on whether it was used more often as a branch
 904           or tag in CVS.  (This is the default behavior.)</li>
 905
 906         <li>"<tt>strict</tt>": No default; every ambiguous symbol has
 907           to be resolved manually using <tt>--symbol-hints</tt>,
 908           <tt>--force-branch</tt>, <tt>--force-tag</tt>, or
 909           <tt>--exclude</tt>.</li>
 910
 911         <li>"<tt>branch</tt>": Treat every ambiguous symbol as a
 912           branch.</li>
 913
 914         <li>"<tt>tag</tt>": Treat every ambiguous symbols as a
 915           tag.</li>
 916
 917       </ul>
 918     </td>
 919   </tr>
 920
 921   <tr>
 922     <td align="right"><tt>--force-branch=REGEXP</tt></td>
 923     <td>Force symbols whose names match REGEXP to be branches.</td>
 924   </tr>
 925
 926   <tr>
 927     <td align="right"><tt>--force-tag=REGEXP</tt></td>
 928     <td>Force symbols whose names match REGEXP to be tags.  This will
 929       cause an error if such a symbol has commits on it.</td>
 930   </tr>
 931
 932   <tr>
 933     <td align="right"><tt>--exclude=REGEXP</tt></td>
 934     <td>Exclude branches and tags whose names match REGEXP from
 935       the conversion.</td>
 936   </tr>
 937
 938   <tr>
 939     <td align="right"><tt>--keep-trivial-imports</tt></td>
 940     <td>Do not exclude branches that were only used for a single
 941       import.  (By default such branches are excluded because they
 942       are usually created by the inappropriate use of <tt>cvs
 943       import</tt>.)</td>
 944   </tr>
 945
 946   <tr>
 947     <th colspan="2">
 948       Subversion properties
 949     </th>
 950   </tr>
 951
 952   <tr>
 953     <td align="right"><tt>--username=NAME</tt></td>
 954     <td>Use NAME as the author for cvs2svn-synthesized commits (the
 955       default value is no author at all.</td>
 956   </tr>
 957
 958   <tr>
 959     <td align="right"><tt>--auto-props=FILE</tt></td>
 960     <td>
 961
 962       <p>Specify a file in the format of Subversion's config file,
 963         whose <tt>[auto-props]</tt> section can be used to set
 964         arbitrary properties on files in the Subversion repository
 965         based on their filenames.  (The <tt>[auto-props]</tt> section
 966         header must be present; other sections of the config file,
 967         including the <tt>enable-auto-props</tt> setting, are
 968         ignored.)  Filenames are matched to the filename patterns
 969         case-insensitively, consistent with Subversion's behavior.
 970         The auto-props file might have content like this:</p>
 971
 972 <pre>
 973 [auto-props]
 974 *.txt = svn:mime-type=text/plain;svn:eol-style=native
 975 *.doc = svn:mime-type=application/msword;!svn:eol-style
 976 </pre>
 977
 978       <p>Please note that cvs2svn allows properties to be explicitly
 979         <em>unset</em>: if cvs2svn sees a setting like
 980         <tt>!svn:eol-style</tt> (with a leading exclamation point), it
 981         forces the property to remain <em>unset</em>, even if later
 982         rules would otherwise set the property.</p>
 983
 984     </td>
 985   </tr>
 986
 987   <tr>
 988     <td align="right"><tt>--mime-types=FILE</tt></td>
 989     <td>Specify an apache-style mime.types file for setting
 990       <tt>svn:mime-type</tt> properties on files in the Subversion
 991       repository.</td>
 992   </tr>
 993
 994   <tr>
 995     <td align="right"><tt>--eol-from-mime-type</tt></td>
 996     <td>For files that don't have the <tt>kb</tt> expansion mode but
 997       have a known mime type, set the eol-style based on the mime
 998       type.  For such files, set the <tt>svn:eol-style</tt> property
 999       to "native" if the mime type begins with "text/", and leave it
1000       unset (i.e., no EOL translation) otherwise.  Files with unknown
1001       mime types are not affected by this option.  This option has no
1002       effect unless the <tt>--mime-types</tt> option is also
1003       specified.</td>
1004   </tr>
1005
1006   <tr>
1007     <td align="right"><tt>--default-eol=STYLE</tt></td>
1008     <td>Set <tt>svn:eol-style</tt> to STYLE for files that don't have
1009       the <tt>kb</tt> expansion mode and whose end-of-line translation
1010       mode hasn't been determined by one of the other options.  STYLE
1011       can be "<tt>binary</tt>" (default), "<tt>native</tt>",
1012       "<tt>CRLF</tt>", "<tt>LF</tt>", or "<tt>CR</tt>".</td>
1013   </tr>
1014
1015   <tr>
1016     <td align="right"><tt>--keywords-off</tt></td>
1017     <td>By default, cvs2svn sets <tt>svn:keywords</tt> on CVS files to
1018       "Author Date Id Revision" if the file's svn:eol-style property
1019       is set (see the <tt>--default-eol</tt> option).  The
1020       <tt>--keywords-off</tt> switch prevents cvs2svn from setting
1021       <tt>svn:keywords</tt> for any file.  (The result for files
1022       that <em>do</em> contain keyword strings is somewhat
1023       unexpected: the keywords will be left with the expansions that
1024       they had when committed to CVS, which is usually the expansion
1025       for the <em>previous</em> revision.)</td>
1026   </tr>
1027
1028   <tr>
1029     <td align="right"><tt>--keep-cvsignore</tt></td>
1030     <td>Include <tt>.cvsignore</tt> files in the output.  (Normally
1031       they are unneeded because cvs2svn sets the corresponding
1032       <tt>svn:ignore</tt> properties.)</td>
1033   </tr>
1034
1035   <tr>
1036     <td align="right"><tt>--cvs-revnums</tt></td>
1037     <td>Record CVS revision numbers as file properties in the
1038       Subversion repository.  (Note that unless it is removed
1039       explicitly, the last CVS revision number will remain associated
1040       with the file even after the file is changed within
1041       Subversion.)</td>
1042   </tr>
1043
1044   <tr>
1045     <th colspan="2">
1046       Extraction options
1047     </th>
1048   </tr>
1049
1050   <tr>
1051     <td align="right">
1052       <a name="use-internal-co"><tt>--use-internal-co</tt></a>
1053     </td>
1054     <td>Use internal code to extract the contents of CVS revisions.
1055       This is the default extraction option.  This is up to 50% faster
1056       than <tt>--use-rcs</tt>, but needs a lot of disk space: roughly
1057       the size of your CVS repository plus the peak size of a complete
1058       checkout of the repository with all branches that existed and
1059       still had commits pending at a given time.  If this option is
1060       used, the <tt>$Log$</tt> keyword is not handled.
1061     </td>
1062   </tr>
1063
1064   <tr>
1065     <td align="right"><a name="use-rcs"><tt>--use-rcs</tt></a></td>
1066     <td>Use RCS's <b><tt>co</tt></b> command to extract the contents
1067       of CVS revisions.  RCS is much faster than CVS, but in certain
1068       rare cases it has problems with data that CVS can handle.
1069       Specifically:
1070       <ul>
1071         <li>RCS can't handle spaces in author names:<br/>
1072           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4"
1073                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4</a>
1074         </li>
1075         <li>"Unterminated keyword" misread by RCS:<br/>
1076           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11"
1077                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11</a>
1078         </li>
1079         <li>RCS handles the "$Log$" keyword differently from CVS:<br/>
1080           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29"
1081                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29</a>
1082         </li>
1083       </ul>
1084       If you are having trouble in <tt>OutputPass</tt> of a
1085       conversion when using the <tt>--use-rcs</tt> option, the first
1086       thing to try is using the <tt>--use-cvs</tt> option instead.
1087     </td>
1088   </tr>
1089
1090   <tr>
1091     <td align="right"><a name="use-cvs"><tt>--use-cvs</tt></a></td>
1092     <td>If RCS <b><tt>co</tt></b> is having trouble extracting CVS
1093       revisions, you may need to pass this flag, which causes cvs2svn
1094       to use CVS instead of RCS to read the repository.  See <a
1095       href="#use-rcs"><tt>--use-rcs</tt></a> for more information.
1096     </td>
1097   </tr>
1098
1099   <tr>
1100     <th colspan="2">
1101       Environment options
1102     </th>
1103   </tr>
1104
1105   <tr>
1106     <td align="right"><tt>--tmpdir=PATH</tt></td>
1107     <td>Use the directory PATH for all of cvs2svn's temporary data
1108       (which can be a <i>lot</i> of data).  The default value is
1109       <tt>cvs2svn-tmp</tt> in the current working directory.</td>
1110   </tr>
1111
1112   <tr>
1113     <td align="right"><tt>--svnadmin=PATH</tt></td>
1114     <td>If the <tt>svnadmin</tt> program is not in your $PATH you
1115       should specify its absolute path with this switch.
1116       <tt>svnadmin</tt> is needed when the <tt>-s/--svnrepos</tt>
1117       output option is used</td>
1118   </tr>
1119
1120   <tr>
1121     <td align="right"><tt>--co=PATH</tt></td>
1122     <td>If the <tt>co</tt> program (a part of RCS) is not in your
1123       $PATH you should specify its absolute path with this switch.
1124       (<tt>co</tt> is needed if the <tt>--use-rcs</tt> extraction
1125       option is used.)</td>
1126   </tr>
1127
1128   <tr>
1129     <td align="right"><tt>--cvs=PATH</tt></td>
1130     <td>If the cvs program is not in your $PATH you should
1131       specify its absolute path with this switch.  (<tt>cvs</tt> is
1132       needed if the <tt>--use-cvs</tt> extraction option is
1133       used.)</td>
1134   </tr>
1135
1136   <tr>
1137     <th colspan="2">
1138       Partial conversions
1139     </th>
1140   </tr>
1141
1142   <tr>
1143     <td align="right"><tt>-p PASS</tt><br/><tt>--pass PASS</tt></td>
1144     <td>Execute only pass PASS of the conversion.  PASS can be
1145     specified by name or by number (see <tt>--help-passes</tt>)</td>
1146   </tr>
1147
1148   <tr>
1149     <td align="right"><tt>-p [START]:[END]</tt><br/><tt>--passes [START]:[END]</tt></td>
1150     <td>Execute passes START through END of the conversion
1151     (inclusive).  START and END can be specified by name or by number
1152     (see <tt>--help-passes</tt>).  If START or END is missing, it
1153     defaults to the first or last pass, respectively.</td>
1154   </tr>
1155
1156   <tr>
1157     <th colspan="2">
1158       Information options
1159     </th>
1160   </tr>
1161
1162   <tr>
1163     <td align="right"><tt>--version</tt></td>
1164     <td>Print the version number.</td>
1165   </tr>
1166
1167   <tr>
1168     <td align="right"><tt>--help</tt>, <tt>-h</tt></td>
1169     <td>Print the usage message and exit with success.</td>
1170   </tr>
1171
1172   <tr>
1173     <td align="right"><tt>--help-passes</tt></td>
1174     <td>Print the numbers and names of the conversion passes and exit
1175     with success.</td>
1176   </tr>
1177
1178   <tr>
1179     <td align="right"><tt>--man</tt></td>
1180     <td>Write the manpage for this program to standard output.</td>
1181   </tr>
1182
1183   <tr>
1184     <td align="right"><tt>--verbose</tt>, <tt>-v</tt></td>
1185     <td>Tell cvs2svn to print lots of information about what
1186       it's doing to STDOUT.  This option can be specified twice to get
1187       debug-level output.</td>
1188   </tr>
1189
1190   <tr>
1191     <td align="right"><tt>--quiet</tt>, <tt>-q</tt></td>
1192     <td>Tell cvs2svn to operate in quiet mode, printing little more
1193       than pass starts and stops to STDOUT.  This option may be
1194       specified twice to suppress all non-error output.</td>
1195   </tr>
1196
1197   <tr>
1198     <td align="right"><tt>--write-symbol-info=PATH</tt></td>
1199     <td>Write symbol statistics and information about how symbols were
1200       converted to PATH during CollateSymbolsPass.  See
1201       <tt>--symbol-hints</tt> for a description of the output
1202       format.</td>
1203   </tr>
1204
1205   <tr>
1206     <td align="right"><tt>--skip-cleanup</tt></td>
1207     <td>Prevent the deletion of the temporary files that cvs2svn
1208       creates in the process of conversion.</td>
1209   </tr>
1210
1211   <tr>
1212     <td align="right"><tt>--profile</tt></td>
1213     <td>Dump Python <a href="http://docs.python.org/library/profile.html"
1214         >cProfile</a> profiling data to the file <tt>cvs2svn.cProfile</tt>.
1215         In Python 2.4 and earlier, if cProfile is not installed, it will
1216         instead dump <a href="http://docs.python.org/library/hotshot.html"
1217         >Hotshot</a> profiling data to the file <tt>cvs2svn.hotshot</tt>.</td>
1218   </tr>
1219
1220 </table>
1221
1222 <hr />
1223
1224 <h1><a name="examples">A Few Examples</a></h1>
1225
1226 <p>To create a new Subversion repository by converting an existing CVS
1227 repository, run the script like this:</p>
1228
1229 <pre>
1230    $ cvs2svn --svnrepos NEW_SVNREPOS CVSREPOS
1231 </pre>
1232
1233 <p>To create a new Subversion repository containing only trunk commits,
1234 and omitting all branches and tags from the CVS repository, do</p>
1235
1236 <pre>
1237    $ cvs2svn --trunk-only --svnrepos NEW_SVNREPOS CVSREPOS
1238 </pre>
1239
1240 <p>To create a Subversion dumpfile (suitable for 'svnadmin load') from
1241 a CVS repository, run it like this:</p>
1242
1243 <pre>
1244    $ cvs2svn --dumpfile DUMPFILE CVSREPOS
1245 </pre>
1246
1247 <p>To use an options file to define all of the conversion parameters,
1248 specify <tt>--options</tt>:</p>
1249
1250 <pre>
1251    $ cvs2svn --options OPTIONSFILE
1252 </pre>
1253
1254 <p>As it works, cvs2svn will create many temporary files in a
1255 temporary directory called "cvs2svn-tmp" (or the directory specified
1256 with <tt>--tmpdir</tt>).  This is normal.  If the entire conversion is
1257 successful, however, those tempfiles will be automatically removed.
1258 If the conversion is not successful, or if you specify the
1259 '--skip-cleanup' option, cvs2svn will leave the temporary files behind
1260 for possible debugging.</p>
1261
1262 </div>
1263 </body>
1264 </html>