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   <li>GNU sort, which is part of the coreutils package, see <a
 114     href="http://www.gnu.org/software/coreutils/"
 115          >http://www.gnu.org/software/coreutils/</a>.  Binaries for
 116     Win32 can be found at <a href="http://unxutils.sourceforge.net/"
 117                                   >http://unxutils.sourceforge.net/</a>.
 118     Windows <tt>sort.exe</tt> is <b>not</b> adequate.
 119   </li>
 120
 121 </ul>
 122
 123 <h2>CVSNT repositories</h2>
 124
 125 <p>cvs2svn does not support conversion of <a
 126 href="http://www.cvsnt.org/">CVSNT</a> repositories.  Some people have
 127 indicated success with such conversions, while others have had
 128 problems.  In other words, <em>such conversions, even if apparently
 129 successful, should be checked carefully before use.</em> See the <a
 130 href="faq.html#cvsnt">FAQ</a> for more information.</p>
 131
 132 <hr />
 133
 134 <h1><a name="install">Installation</a></h1>
 135
 136 <ul>
 137   <li>As root, run 'make install'.</li>
 138
 139   <li>Or, if you do not wish to install cvs2svn on your system, you
 140     can simply run it out of this directory.  As long as it can find
 141     the 'cvs2svn_rcsparse' library, it should be happy.</li>
 142
 143   <li>If you want to create Unix-style manpages for the main programs,
 144     run 'make man'.</li>
 145
 146 </ul>
 147
 148 <hr />
 149
 150 <h1><a name="convert">Deciding how much to convert</a></h1>
 151
 152 <p>If you're looking to switch an existing CVS repository to
 153 Subversion, you have a number of choices for migrating your existing
 154 CVS data to a Subversion repository, depending on your needs.</p>
 155
 156 <p>There are a few basic routes to choose when switching from CVS to
 157 Subversion, and the one you choose will depend on how much historical
 158 data you want in your Subversion repository.  You may be content to
 159 refer to your existing (soon-to-be-converted-to-read-only) CVS
 160 repository for "pre-Subversion" data and start working with a new
 161 Subversion repository.  Maybe you prefer to squeeze every last drop of
 162 data out of your CVS repository into your Subversion repository.  Then
 163 again, perhaps you want a conversion somewhere in between these two.
 164 Based on these needs, we've come up with these different recommended
 165 paths for converting your CVS repository to a Subversion
 166 repository.</p>
 167
 168 <ul>
 169
 170   <li>Top-skim (Doesn't require cvs2svn!)</li>
 171
 172   <li>Trunk only</li>
 173
 174   <li>Pick and choose</li>
 175
 176   <li>Full conversion</li>
 177
 178   <li>Smorgasbord</li>
 179
 180   <li>One project at a time</li>
 181
 182 </ul>
 183
 184 <p>If you decide that top-skimming doesn't meet your needs and you're
 185 going to use cvs2svn (yay!), then be sure to read the section below on
 186 <a href="#prep">prepping your repository</a> before you start your
 187 conversion.</p>
 188
 189
 190 <h2>Top-skimming</h2>
 191
 192 <p>This is the quickest and easiest way to get started in your new
 193 repository.  You're basically going to export the latest revision of
 194 your cvs repository, possibly do some rearranging, and then import the
 195 resulting files into your Subversion repository.  Typically, if you
 196 top-skim, that means you'll be either be keeping your old CVS
 197 repository around as a read-only reference for older data or just
 198 tossing that historical data outright (Note to you data packrats who
 199 have just stopped breathing, please take a deep breath and put down
 200 the letter opener.  You don't <i>have</i> to do this yourself--it's
 201 just that some people don't feel the same way you do about historical
 202 data.  They're really not <i>bad</i> people.  Really.).</p>
 203
 204 <blockquote>
 205
 206   <p><b>Pros:</b> Quick, easy, convenient, results in a very compact and
 207   "neat" Subversion repository.</p>
 208
 209   <p><b>Cons:</b> You've got no historical data, no branches, and no tags
 210   in your Subversion repository.  If you want any of this data, you'll
 211   have to go back into the CVS Repository and get it.</p>
 212
 213 </blockquote>
 214
 215
 216 <h2>Trunk only</h2>
 217
 218 <p>If you decide that you'd like to have the main development line of
 219 your historical data in your Subversion repository but don't need to
 220 carry over the tags and branches, you may want to skip converting your
 221 CVS tags and branches entirely and only convert the "trunk" of your
 222 repository.  To do this, you'll use the <tt>--trunk-only</tt> switch
 223 to cvs2svn.</p>
 224
 225 <blockquote>
 226
 227   <p><b>Pros:</b>Saves disk space in your new Subversion repository.
 228   Attractive to neatniks.</p>
 229
 230   <p><b>Cons:</b> You've got no branches and no tags in your
 231   Subversion repository.</p>
 232
 233 </blockquote>
 234
 235
 236 <h2>Pick and choose</h2>
 237
 238 <p>Let's say, for example, that you want to convert your CVS repository's
 239 historical data but you have no use for the myriad daily build tags
 240 that you've got in your CVS repository.  In addition to that, you want
 241 some branches but would prefer to ignore others.  In this case, you'll
 242 want to use the <tt>--exclude</tt> switch to instruct cvs2svn which
 243 branches and tags it should ignore. </p>
 244
 245 <blockquote>
 246
 247   <p><b>Pros:</b>You only get what you want from your CVS repository.
 248   Saves a some space.</p>
 249
 250   <p><b>Cons:</b>If you forgot something, you'll have to go to your
 251   CVS repository.</p>
 252
 253 </blockquote>
 254
 255
 256 <h2>Full conversion</h2>
 257
 258 <p>If you want to convert your entire CVS repository, including all
 259 tags and branches, you want a full conversion.  This is cvs2svn's
 260 default behavior.</p>
 261
 262 <blockquote>
 263
 264   <p><b>Pros:</b> Converts every last byte of your CVS repository.</p>
 265
 266   <p><b>Cons:</b> Requires more disk space.</p>
 267
 268 </blockquote>
 269
 270
 271 <h2>Smorgasbord</h2>
 272
 273 <p>You can convert your repository (or repositories) piece by piece
 274 using a combination of the above .</p>
 275
 276 <blockquote>
 277
 278   <p><b>Pros:</b> You get exactly what you want.</p>
 279
 280   <p><b>Cons:</b> Importing converted repositories multiple times into
 281   a single Subversion repository will likely break date-based range
 282   commands (e.g. <tt>svn diff -r {2002-02-17:2002-03-18}</tt>) since
 283   Subversion does a binary search through the repository for dates.
 284   While this is not the end of the world, it can be a minor
 285   inconvenience.</p>
 286
 287 </blockquote>
 288
 289
 290 <h2>One project at a time</h2>
 291
 292 <p>If you have many diverse projects in your CVS repository and you
 293 don't want to move them all to Subversion at once, you may want to
 294 convert to Subversion one project at a time.  This requires a few
 295 extra steps, but it can make the conversion of a large CVS repository
 296 much more manageable.  See <a href="faq.html#oneatatime">How can I
 297 convert my CVS repository one module at a time?</a> on the cvs2svn FAQ
 298 for a detailed example on converting your CVS repository one project
 299 at a time.</p>
 300
 301 <blockquote>
 302
 303   <p><b>Pros:</b>Allows multiple projects in a single repository to
 304   convert to Subversion according to a schedule that works best for
 305   them.</p>
 306
 307   <p><b>Cons:</b>Requires some extra steps to accomplish the
 308   conversion.  Importing converted repositories multiple times into a
 309   single Subversion repository will likely break date-based range
 310   commands (e.g. <tt>svn diff -r {2002-02-17:2002-03-18}</tt>) since
 311   Subversion does a binary search through the repository for dates.
 312   While this is not the end of the world, it can be a minor
 313   inconvenience.</p>
 314
 315 </blockquote>
 316
 317 <hr />
 318
 319 <h1><a name="prep">Prepping your repository</a></h1>
 320
 321 <p>There are a number of reasons that you may need to prep your CVS
 322 Repository.  If you decide that you need to change part of your CVS
 323 repository, we <b>strongly</b> recommend working on a <b>copy</b> of
 324 it instead of working on the real thing.  cvs2svn itself does not make
 325 any changes to your CVS repository, but if you start moving things
 326 around and deleting things in a CVS repository, it's all too easy to
 327 shoot yourself in the foot.</p>
 328
 329 <h2>End-of-line translation</h2>
 330
 331 <p>One of the most important topics to consider when converting a
 332 repository is the distinction between binary and text files.  If you
 333 accidentally treat a binary file as text <strong>your repository
 334 contents will be corrupted</strong>.</p>
 335
 336 <p>Text files are handled differently than binary files by both CVS
 337 and Subversion.  When a text file is checked out, the character used
 338 to denote the end of line ("EOL") is converted to the local computer's
 339 format.  This is usually the most convenient behavior for text files.
 340 Moreover, both CVS and Subversion allow "keywords" in text files (such
 341 as <tt>$Id$</tt>), which are expanded with version control information
 342 when the file is checked out.  However, if line-end translation or
 343 keyword expansion is applied to a binary file, the file will usually
 344 be corrupted.</p>
 345
 346 <p>CVS treats a file as text unless you specifically tell it that the
 347 file is binary.  You can tell CVS that a file is binary by using the
 348 command <tt>cvs admin -kb <i>filename</i></tt>.  But often CVS users
 349 forget to specify which files are binary, and as long as the
 350 repository is only used under Unix, they may never notice a problem,
 351 because the internal format of CVS is the same as the Unix format.
 352 But Subversion is not as forgiving as CVS if you tell it to treat a
 353 binary file as text.</p>
 354
 355 <p>If you have been conscientious about marking files as binary in
 356 CVS, then you should be able to use <tt>--default-eol=native</tt>.  If
 357 you have been sloppy, then you have a few choices:</p>
 358 <ul>
 359   <li>Convert your repository with cvs2svn's default options.  Your
 360     text files will be treated as binary, but that usually isn't very
 361     harmful (at least no information will be lost).</li>
 362
 363   <li>Mend your slovenly ways by fixing your CVS repository
 364     <em>before</em> conversion: run <tt>cvs admin -kb
 365     <i>filename</i></tt> for each binary file in the repository.  Then
 366     you can use <tt>--default-eol=native</tt> along with the
 367     anal-retentive folks.</li>
 368
 369   <li>Use cvs2svn options to help cvs2svn deduce which files are
 370     binary <em>during</em> the conversion.  The useful options are
 371     <tt>--eol-from-mime-type</tt>, <tt>--keywords-off</tt>,
 372     <tt>--auto-props</tt>, and <tt>--default-eol</tt>.  See the <a
 373     href="faq.html#eol-fixup">FAQ</a> for more information.</li>
 374
 375 </ul>
 376
 377 <h2>Converting part of repository</h2>
 378
 379 <p>If you want to convert a subdirectory in your repository, you can
 380 just point cvs2svn at the subdirectory and go.  There is no need to
 381 delete the unwanted directories from the CVS repository.</p>
 382
 383 <p>If the subdirectory that you are converting contains any files that
 384 you <i>don't</i> want converted into your new Subversion repository,
 385 you should delete them or move them aside.  Such files can be deleted
 386 from HEAD after the conversion, but they will still be visible in the
 387 repository history.</p>
 388
 389 <p>Lastly, even though you can move and copy files and directories
 390 around in Subversion, you may want to do some rearranging of project
 391 directories before running your conversion to get the desired
 392 repository project organization.</p>
 393
 394 <hr />
 395
 396 <h1><a name="cmd-vs-options">Command line vs. options file</a></h1>
 397
 398 <p>There are two ways to specify the options that define a conversion:
 399 via the cvs2svn command line, or via an options file.  The command
 400 line is useful for simple conversions, but the options file method is
 401 recommended for nontrivial conversions as it gives the user more
 402 flexibility.</p>
 403
 404 <h2><a name="cmd-line-method">Command line method</a></h2>
 405
 406 <p>A command-line conversion allows the use of all of the command line
 407 options listed <a href="#cmd-ref">below</a> (except for
 408 <tt>--options</tt>).  This method allows almost all of the built-in
 409 conversion options to be selected, with the primary limitation that it
 410 does not support multiproject conversions.  However, it may require a
 411 <em>long</em> command line to specify all of the options for a
 412 complicated conversion.</p>
 413
 414
 415 <h2><a name="options-file-method">Options file method</a></h2>
 416
 417 <p>The options file method allows full control of the conversion
 418 process, including multiproject conversions.  It also allows expert
 419 users to customize the conversion even more radically by writing
 420 Python code.  Finally, the options file used in the conversion can be
 421 retained as permanent record of the options used in a conversion.</p>
 422
 423 <p>To use the options file method, you need to create a file defining
 424 all of the options that are to be used for the conversion.  A
 425 heavily-commented sample options file,
 426 <tt>cvs2svn-example.options</tt>, is included in the cvs2svn
 427 distribution.  The easiest way to create your own options file is to
 428 make a copy of the sample file and modify it as directed by the
 429 comments in that file.</p>
 430
 431 <p><strong>Note:</strong> The options file format changes frequently.
 432 Please be sure to base your options file on the
 433 <tt>cvs2svn-example.options</tt> file from the version of cvs2svn that
 434 you plan to use.</p>
 435
 436 <p>To start a conversion using an options file, invoke cvs2svn like
 437 this:</p>
 438
 439 <pre>
 440    $ cvs2svn --options=OPTIONSFILE
 441 </pre>
 442
 443 <p>Only the following options are allowed in combination with
 444 <tt>--options</tt>: <tt>-h/--help</tt>, <tt>--help-passes</tt>,
 445 <tt>--version</tt>, <tt>-v/--verbose</tt>, <tt>-q/--quiet</tt>,
 446 <tt>-p/--pass/--passes</tt>, <tt>--dry-run</tt>, and
 447 <tt>--profile</tt>.</p>
 448
 449 <hr />
 450
 451
 452 <h1><a name="symbols">Symbol handling</a></h1>
 453
 454 <p>cvs2svn converts CVS tags and branches into Subversion tags and
 455 branches.  This section discusses issues related to symbol
 456 handling.</p>
 457
 458 <p><strong>HINT:</strong> If there are problems with symbol usage in
 459 your repository, they are usually reported during
 460 <tt>CollateSymbolsPass</tt> of the conversion, causing the conversion
 461 to be interrupted.  However, it is not necessary to restart the whole
 462 conversion to fix the problems.  Usually it is adequate to adjust the
 463 symbol-handling options then re-start cvs2svn starting at
 464 <tt>CollateSymbolsPass</tt>, by adding the option "<tt>-p
 465 CollateSymbolsPass:</tt>".  This trick can save a lot of time if you
 466 have a large repository, as it might take a few iterations before you
 467 find the best set of options to convert your repository.</p>
 468
 469
 470 <h2><a name="symbol-layout">Placement of trunk, branches, and tags
 471 directories</a></h2>
 472
 473 <p>cvs2svn converts CVS branches and tags into Subversion branches and
 474 tags following the <a
 475 href="http://svnbook.red-bean.com/en/1.2/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">standard
 476 Subversion convention</a>.  For single-project conversions, the
 477 default is to put the trunk, branches, and tags directories at the top
 478 level of the repository tree, though this behavior can be changed by
 479 using the <tt>--trunk</tt>, <tt>--branches</tt>, and <tt>--tags</tt>
 480 options.  For multiproject conversions, you must specify the location
 481 of each project's trunk, branches, and tags directory in the options
 482 file; <a
 483 href="http://svnbook.red-bean.com/en/1.4/svn.branchmerge.maint.html#svn.branchmerge.maint.layout">repository
 484 layout strategies</a> are discussed in the <a
 485 href="http://svnbook.red-bean.com/">Subversion book</a>.  For even
 486 finer control over the conversion, you can use a
 487 <tt>--symbol-hints</tt> file to specify the SVN path to be used for
 488 each CVS tag and branch.</p>
 489
 490
 491 <h2><a name="symbol-exclusion">Excluding tags and branches</a></h2>
 492
 493 <p>Often a CVS repository contains tags and branches that will not be
 494 needed after the conversion to Subversion.  You can instruct cvs2svn
 495 to exclude such symbols from the conversion, in which case they will
 496 not be present in the resulting Subversion repository.  Please be
 497 careful when doing this; excluding symbols causes information that was
 498 present in CVS to be omitted in Subversion, thereby discarding
 499 potentially useful historical information.  Also be aware that if you
 500 exclude a branch, then all CVS revisions that were committed to that
 501 branch will also be excluded.</p>
 502
 503 <p>To exclude a tag or branch, use the option
 504 <tt>--exclude=SYMBOL</tt>.  You can also exclude a whole group of
 505 symbols matching a specified regular expression; for example,
 506 <tt>--exclude='RELEASE_0_.*'</tt>.  (The regular expression has to
 507 match the <em>whole</em> symbol name for the rule to apply.)</p>
 508
 509 <p>However, please note the following restriction.  If a branch has a
 510 subbranch or a tag on it, then the branch cannot be excluded unless
 511 the dependent symbol is also excluded.  cvs2svn checks for this
 512 situation; if it occurs then <tt>CollateSymbolsPass</tt> outputs an
 513 error message like the following:</p>
 514
 515 <pre>
 516    ERROR: The branch 'BRANCH' cannot be excluded because the following symbols depend on it:
 517        'TAG'
 518        'SUBBRANCH'
 519 </pre>
 520
 521 <p>In such a case you can either exclude the dependent symbol(s) (in
 522 this case by using <tt>--exclude=TAG --exclude=SUBBRANCH</tt>) or
 523 <em>not</em> exclude 'BRANCH'.</p>
 524
 525 <h3>Excluding vendor branches</h3>
 526
 527 <p>There is one more special case related to branch handling.  A <a
 528 href="http://cvsbook.red-bean.com/cvsbook.html#Tracking%20Third-Party%20Sources%20(Vendor%20Branches)">vendor
 529 branch</a> is a CVS branch that is used to track source code received
 530 from an outside source.  A vendor branch typically has CVS branch
 531 number <tt>1.1.1</tt> and revision numbers <tt>1.1.1.1</tt>,
 532 <tt>1.1.1.2</tt>, etc.  Vendor branches are created automatically
 533 whenever the <tt>cvs import</tt> command is used.  Vendor branches
 534 have the strange property that, under certain circumstances, a file
 535 that appears on a vendor branch also implicitly exists on trunk.
 536 cvs2svn knows all about vendor branches and does its best to ensure
 537 that a file that appears on a vendor branch is also copied to trunk,
 538 to give Subversion behavior that is as close as possible to the CVS
 539 behavior.</p>
 540
 541 <p>However, often vendor branches exist for reasons unrelated to
 542 tracking outside sources.  Indeed, some CVS documentation recommends
 543 using the <tt>cvs import</tt> command to import your own code into
 544 your CVS repository (which is arguably a misuse of the <tt>cvs
 545 import</tt> command).  Vendor branches created by this practice are
 546 useless and would only serve to clutter up your Subversion repository.
 547 Therefore, cvs2svn allows vendor branches to be excluded, in which
 548 case the vendor branch revisions are grafted onto the history of
 549 trunk.  This is allowed <em>even if</em> other branches or tags appear
 550 to sprout from the vendor branch, in which case the dependent tags are
 551 grafted to trunk as well.  Such branches can be recognized in the
 552 <tt>--write-symbol-info</tt> by looking for a symbol that is a "pure
 553 import" in the same number of files that it appears as a branch.  It
 554 is typically advantageous to exclude such branches.</p>
 555
 556
 557 <h2><a name="symbol-inconsistencies">Tag/branch inconsistencies</a></h2>
 558
 559 <p>In CVS, the same symbol can appear as a tag in some files (e.g.,
 560 <tt>cvs tag SYMBOL file1.txt</tt>) and a branch in others (e.g.,
 561 <tt>cvs tag -b SYMBOL file2.txt</tt>).  Subversion takes a more global
 562 view of your repository, and therefore works better when each symbol
 563 is used in a self-consistent way--either always as a branch or always
 564 as a tag.  cvs2svn provides features to help you resolve these
 565 ambiguities.</p>
 566
 567 <p>If your repository contains inconsistently-used symbols, then
 568 <tt>CollateSymbolsPass</tt>, by default, uses heuristics to decide
 569 which symbols to convert as branches and which as tags.  Often this
 570 behavior will be adequate, and you don't have to do anything special.
 571 You can use the <tt>--write-symbol-info=<i>filename</i></tt> option to
 572 cause cvs2svn to list all of the symbols in your repository and how it
 573 chose to convert them to <tt><i>filename</i></tt>.</p>
 574
 575 <p>However, if you want to take finer control over how symbols are
 576 converted, you can do so.  The first step is probably to change the
 577 default symbol handling style from <tt>heuristic</tt> (the default
 578 value) to <tt>strict</tt> using the option
 579 <tt>--symbol-default=strict</tt>.  With the <tt>strict</tt> setting,
 580 cvs2svn prints error messages and aborts the conversion if there are
 581 any ambiguous symbols.  The error messages look like this:</p>
 582
 583 <pre>
 584    ERROR: It is not clear how the following symbols should be converted.
 585    Use --symbol-hints, --force-tag, --force-branch, --exclude, and/or
 586    --symbol-default to resolve the ambiguity.
 587        'SYMBOL1' is a tag in 1 files, a branch in 2 files and has commits in 0 files
 588        'SYMBOL2' is a tag in 2 files, a branch in 1 files and has commits in 0 files
 589        'SYMBOL3' is a tag in 1 files, a branch in 2 files and has commits in 1 files
 590 </pre>
 591
 592 <p>You have to tell cvs2svn how to fix the inconsistencies then
 593 restart the conversion at <tt>CollateSymbolsPass</tt>.</p>
 594
 595 <p>There are three ways to deal with an inconsistent symbol: treat it
 596 as a tag, treat it as a branch, or exclude it from the conversion
 597 altogether.</p>
 598
 599 <p>In the example above, the symbol 'SYMBOL1' was used as a branch in
 600 two files but used as a tag in only one file.  Therefore, it might
 601 make sense to convert it as a branch, by using the option
 602 <tt>--force-branch=SYMBOL1</tt>.  However, no revisions were committed
 603 on this branch, so it would also be possible to convert it as a tag,
 604 by using the option <tt>--force-tag=SYMBOL1</tt>.  If the symbol is
 605 not needed at all, it can be excluded by using
 606 <tt>--exclude=SYMBOL1</tt>.</p>
 607
 608 <p>Similarly, 'SYMBOL2' was used more often as a tag, but can still be
 609 converted as a branch or a tag, or excluded.</p>
 610
 611 <p><tt>SYMBOL3</tt>, on the other hand, was sometimes used as a
 612 branch, and at least one revision was committed on the branch.  It can
 613 be converted as a branch, using <tt>--force-branch=SYMBOL3</tt>.  But
 614 it cannot be converted as a tag (because tags are not allowed to have
 615 revisions on them).  If it is excluded, using
 616 <tt>--exclude=SYMBOL3</tt>, then both the branch and the revisions on
 617 the branch will be left out of the Subversion repository.</p>
 618
 619 <p>If you are not so picky about which symbols are converted as tags
 620 and which as branches, you can ask cvs2svn to decide by itself.  To do
 621 this, specify the <tt>--symbol-default=OPTION</tt>, where
 622 <tt>OPTION</tt> can be either "<tt>heuristic</tt>" (the default;
 623 decide how to treat each ambiguous symbol based on whether it was used
 624 more often as a branch or as a tag in CVS), "<tt>branch</tt>" (treat
 625 every ambiguous symbol as a branch), or "<tt>tag</tt>" (treat every
 626 ambiguous symbol as a tag).  You can use the <tt>--force-branch</tt>
 627 and <tt>--force-tag</tt> options to specify the treatment of
 628 particular symbols, in combination with <tt>--symbol-default</tt> to
 629 specify the default to be used for other ambiguous symbols.</p>
 630
 631 <p>Finally, you can have cvs2svn write a text file showing how each
 632 symbol was converted by using the <tt>--write-symbol-info</tt> option.
 633 If you disagree with any of cvs2svn's choices, you can make a copy of
 634 this file, edit it, then pass it to cvs2svn by using the
 635 <tt>--symbol-hints</tt> option.  In this manner you can influence how
 636 each symbol is converted and also the parent line of development of
 637 each symbol (the line of development from which the symbol
 638 sprouts).</p>
 639
 640 <hr />
 641
 642
 643 <h1><a name="cmd-ref">Command line reference</a></h1>
 644
 645 <table border="1" cellpadding="10" cellspacing="3" width="80%">
 646
 647   <tr>
 648     <td colspan="2">
 649       <strong>USAGE:</strong><br/>
 650       <tt>cvs2svn [OPTIONS]... [-s SVN-REPOS-PATH|--dumpfile=PATH|--dry-run]
 651       CVS-REPOS-PATH</tt><br/>
 652       <tt>cvs2svn [OPTIONS]... --options=PATH</tt><br/>
 653     </td>
 654   </tr>
 655
 656   <tr>
 657     <td align="right"><tt>CVS-REPOS-PATH</tt></td>
 658     <td>The filesystem path of the part of the CVS repository that you
 659       want to convert.  It is not possible to convert a CVS repository
 660       to which you only have remote access; see <a
 661       href="faq.html#repoaccess">the FAQ</a> for details.  This
 662       doesn't have to be the top level directory of a CVS repository;
 663       it can point at a project within a repository, in which case
 664       only that project will be converted.  This path or one of its
 665       parent directories has to contain a subdirectory called CVSROOT
 666       (though the CVSROOT directory can be empty).</td>
 667   </tr>
 668
 669   <tr>
 670     <th colspan="2">
 671       Configuration via options file
 672     </th>
 673   </tr>
 674
 675   <tr>
 676     <td align="right"><tt>--options=PATH</tt></td>
 677     <td>Read the conversion options from the specified file.  See
 678       section <a href="#options-file-method">options file method</a>
 679       for more information.</td>
 680   </tr>
 681
 682   <tr>
 683     <th colspan="2">
 684       Output options
 685     </th>
 686   </tr>
 687
 688   <tr>
 689     <td align="right"><tt>-s PATH</tt><br/><tt>--svnrepos PATH</tt></td>
 690     <td>Write the output of the conversion into a Subversion
 691       repository located at PATH.  This option causes a new Subversion
 692       repository to be created at PATH unless the
 693       <tt>--existing-svnrepos</tt> option is also used.</td>
 694   </tr>
 695
 696   <tr>
 697     <td align="right"><tt>--existing-svnrepos</tt></td>
 698     <td>Load the converted CVS repository into an existing Subversion
 699       repository, instead of creating a new repository.  (This option
 700       should be used in combination with
 701       <tt>-s</tt>/<tt>--svnrepos</tt>.)  The repository must either be
 702       empty or contain no paths that overlap with those that will
 703       result from the conversion.  Please note that you need write
 704       permission for the repository files.</td>
 705   </tr>
 706
 707   <tr>
 708     <td align="right"><tt>--fs-type=TYPE</tt></td>
 709     <td>Pass the <tt>--fs-type=TYPE</tt> option to "svnadmin
 710       create" if creating a new Subversion repository.</td>
 711   </tr>
 712
 713   <tr>
 714     <td align="right"><tt>--bdb-txn-nosync</tt></td>
 715     <td>Pass the <tt>--bdb-txn-nosync</tt> switch to "svnadmin
 716       create" if creating a new Subversion repository.</td>
 717   </tr>
 718
 719   <tr>
 720     <td align="right"><tt>--create-option=OPT</tt></td>
 721     <td>Pass OPT to "svnadmin create" if creating a new Subversion
 722       repository (can be specified multiple times to pass multiple
 723       options).</td>
 724   </tr>
 725
 726   <tr>
 727     <td align="right"><tt>--dumpfile=PATH</tt></td>
 728     <td>Output the converted CVS repository into a Subversion dumpfile
 729       instead of a Subversion repository (useful for importing a CVS
 730       repository into an existing Subversion repository).  PATH is the
 731       filename in which to store the dumpfile.</td>
 732   </tr>
 733
 734   <tr>
 735     <td align="right"><tt>--dry-run</tt></td>
 736     <td>Do not create a repository or a dumpfile; just print the details
 737       of what cvs2svn would do if it were really converting your
 738       repository.</td>
 739   </tr>
 740
 741   <tr>
 742     <th colspan="2">
 743       Conversion options
 744     </th>
 745   </tr>
 746
 747   <tr>
 748     <td align="right"><tt>--trunk-only</tt></td>
 749     <td>Convert only the main line of development from the CVS
 750       repository (commonly referred to in Subversion parlance as
 751       "trunk"), ignoring all tags and branches.</td>
 752   </tr>
 753
 754   <tr>
 755     <td align="right"><tt>--trunk=PATH</tt></td>
 756     <td>The top-level path to use for trunk in the Subversion
 757       repository.  The default value is "trunk".</td>
 758   </tr>
 759
 760   <tr>
 761     <td align="right"><tt>--branches=PATH</tt></td>
 762     <td>The top-level path to use for branches in the Subversion
 763       repository.  The default value is "branches".</td>
 764   </tr>
 765
 766   <tr>
 767     <td align="right"><tt>--tags=PATH</tt></td>
 768     <td>The top-level path to use for tags in the Subversion
 769       repository.  The default value is "tags".</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 id date" if the mode of the RCS file in question is
1014       either kv, kvl or <b>not</b> kb.  If you use the
1015       <tt>--keywords-off</tt> switch, cvs2svn will not set
1016       <tt>svn:keywords</tt> for any file.  While this will not touch
1017       the keywords in the contents of your files, Subversion will not
1018       expand them.</td>
1019   </tr>
1020
1021   <tr>
1022     <td align="right"><tt>--keep-cvsignore</tt></td>
1023     <td>Include <tt>.cvsignore</tt> files in the output.  (Normally
1024       they are unneeded because cvs2svn sets the corresponding
1025       <tt>svn:ignore</tt> properties.)</td>
1026   </tr>
1027
1028   <tr>
1029     <td align="right"><tt>--cvs-revnums</tt></td>
1030     <td>Record CVS revision numbers as file properties in the
1031       Subversion repository.  (Note that unless it is removed
1032       explicitly, the last CVS revision number will remain associated
1033       with the file even after the file is changed within
1034       Subversion.)</td>
1035   </tr>
1036
1037   <tr>
1038     <th colspan="2">
1039       Extraction options
1040     </th>
1041   </tr>
1042
1043   <tr>
1044     <td align="right">
1045       <a name="use-internal-co"><tt>--use-internal-co</tt></a>
1046     </td>
1047     <td>Use internal code to extract the contents of CVS revisions.
1048       This is the default extraction option.  This is up to 50% faster
1049       than <tt>--use-rcs</tt>, but needs a lot of disk space: roughly
1050       the size of your CVS repository plus the peak size of a complete
1051       checkout of the repository with all branches that existed and
1052       still had commits pending at a given time.  If this option is
1053       used, the <tt>$Log$</tt> keyword is not handled.
1054     </td>
1055   </tr>
1056
1057   <tr>
1058     <td align="right"><a name="use-rcs"><tt>--use-rcs</tt></a></td>
1059     <td>Use RCS's <b><tt>co</tt></b> command to extract the contents
1060       of CVS revisions.  RCS is much faster than CVS, but in certain
1061       rare cases it has problems with data that CVS can handle.
1062       Specifically:
1063       <ul>
1064         <li>RCS can't handle spaces in author names:<br/>
1065           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4"
1066                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=4</a>
1067         </li>
1068         <li>"Unterminated keyword" misread by RCS:<br/>
1069           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11"
1070                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=11</a>
1071         </li>
1072         <li>RCS handles the "$Log$" keyword differently from CVS:<br/>
1073           <a href="http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29"
1074                   >http://cvs2svn.tigris.org/issues/show_bug.cgi?id=29</a>
1075         </li>
1076       </ul>
1077       If you are having trouble in <tt>OutputPass</tt> of a
1078       conversion when using the <tt>--use-rcs</tt> option, the first
1079       thing to try is using the <tt>--use-cvs</tt> option instead.
1080     </td>
1081   </tr>
1082
1083   <tr>
1084     <td align="right"><a name="use-cvs"><tt>--use-cvs</tt></a></td>
1085     <td>If RCS <b><tt>co</tt></b> is having trouble extracting CVS
1086       revisions, you may need to pass this flag, which causes cvs2svn
1087       to use CVS instead of RCS to read the repository.  See <a
1088       href="#use-rcs"><tt>--use-rcs</tt></a> for more information.
1089     </td>
1090   </tr>
1091
1092   <tr>
1093     <th colspan="2">
1094       Environment options
1095     </th>
1096   </tr>
1097
1098   <tr>
1099     <td align="right"><tt>--tmpdir=PATH</tt></td>
1100     <td>Use the directory PATH for all of cvs2svn's temporary data
1101       (which can be a <i>lot</i> of data).  The default value is
1102       <tt>cvs2svn-tmp</tt> in the current working directory.</td>
1103   </tr>
1104
1105   <tr>
1106     <td align="right"><tt>--svnadmin=PATH</tt></td>
1107     <td>If the <tt>svnadmin</tt> program is not in your $PATH you
1108       should specify its absolute path with this switch.
1109       <tt>svnadmin</tt> is needed when the <tt>-s/--svnrepos</tt>
1110       output option is used</td>
1111   </tr>
1112
1113   <tr>
1114     <td align="right"><tt>--co=PATH</tt></td>
1115     <td>If the <tt>co</tt> program (a part of RCS) is not in your
1116       $PATH you should specify its absolute path with this switch.
1117       (<tt>co</tt> is needed if the <tt>--use-rcs</tt> extraction
1118       option is used.)</td>
1119   </tr>
1120
1121   <tr>
1122     <td align="right"><tt>--cvs=PATH</tt></td>
1123     <td>If the cvs program is not in your $PATH you should
1124       specify its absolute path with this switch.  (<tt>cvs</tt> is
1125       needed if the <tt>--use-cvs</tt> extraction option is
1126       used.)</td>
1127   </tr>
1128
1129   <tr>
1130     <td align="right"><tt>--sort=PATH</tt></td>
1131     <td>If the GNU <tt>sort</tt> program is not in your $PATH you
1132       should specify its absolute path with this switch.  cvs2svn
1133       requires GNU <tt>sort</tt>; Windows <tt>sort.exe</tt> is
1134       <b>not</b> adequate.</td>
1135   </tr>
1136
1137   <tr>
1138     <th colspan="2">
1139       Partial conversions
1140     </th>
1141   </tr>
1142
1143   <tr>
1144     <td align="right"><tt>-p PASS</tt><br/><tt>--pass PASS</tt></td>
1145     <td>Execute only pass PASS of the conversion.  PASS can be
1146     specified by name or by number (see <tt>--help-passes</tt>)</td>
1147   </tr>
1148
1149   <tr>
1150     <td align="right"><tt>-p [START]:[END]</tt><br/><tt>--passes [START]:[END]</tt></td>
1151     <td>Execute passes START through END of the conversion
1152     (inclusive).  START and END can be specified by name or by number
1153     (see <tt>--help-passes</tt>).  If START or END is missing, it
1154     defaults to the first or last pass, respectively.</td>
1155   </tr>
1156
1157   <tr>
1158     <th colspan="2">
1159       Information options
1160     </th>
1161   </tr>
1162
1163   <tr>
1164     <td align="right"><tt>--version</tt></td>
1165     <td>Print the version number.</td>
1166   </tr>
1167
1168   <tr>
1169     <td align="right"><tt>--help</tt>, <tt>-h</tt></td>
1170     <td>Print the usage message and exit with success.</td>
1171   </tr>
1172
1173   <tr>
1174     <td align="right"><tt>--help-passes</tt></td>
1175     <td>Print the numbers and names of the conversion passes and exit
1176     with success.</td>
1177   </tr>
1178
1179   <tr>
1180     <td align="right"><tt>--man</tt></td>
1181     <td>Write the manpage for this program to standard output.</td>
1182   </tr>
1183
1184   <tr>
1185     <td align="right"><tt>--verbose</tt>, <tt>-v</tt></td>
1186     <td>Tell cvs2svn to print lots of information about what
1187       it's doing to STDOUT.  This option can be specified twice to get
1188       debug-level output.</td>
1189   </tr>
1190
1191   <tr>
1192     <td align="right"><tt>--quiet</tt>, <tt>-q</tt></td>
1193     <td>Tell cvs2svn to operate in quiet mode, printing little more
1194       than pass starts and stops to STDOUT.  This option may be
1195       specified twice to suppress all non-error output.</td>
1196   </tr>
1197
1198   <tr>
1199     <td align="right"><tt>--write-symbol-info=PATH</tt></td>
1200     <td>Write symbol statistics and information about how symbols were
1201       converted to PATH during CollateSymbolsPass.  See
1202       <tt>--symbol-hints</tt> for a description of the output
1203       format.</td>
1204   </tr>
1205
1206   <tr>
1207     <td align="right"><tt>--skip-cleanup</tt></td>
1208     <td>Prevent the deletion of the temporary files that cvs2svn
1209       creates in the process of conversion.</td>
1210   </tr>
1211
1212   <tr>
1213     <td align="right"><tt>--profile</tt></td>
1214     <td>Dump Python <a href="http://docs.python.org/lib/module-hotshot.html"
1215         >Hotshot</a> profiling data to the file <tt>cvs2svn.hotshot</tt>.</td>
1216   </tr>
1217
1218 </table>
1219
1220 <hr />
1221
1222 <h1><a name="examples">A Few Examples</a></h1>
1223
1224 <p>To create a new Subversion repository by converting an existing CVS
1225 repository, run the script like this:</p>
1226
1227 <pre>
1228    $ cvs2svn --svnrepos NEW_SVNREPOS CVSREPOS
1229 </pre>
1230
1231 <p>To create a new Subversion repository containing only trunk commits,
1232 and omitting all branches and tags from the CVS repository, do</p>
1233
1234 <pre>
1235    $ cvs2svn --trunk-only --svnrepos NEW_SVNREPOS CVSREPOS
1236 </pre>
1237
1238 <p>To create a Subversion dumpfile (suitable for 'svnadmin load') from
1239 a CVS repository, run it like this:</p>
1240
1241 <pre>
1242    $ cvs2svn --dumpfile DUMPFILE CVSREPOS
1243 </pre>
1244
1245 <p>To use an options file to define all of the conversion parameters,
1246 specify <tt>--options</tt>:</p>
1247
1248 <pre>
1249    $ cvs2svn --options OPTIONSFILE
1250 </pre>
1251
1252 <p>As it works, cvs2svn will create many temporary files in a
1253 temporary directory called "cvs2svn-tmp" (or the directory specified
1254 with <tt>--tmpdir</tt>).  This is normal.  If the entire conversion is
1255 successful, however, those tempfiles will be automatically removed.
1256 If the conversion is not successful, or if you specify the
1257 '--skip-cleanup' option, cvs2svn will leave the temporary files behind
1258 for possible debugging.</p>
1259
1260 </div>
1261 </body>
1262 </html>