Autogenerated HTML docs for v1.7.5-52-ge839f
[git/jnareb-git.git] / git-cvsimport.html
blob41d352504e7a669bcdcabc9ba5e5fc04d3647854
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.4.5" />
7 <title>git-cvsimport(1)</title>
8 <style type="text/css">
9 /* Debug borders */
10 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
12 border: 1px solid red;
16 body {
17 margin: 1em 5% 1em 5%;
20 a {
21 color: blue;
22 text-decoration: underline;
24 a:visited {
25 color: fuchsia;
28 em {
29 font-style: italic;
30 color: navy;
33 strong {
34 font-weight: bold;
35 color: #083194;
38 tt {
39 color: navy;
42 h1, h2, h3, h4, h5, h6 {
43 color: #527bbd;
44 font-family: sans-serif;
45 margin-top: 1.2em;
46 margin-bottom: 0.5em;
47 line-height: 1.3;
50 h1, h2, h3 {
51 border-bottom: 2px solid silver;
53 h2 {
54 padding-top: 0.5em;
56 h3 {
57 float: left;
59 h3 + * {
60 clear: left;
63 div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
68 hr {
69 border: 1px solid silver;
72 p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
77 ul, ol, li > p {
78 margin-top: 0;
81 pre {
82 padding: 0;
83 margin: 0;
86 span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
90 font-size: 1.1em;
92 span#email {
94 span#revnumber, span#revdate, span#revremark {
95 font-family: sans-serif;
98 div#footer {
99 font-family: sans-serif;
100 font-size: small;
101 border-top: 2px solid silver;
102 padding-top: 0.5em;
103 margin-top: 4.0em;
105 div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
109 div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
114 div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
118 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120 div.admonitionblock {
121 margin-top: 1.5em;
122 margin-bottom: 1.5em;
124 div.admonitionblock {
125 margin-top: 2.5em;
126 margin-bottom: 2.5em;
129 div.content { /* Block element content. */
130 padding: 0;
133 /* Block element titles. */
134 div.title, caption.title {
135 color: #527bbd;
136 font-family: sans-serif;
137 font-weight: bold;
138 text-align: left;
139 margin-top: 1.0em;
140 margin-bottom: 0.5em;
142 div.title + * {
143 margin-top: 0;
146 td div.title:first-child {
147 margin-top: 0.0em;
149 div.content div.title:first-child {
150 margin-top: 0.0em;
152 div.content + div.title {
153 margin-top: 0.0em;
156 div.sidebarblock > div.content {
157 background: #ffffee;
158 border: 1px solid silver;
159 padding: 0.5em;
162 div.listingblock > div.content {
163 border: 1px solid silver;
164 background: #f4f4f4;
165 padding: 0.5em;
168 div.quoteblock {
169 padding-left: 2.0em;
170 margin-right: 10%;
172 div.quoteblock > div.attribution {
173 padding-top: 0.5em;
174 text-align: right;
177 div.verseblock {
178 padding-left: 2.0em;
179 margin-right: 10%;
181 div.verseblock > div.content {
182 white-space: pre;
184 div.verseblock > div.attribution {
185 padding-top: 0.75em;
186 text-align: left;
188 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
189 div.verseblock + div.attribution {
190 text-align: left;
193 div.admonitionblock .icon {
194 vertical-align: top;
195 font-size: 1.1em;
196 font-weight: bold;
197 text-decoration: underline;
198 color: #527bbd;
199 padding-right: 0.5em;
201 div.admonitionblock td.content {
202 padding-left: 0.5em;
203 border-left: 2px solid silver;
206 div.exampleblock > div.content {
207 border-left: 2px solid silver;
208 padding: 0.5em;
211 div.imageblock div.content { padding-left: 0; }
212 span.image img { border-style: none; }
213 a.image:visited { color: white; }
215 dl {
216 margin-top: 0.8em;
217 margin-bottom: 0.8em;
219 dt {
220 margin-top: 0.5em;
221 margin-bottom: 0;
222 font-style: normal;
223 color: navy;
225 dd > *:first-child {
226 margin-top: 0.1em;
229 ul, ol {
230 list-style-position: outside;
232 ol.arabic {
233 list-style-type: decimal;
235 ol.loweralpha {
236 list-style-type: lower-alpha;
238 ol.upperalpha {
239 list-style-type: upper-alpha;
241 ol.lowerroman {
242 list-style-type: lower-roman;
244 ol.upperroman {
245 list-style-type: upper-roman;
248 div.compact ul, div.compact ol,
249 div.compact p, div.compact p,
250 div.compact div, div.compact div {
251 margin-top: 0.1em;
252 margin-bottom: 0.1em;
255 div.tableblock > table {
256 border: 3px solid #527bbd;
258 thead {
259 font-family: sans-serif;
260 font-weight: bold;
262 tfoot {
263 font-weight: bold;
265 td > div.verse {
266 white-space: pre;
268 p.table {
269 margin-top: 0;
271 /* Because the table frame attribute is overriden by CSS in most browsers. */
272 div.tableblock > table[frame="void"] {
273 border-style: none;
275 div.tableblock > table[frame="hsides"] {
276 border-left-style: none;
277 border-right-style: none;
279 div.tableblock > table[frame="vsides"] {
280 border-top-style: none;
281 border-bottom-style: none;
285 div.hdlist {
286 margin-top: 0.8em;
287 margin-bottom: 0.8em;
289 div.hdlist tr {
290 padding-bottom: 15px;
292 dt.hdlist1.strong, td.hdlist1.strong {
293 font-weight: bold;
295 td.hdlist1 {
296 vertical-align: top;
297 font-style: normal;
298 padding-right: 0.8em;
299 color: navy;
301 td.hdlist2 {
302 vertical-align: top;
304 div.hdlist.compact tr {
305 margin: 0;
306 padding-bottom: 0;
309 .comment {
310 background: yellow;
313 @media print {
314 div#footer-badges { display: none; }
317 div#toctitle {
318 color: #527bbd;
319 font-family: sans-serif;
320 font-size: 1.1em;
321 font-weight: bold;
322 margin-top: 1.0em;
323 margin-bottom: 0.1em;
326 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
327 margin-top: 0;
328 margin-bottom: 0;
330 div.toclevel2 {
331 margin-left: 2em;
332 font-size: 0.9em;
334 div.toclevel3 {
335 margin-left: 4em;
336 font-size: 0.9em;
338 div.toclevel4 {
339 margin-left: 6em;
340 font-size: 0.9em;
342 /* Overrides for manpage documents */
343 h1 {
344 padding-top: 0.5em;
345 padding-bottom: 0.5em;
346 border-top: 2px solid silver;
347 border-bottom: 2px solid silver;
349 h2 {
350 border-style: none;
352 div.sectionbody {
353 margin-left: 5%;
356 @media print {
357 div#toc { display: none; }
360 /* Workarounds for IE6's broken and incomplete CSS2. */
362 div.sidebar-content {
363 background: #ffffee;
364 border: 1px solid silver;
365 padding: 0.5em;
367 div.sidebar-title, div.image-title {
368 color: #527bbd;
369 font-family: sans-serif;
370 font-weight: bold;
371 margin-top: 0.0em;
372 margin-bottom: 0.5em;
375 div.listingblock div.content {
376 border: 1px solid silver;
377 background: #f4f4f4;
378 padding: 0.5em;
381 div.quoteblock-attribution {
382 padding-top: 0.5em;
383 text-align: right;
386 div.verseblock-content {
387 white-space: pre;
389 div.verseblock-attribution {
390 padding-top: 0.75em;
391 text-align: left;
394 div.exampleblock-content {
395 border-left: 2px solid silver;
396 padding-left: 0.5em;
399 /* IE6 sets dynamically generated links as visited. */
400 div#toc a:visited { color: blue; }
401 </style>
402 </head>
403 <body>
404 <div id="header">
405 <h1>
406 git-cvsimport(1) Manual Page
407 </h1>
408 <h2>NAME</h2>
409 <div class="sectionbody">
410 <p>git-cvsimport -
411 Salvage your data out of another SCM people love to hate
412 </p>
413 </div>
414 </div>
415 <h2 id="_synopsis">SYNOPSIS</h2>
416 <div class="sectionbody">
417 <div class="verseblock">
418 <div class="verseblock-content"><em>git cvsimport</em> [-o &lt;branch-for-HEAD&gt;] [-h] [-v] [-d &lt;CVSROOT&gt;]
419 [-A &lt;author-conv-file&gt;] [-p &lt;options-for-cvsps&gt;] [-P &lt;file&gt;]
420 [-C &lt;git_repository&gt;] [-z &lt;fuzz&gt;] [-i] [-k] [-u] [-s &lt;subst&gt;]
421 [-a] [-m] [-M &lt;regex&gt;] [-S &lt;regex&gt;] [-L &lt;commitlimit&gt;]
422 [-r &lt;remote&gt;] [-R] [&lt;CVS_module&gt;]</div>
423 <div class="verseblock-attribution">
424 </div></div>
425 </div>
426 <h2 id="_description">DESCRIPTION</h2>
427 <div class="sectionbody">
428 <div class="paragraph"><p>Imports a CVS repository into git. It will either create a new
429 repository, or incrementally import into an existing one.</p></div>
430 <div class="paragraph"><p>Splitting the CVS log into patch sets is done by <em>cvsps</em>.
431 At least version 2.1 is required.</p></div>
432 <div class="paragraph"><p><strong>WARNING:</strong> for certain situations the import leads to incorrect results.
433 Please see the section <a href="#issues">ISSUES</a> for further reference.</p></div>
434 <div class="paragraph"><p>You should <strong>never</strong> do any work of your own on the branches that are
435 created by <em>git cvsimport</em>. By default initial import will create and populate a
436 "master" branch from the CVS repository&#8217;s main branch which you&#8217;re free
437 to work with; after that, you need to <em>git merge</em> incremental imports, or
438 any CVS branches, yourself. It is advisable to specify a named remote via
439 -r to separate and protect the incoming branches.</p></div>
440 <div class="paragraph"><p>If you intend to set up a shared public repository that all developers can
441 read/write, or if you want to use <a href="git-cvsserver.html">git-cvsserver(1)</a>, then you
442 probably want to make a bare clone of the imported repository,
443 and use the clone as the shared repository.
444 See <a href="gitcvs-migration.html">gitcvs-migration(7)</a>.</p></div>
445 </div>
446 <h2 id="_options">OPTIONS</h2>
447 <div class="sectionbody">
448 <div class="dlist"><dl>
449 <dt class="hdlist1">
451 </dt>
452 <dd>
454 Verbosity: let <em>cvsimport</em> report what it is doing.
455 </p>
456 </dd>
457 <dt class="hdlist1">
458 -d &lt;CVSROOT&gt;
459 </dt>
460 <dd>
462 The root of the CVS archive. May be local (a simple path) or remote;
463 currently, only the :local:, :ext: and :pserver: access methods
464 are supported. If not given, <em>git cvsimport</em> will try to read it
465 from <tt>CVS/Root</tt>. If no such file exists, it checks for the
466 <tt>CVSROOT</tt> environment variable.
467 </p>
468 </dd>
469 <dt class="hdlist1">
470 &lt;CVS_module&gt;
471 </dt>
472 <dd>
474 The CVS module you want to import. Relative to &lt;CVSROOT&gt;.
475 If not given, <em>git cvsimport</em> tries to read it from
476 <tt>CVS/Repository</tt>.
477 </p>
478 </dd>
479 <dt class="hdlist1">
480 -C &lt;target-dir&gt;
481 </dt>
482 <dd>
484 The git repository to import to. If the directory doesn&#8217;t
485 exist, it will be created. Default is the current directory.
486 </p>
487 </dd>
488 <dt class="hdlist1">
489 -r &lt;remote&gt;
490 </dt>
491 <dd>
493 The git remote to import this CVS repository into.
494 Moves all CVS branches into remotes/&lt;remote&gt;/&lt;branch&gt;
495 akin to the way <em>git clone</em> uses <em>origin</em> by default.
496 </p>
497 </dd>
498 <dt class="hdlist1">
499 -o &lt;branch-for-HEAD&gt;
500 </dt>
501 <dd>
503 When no remote is specified (via -r) the <em>HEAD</em> branch
504 from CVS is imported to the <em>origin</em> branch within the git
505 repository, as <em>HEAD</em> already has a special meaning for git.
506 When a remote is specified the <em>HEAD</em> branch is named
507 remotes/&lt;remote&gt;/master mirroring <em>git clone</em> behaviour.
508 Use this option if you want to import into a different
509 branch.
510 </p>
511 <div class="paragraph"><p>Use <em>-o master</em> for continuing an import that was initially done by
512 the old cvs2git tool.</p></div>
513 </dd>
514 <dt class="hdlist1">
516 </dt>
517 <dd>
519 Import-only: don&#8217;t perform a checkout after importing. This option
520 ensures the working directory and index remain untouched and will
521 not create them if they do not exist.
522 </p>
523 </dd>
524 <dt class="hdlist1">
526 </dt>
527 <dd>
529 Kill keywords: will extract files with <em>-kk</em> from the CVS archive
530 to avoid noisy changesets. Highly recommended, but off by default
531 to preserve compatibility with early imported trees.
532 </p>
533 </dd>
534 <dt class="hdlist1">
536 </dt>
537 <dd>
539 Convert underscores in tag and branch names to dots.
540 </p>
541 </dd>
542 <dt class="hdlist1">
543 -s &lt;subst&gt;
544 </dt>
545 <dd>
547 Substitute the character "/" in branch names with &lt;subst&gt;
548 </p>
549 </dd>
550 <dt class="hdlist1">
551 -p &lt;options-for-cvsps&gt;
552 </dt>
553 <dd>
555 Additional options for cvsps.
556 The options <em>-u</em> and <em>-A</em> are implicit and should not be used here.
557 </p>
558 <div class="paragraph"><p>If you need to pass multiple options, separate them with a comma.</p></div>
559 </dd>
560 <dt class="hdlist1">
561 -z &lt;fuzz&gt;
562 </dt>
563 <dd>
565 Pass the timestamp fuzz factor to cvsps, in seconds. If unset,
566 cvsps defaults to 300s.
567 </p>
568 </dd>
569 <dt class="hdlist1">
570 -P &lt;cvsps-output-file&gt;
571 </dt>
572 <dd>
574 Instead of calling cvsps, read the provided cvsps output file. Useful
575 for debugging or when cvsps is being handled outside cvsimport.
576 </p>
577 </dd>
578 <dt class="hdlist1">
580 </dt>
581 <dd>
583 Attempt to detect merges based on the commit message. This option
584 will enable default regexes that try to capture the source
585 branch name from the commit message.
586 </p>
587 </dd>
588 <dt class="hdlist1">
589 -M &lt;regex&gt;
590 </dt>
591 <dd>
593 Attempt to detect merges based on the commit message with a custom
594 regex. It can be used with <em>-m</em> to enable the default regexes
595 as well. You must escape forward slashes.
596 </p>
597 <div class="paragraph"><p>The regex must capture the source branch name in $1.</p></div>
598 <div class="paragraph"><p>This option can be used several times to provide several detection regexes.</p></div>
599 </dd>
600 <dt class="hdlist1">
601 -S &lt;regex&gt;
602 </dt>
603 <dd>
605 Skip paths matching the regex.
606 </p>
607 </dd>
608 <dt class="hdlist1">
610 </dt>
611 <dd>
613 Import all commits, including recent ones. cvsimport by default
614 skips commits that have a timestamp less than 10 minutes ago.
615 </p>
616 </dd>
617 <dt class="hdlist1">
618 -L &lt;limit&gt;
619 </dt>
620 <dd>
622 Limit the number of commits imported. Workaround for cases where
623 cvsimport leaks memory.
624 </p>
625 </dd>
626 <dt class="hdlist1">
627 -A &lt;author-conv-file&gt;
628 </dt>
629 <dd>
631 CVS by default uses the Unix username when writing its
632 commit logs. Using this option and an author-conv-file
633 in this format
634 </p>
635 <div class="listingblock">
636 <div class="content">
637 <pre><tt> exon=Andreas Ericsson &lt;ae@op5.se&gt;
638 spawn=Simon Pawn &lt;spawn@frog-pond.org&gt;</tt></pre>
639 </div></div>
640 <div class="paragraph"><p><em>git cvsimport</em> will make it appear as those authors had
641 their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly
642 all along.</p></div>
643 <div class="paragraph"><p>For convenience, this data is saved to <tt>$GIT_DIR/cvs-authors</tt>
644 each time the <em>-A</em> option is provided and read from that same
645 file each time <em>git cvsimport</em> is run.</p></div>
646 <div class="paragraph"><p>It is not recommended to use this feature if you intend to
647 export changes back to CVS again later with
648 <em>git cvsexportcommit</em>.</p></div>
649 </dd>
650 <dt class="hdlist1">
652 </dt>
653 <dd>
655 Generate a <tt>$GIT_DIR/cvs-revisions</tt> file containing a mapping from CVS
656 revision numbers to newly-created Git commit IDs. The generated file
657 will contain one line for each (filename, revision) pair imported;
658 each line will look like
659 </p>
660 <div class="listingblock">
661 <div class="content">
662 <pre><tt>src/widget.c 1.1 1d862f173cdc7325b6fa6d2ae1cfd61fd1b512b7</tt></pre>
663 </div></div>
664 <div class="paragraph"><p>The revision data is appended to the file if it already exists, for use when
665 doing incremental imports.</p></div>
666 <div class="paragraph"><p>This option may be useful if you have CVS revision numbers stored in commit
667 messages, bug-tracking systems, email archives, and the like.</p></div>
668 </dd>
669 <dt class="hdlist1">
671 </dt>
672 <dd>
674 Print a short usage message and exit.
675 </p>
676 </dd>
677 </dl></div>
678 </div>
679 <h2 id="_output">OUTPUT</h2>
680 <div class="sectionbody">
681 <div class="paragraph"><p>If <em>-v</em> is specified, the script reports what it is doing.</p></div>
682 <div class="paragraph"><p>Otherwise, success is indicated the Unix way, i.e. by simply exiting with
683 a zero exit status.</p></div>
684 </div>
685 <h2 id="issues">ISSUES</h2>
686 <div class="sectionbody">
687 <div class="paragraph"><p>Problems related to timestamps:</p></div>
688 <div class="ulist"><ul>
689 <li>
691 If timestamps of commits in the CVS repository are not stable enough
692 to be used for ordering commits changes may show up in the wrong
693 order.
694 </p>
695 </li>
696 <li>
698 If any files were ever "cvs import"ed more than once (e.g., import of
699 more than one vendor release) the HEAD contains the wrong content.
700 </p>
701 </li>
702 <li>
704 If the timestamp order of different files cross the revision order
705 within the commit matching time window the order of commits may be
706 wrong.
707 </p>
708 </li>
709 </ul></div>
710 <div class="paragraph"><p>Problems related to branches:</p></div>
711 <div class="ulist"><ul>
712 <li>
714 Branches on which no commits have been made are not imported.
715 </p>
716 </li>
717 <li>
719 All files from the branching point are added to a branch even if
720 never added in CVS.
721 </p>
722 </li>
723 <li>
725 This applies to files added to the source branch <strong>after</strong> a daughter
726 branch was created: if previously no commit was made on the daughter
727 branch they will erroneously be added to the daughter branch in git.
728 </p>
729 </li>
730 </ul></div>
731 <div class="paragraph"><p>Problems related to tags:</p></div>
732 <div class="ulist"><ul>
733 <li>
735 Multiple tags on the same revision are not imported.
736 </p>
737 </li>
738 </ul></div>
739 <div class="paragraph"><p>If you suspect that any of these issues may apply to the repository you
740 want to import consider using these alternative tools which proved to be
741 more stable in practice:</p></div>
742 <div class="ulist"><ul>
743 <li>
745 cvs2git (part of cvs2svn), <tt>http://cvs2svn.tigris.org</tt>
746 </p>
747 </li>
748 <li>
750 parsecvs, <tt>http://cgit.freedesktop.org/~keithp/parsecvs</tt>
751 </p>
752 </li>
753 </ul></div>
754 </div>
755 <h2 id="_git">GIT</h2>
756 <div class="sectionbody">
757 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
758 </div>
759 <div id="footer">
760 <div id="footer-text">
761 Last updated 2011-03-15 23:30:13 UTC
762 </div>
763 </div>
764 </body>
765 </html>