git-cvsimport.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.2.5" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, h2, h3, h4, h5, h6 {
  40   color: #527bbd;
  41   font-family: sans-serif;
  42   margin-top: 1.2em;
  43   margin-bottom: 0.5em;
  44   line-height: 1.3;
  45 }
  46
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  91 div#footer {
  92   font-family: sans-serif;
  93   font-size: small;
  94   border-top: 2px solid silver;
  95   padding-top: 0.5em;
  96   margin-top: 4.0em;
  97 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 107 div#preamble,
 108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 110 div.admonitionblock {
 111   margin-right: 10%;
 112   margin-top: 1.5em;
 113   margin-bottom: 1.5em;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 124 /* Block element titles. */
 125 div.title, caption.title {
 126   font-family: sans-serif;
 127   font-weight: bold;
 128   text-align: left;
 129   margin-top: 1.0em;
 130   margin-bottom: 0.5em;
 131 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 172 div.admonitionblock .icon {
 173   vertical-align: top;
 174   font-size: 1.1em;
 175   font-weight: bold;
 176   text-decoration: underline;
 177   color: #527bbd;
 178   padding-right: 0.5em;
 179 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 249 div#toctitle {
 250   color: #527bbd;
 251   font-family: sans-serif;
 252   font-size: 1.1em;
 253   font-weight: bold;
 254   margin-top: 1.0em;
 255   margin-bottom: 0.1em;
 256 }
 257
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 282 div.sidebar-title, div.image-title {
 283   font-family: sans-serif;
 284   font-weight: bold;
 285   margin-top: 0.0em;
 286   margin-bottom: 0.5em;
 287 }
 288
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>git-cvsimport(1)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 git-cvsimport(1) Manual Page
 313 </h1>
 314 <h2>NAME</h2>
 315 <div class="sectionbody">
 316 <p>git-cvsimport -
 317    Salvage your data out of another SCM people love to hate
 318 </p>
 319 </div>
 320 </div>
 321 <h2>SYNOPSIS</h2>
 322 <div class="sectionbody">
 323 <div class="verseblock">
 324 <div class="content"><em>git cvsimport</em> [-o &lt;branch-for-HEAD&gt;] [-h] [-v] [-d &lt;CVSROOT&gt;]
 325               [-A &lt;author-conv-file&gt;] [-p &lt;options-for-cvsps&gt;] [-P &lt;file&gt;]
 326               [-C &lt;git_repository&gt;] [-z &lt;fuzz&gt;] [-i] [-k] [-u] [-s &lt;subst&gt;]
 327               [-a] [-m] [-M &lt;regex&gt;] [-S &lt;regex&gt;] [-L &lt;commitlimit&gt;]
 328               [-r &lt;remote&gt;] [-R] [&lt;CVS_module&gt;]</div></div>
 329 </div>
 330 <h2 id="_description">DESCRIPTION</h2>
 331 <div class="sectionbody">
 332 <div class="para"><p>Imports a CVS repository into git. It will either create a new
 333 repository, or incrementally import into an existing one.</p></div>
 334 <div class="para"><p>Splitting the CVS log into patch sets is done by <em>cvsps</em>.
 335 At least version 2.1 is required.</p></div>
 336 <div class="para"><p><strong>WARNING:</strong> for certain situations the import leads to incorrect results.
 337 Please see the section <a href="#issues">ISSUES</a> for further reference.</p></div>
 338 <div class="para"><p>You should <strong>never</strong> do any work of your own on the branches that are
 339 created by <em>git cvsimport</em>.  By default initial import will create and populate a
 340 "master" branch from the CVS repository's main branch which you're free
 341 to work with; after that, you need to <em>git merge</em> incremental imports, or
 342 any CVS branches, yourself.  It is advisable to specify a named remote via
 343 -r to separate and protect the incoming branches.</p></div>
 344 <div class="para"><p>If you intend to set up a shared public repository that all developers can
 345 read/write, or if you want to use <a href="git-cvsserver.html">git-cvsserver(1)</a>, then you
 346 probably want to make a bare clone of the imported repository,
 347 and use the clone as the shared repository.
 348 See <a href="gitcvs-migration.html">gitcvs-migration(7)</a>.</p></div>
 349 </div>
 350 <h2 id="_options">OPTIONS</h2>
 351 <div class="sectionbody">
 352 <div class="vlist"><dl>
 353 <dt>
 354 -v
 355 </dt>
 356 <dd>
 357 <p>
 358         Verbosity: let <em>cvsimport</em> report what it is doing.
 359 </p>
 360 </dd>
 361 <dt>
 362 -d &lt;CVSROOT&gt;
 363 </dt>
 364 <dd>
 365 <p>
 366         The root of the CVS archive. May be local (a simple path) or remote;
 367         currently, only the :local:, :ext: and :pserver: access methods
 368         are supported. If not given, <em>git cvsimport</em> will try to read it
 369         from <tt>CVS/Root</tt>. If no such file exists, it checks for the
 370         <tt>CVSROOT</tt> environment variable.
 371 </p>
 372 </dd>
 373 <dt>
 374 &lt;CVS_module&gt;
 375 </dt>
 376 <dd>
 377 <p>
 378         The CVS module you want to import. Relative to &lt;CVSROOT&gt;.
 379         If not given, <em>git cvsimport</em> tries to read it from
 380         <tt>CVS/Repository</tt>.
 381 </p>
 382 </dd>
 383 <dt>
 384 -C &lt;target-dir&gt;
 385 </dt>
 386 <dd>
 387 <p>
 388         The git repository to import to.  If the directory doesn't
 389         exist, it will be created.  Default is the current directory.
 390 </p>
 391 </dd>
 392 <dt>
 393 -r &lt;remote&gt;
 394 </dt>
 395 <dd>
 396 <p>
 397         The git remote to import this CVS repository into.
 398         Moves all CVS branches into remotes/&lt;remote&gt;/&lt;branch&gt;
 399         akin to the way <em>git clone</em> uses <em>origin</em> by default.
 400 </p>
 401 </dd>
 402 <dt>
 403 -o &lt;branch-for-HEAD&gt;
 404 </dt>
 405 <dd>
 406 <p>
 407         When no remote is specified (via -r) the <em>HEAD</em> branch
 408         from CVS is imported to the <em>origin</em> branch within the git
 409         repository, as <em>HEAD</em> already has a special meaning for git.
 410         When a remote is specified the <em>HEAD</em> branch is named
 411         remotes/&lt;remote&gt;/master mirroring <em>git clone</em> behaviour.
 412         Use this option if you want to import into a different
 413         branch.
 414 </p>
 415 <div class="para"><p>Use <em>-o master</em> for continuing an import that was initially done by
 416 the old cvs2git tool.</p></div>
 417 </dd>
 418 <dt>
 419 -i
 420 </dt>
 421 <dd>
 422 <p>
 423         Import-only: don't perform a checkout after importing.  This option
 424         ensures the working directory and index remain untouched and will
 425         not create them if they do not exist.
 426 </p>
 427 </dd>
 428 <dt>
 429 -k
 430 </dt>
 431 <dd>
 432 <p>
 433         Kill keywords: will extract files with <em>-kk</em> from the CVS archive
 434         to avoid noisy changesets. Highly recommended, but off by default
 435         to preserve compatibility with early imported trees.
 436 </p>
 437 </dd>
 438 <dt>
 439 -u
 440 </dt>
 441 <dd>
 442 <p>
 443         Convert underscores in tag and branch names to dots.
 444 </p>
 445 </dd>
 446 <dt>
 447 -s &lt;subst&gt;
 448 </dt>
 449 <dd>
 450 <p>
 451         Substitute the character "/" in branch names with &lt;subst&gt;
 452 </p>
 453 </dd>
 454 <dt>
 455 -p &lt;options-for-cvsps&gt;
 456 </dt>
 457 <dd>
 458 <p>
 459         Additional options for cvsps.
 460         The options <em>-u</em> and <em>-A</em> are implicit and should not be used here.
 461 </p>
 462 <div class="para"><p>If you need to pass multiple options, separate them with a comma.</p></div>
 463 </dd>
 464 <dt>
 465 -z &lt;fuzz&gt;
 466 </dt>
 467 <dd>
 468 <p>
 469         Pass the timestamp fuzz factor to cvsps, in seconds. If unset,
 470         cvsps defaults to 300s.
 471 </p>
 472 </dd>
 473 <dt>
 474 -P &lt;cvsps-output-file&gt;
 475 </dt>
 476 <dd>
 477 <p>
 478         Instead of calling cvsps, read the provided cvsps output file. Useful
 479         for debugging or when cvsps is being handled outside cvsimport.
 480 </p>
 481 </dd>
 482 <dt>
 483 -m
 484 </dt>
 485 <dd>
 486 <p>
 487         Attempt to detect merges based on the commit message. This option
 488         will enable default regexes that try to capture the source
 489         branch name from the commit message.
 490 </p>
 491 </dd>
 492 <dt>
 493 -M &lt;regex&gt;
 494 </dt>
 495 <dd>
 496 <p>
 497         Attempt to detect merges based on the commit message with a custom
 498         regex. It can be used with <em>-m</em> to enable the default regexes
 499         as well. You must escape forward slashes.
 500 </p>
 501 <div class="para"><p>The regex must capture the source branch name in $1.</p></div>
 502 <div class="para"><p>This option can be used several times to provide several detection regexes.</p></div>
 503 </dd>
 504 <dt>
 505 -S &lt;regex&gt;
 506 </dt>
 507 <dd>
 508 <p>
 509         Skip paths matching the regex.
 510 </p>
 511 </dd>
 512 <dt>
 513 -a
 514 </dt>
 515 <dd>
 516 <p>
 517         Import all commits, including recent ones. cvsimport by default
 518         skips commits that have a timestamp less than 10 minutes ago.
 519 </p>
 520 </dd>
 521 <dt>
 522 -L &lt;limit&gt;
 523 </dt>
 524 <dd>
 525 <p>
 526         Limit the number of commits imported. Workaround for cases where
 527         cvsimport leaks memory.
 528 </p>
 529 </dd>
 530 <dt>
 531 -A &lt;author-conv-file&gt;
 532 </dt>
 533 <dd>
 534 <p>
 535         CVS by default uses the Unix username when writing its
 536         commit logs. Using this option and an author-conv-file
 537         in this format
 538 </p>
 539 <div class="listingblock">
 540 <div class="content">
 541 <pre><tt>        exon=Andreas Ericsson &lt;ae@op5.se&gt;
 542         spawn=Simon Pawn &lt;spawn@frog-pond.org&gt;
 543 </tt></pre>
 544 </div></div>
 545 <div class="para"><p><em>git cvsimport</em> will make it appear as those authors had
 546 their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly
 547 all along.</p></div>
 548 <div class="para"><p>For convenience, this data is saved to <tt>$GIT_DIR/cvs-authors</tt>
 549 each time the <em>-A</em> option is provided and read from that same
 550 file each time <em>git cvsimport</em> is run.</p></div>
 551 <div class="para"><p>It is not recommended to use this feature if you intend to
 552 export changes back to CVS again later with
 553 <em>git cvsexportcommit</em>.</p></div>
 554 </dd>
 555 <dt>
 556 -R
 557 </dt>
 558 <dd>
 559 <p>
 560         Generate a <tt>$GIT_DIR/cvs-revisions</tt> file containing a mapping from CVS
 561         revision numbers to newly-created Git commit IDs.  The generated file
 562         will contain one line for each (filename, revision) pair imported;
 563         each line will look like
 564 </p>
 565 <div class="listingblock">
 566 <div class="content">
 567 <pre><tt>src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7</tt></pre>
 568 </div></div>
 569 <div class="para"><p>The revision data is appended to the file if it already exists, for use when
 570 doing incremental imports.</p></div>
 571 <div class="para"><p>This option may be useful if you have CVS revision numbers stored in commit
 572 messages, bug-tracking systems, email archives, and the like.</p></div>
 573 </dd>
 574 <dt>
 575 -h
 576 </dt>
 577 <dd>
 578 <p>
 579         Print a short usage message and exit.
 580 </p>
 581 </dd>
 582 </dl></div>
 583 </div>
 584 <h2 id="_output">OUTPUT</h2>
 585 <div class="sectionbody">
 586 <div class="para"><p>If <em>-v</em> is specified, the script reports what it is doing.</p></div>
 587 <div class="para"><p>Otherwise, success is indicated the Unix way, i.e. by simply exiting with
 588 a zero exit status.</p></div>
 589 </div>
 590 <h2 id="issues">ISSUES</h2>
 591 <div class="sectionbody">
 592 <div class="para"><p>Problems related to timestamps:</p></div>
 593 <div class="ilist"><ul>
 594 <li>
 595 <p>
 596 If timestamps of commits in the CVS repository are not stable enough
 597    to be used for ordering commits changes may show up in the wrong
 598    order.
 599 </p>
 600 </li>
 601 <li>
 602 <p>
 603 If any files were ever "cvs import"ed more than once (e.g., import of
 604    more than one vendor release) the HEAD contains the wrong content.
 605 </p>
 606 </li>
 607 <li>
 608 <p>
 609 If the timestamp order of different files cross the revision order
 610    within the commit matching time window the order of commits may be
 611    wrong.
 612 </p>
 613 </li>
 614 </ul></div>
 615 <div class="para"><p>Problems related to branches:</p></div>
 616 <div class="ilist"><ul>
 617 <li>
 618 <p>
 619 Branches on which no commits have been made are not imported.
 620 </p>
 621 </li>
 622 <li>
 623 <p>
 624 All files from the branching point are added to a branch even if
 625    never added in CVS.
 626 </p>
 627 </li>
 628 <li>
 629 <p>
 630 This applies to files added to the source branch <strong>after</strong> a daughter
 631    branch was created: if previously no commit was made on the daughter
 632    branch they will erroneously be added to the daughter branch in git.
 633 </p>
 634 </li>
 635 </ul></div>
 636 <div class="para"><p>Problems related to tags:</p></div>
 637 <div class="ilist"><ul>
 638 <li>
 639 <p>
 640 Multiple tags on the same revision are not imported.
 641 </p>
 642 </li>
 643 </ul></div>
 644 <div class="para"><p>If you suspect that any of these issues may apply to the repository you
 645 want to import consider using these alternative tools which proved to be
 646 more stable in practice:</p></div>
 647 <div class="ilist"><ul>
 648 <li>
 649 <p>
 650 cvs2git (part of cvs2svn), <tt>http://cvs2svn.tigris.org</tt>
 651 </p>
 652 </li>
 653 <li>
 654 <p>
 655 parsecvs, <tt>http://cgit.freedesktop.org/~keithp/parsecvs</tt>
 656 </p>
 657 </li>
 658 </ul></div>
 659 </div>
 660 <h2 id="_author">Author</h2>
 661 <div class="sectionbody">
 662 <div class="para"><p>Written by Matthias Urlichs &lt;smurf@smurf.noris.de&gt;, with help from
 663 various participants of the git-list &lt;git@vger.kernel.org&gt;.</p></div>
 664 </div>
 665 <h2 id="_documentation">Documentation</h2>
 666 <div class="sectionbody">
 667 <div class="para"><p>Documentation by Matthias Urlichs &lt;smurf@smurf.noris.de&gt;.</p></div>
 668 </div>
 669 <h2 id="_git">GIT</h2>
 670 <div class="sectionbody">
 671 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
 672 </div>
 673 <div id="footer">
 674 <div id="footer-text">
 675 Last updated 2010-09-18 23:56:38 UTC
 676 </div>
 677 </div>
 678 </body>
 679 </html>