Google Git
Sign in
chromium / external / gitster / git-htmldocs / fbe7486629ec9aeeb001819e3a4b9fb7b756b3e6 / . / git-fast-import.html
blob: f61958ec3963980a7e17eb3afb9d9d7f31eac74e [file] [log] [blame]
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]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" />
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]6<meta name="generator" content="AsciiDoc 8.5.2" />
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]7<title>git-fast-import(1)</title>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]8<style type="text/css">
9/* Debug borders */
10p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
11/*
12 border: 1px solid red;
13*/
14}
15
16body {
17 margin: 1em 5% 1em 5%;
18}
19
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]20a {
21 color: blue;
22 text-decoration: underline;
23}
24a:visited {
25 color: fuchsia;
26}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]27
28em {
29 font-style: italic;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]30 color: navy;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]31}
32
33strong {
34 font-weight: bold;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]35 color: #083194;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]36}
37
38tt {
39 color: navy;
40}
41
42h1, 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;
48}
49
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]50h1, h2, h3 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]51 border-bottom: 2px solid silver;
52}
53h2 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]54 padding-top: 0.5em;
55}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]56h3 {
57 float: left;
58}
59h3 + * {
60 clear: left;
61}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]62
63div.sectionbody {
64 font-family: serif;
65 margin-left: 0;
66}
67
68hr {
69 border: 1px solid silver;
70}
71
72p {
73 margin-top: 0.5em;
74 margin-bottom: 0.5em;
75}
76
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]77ul, ol, li > p {
78 margin-top: 0;
79}
80
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]81pre {
82 padding: 0;
83 margin: 0;
84}
85
86span#author {
87 color: #527bbd;
88 font-family: sans-serif;
89 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]90 font-size: 1.1em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]91}
92span#email {
93}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]94span#revnumber, span#revdate, span#revremark {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]95 font-family: sans-serif;
96}
97
98div#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;
104}
105div#footer-text {
106 float: left;
107 padding-bottom: 0.5em;
108}
109div#footer-badges {
110 float: right;
111 padding-bottom: 0.5em;
112}
113
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]114div#preamble {
115 margin-top: 1.5em;
116 margin-bottom: 1.5em;
117}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]118div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
119div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
120div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]121 margin-top: 1.0em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]122 margin-bottom: 1.5em;
123}
124div.admonitionblock {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]125 margin-top: 2.0em;
126 margin-bottom: 2.0em;
127 margin-right: 10%;
128 color: #606060;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]129}
130
131div.content { /* Block element content. */
132 padding: 0;
133}
134
135/* Block element titles. */
136div.title, caption.title {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]137 color: #527bbd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]138 font-family: sans-serif;
139 font-weight: bold;
140 text-align: left;
141 margin-top: 1.0em;
142 margin-bottom: 0.5em;
143}
144div.title + * {
145 margin-top: 0;
146}
147
148td div.title:first-child {
149 margin-top: 0.0em;
150}
151div.content div.title:first-child {
152 margin-top: 0.0em;
153}
154div.content + div.title {
155 margin-top: 0.0em;
156}
157
158div.sidebarblock > div.content {
159 background: #ffffee;
160 border: 1px solid silver;
161 padding: 0.5em;
162}
163
164div.listingblock > div.content {
165 border: 1px solid silver;
166 background: #f4f4f4;
167 padding: 0.5em;
168}
169
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]170div.quoteblock, div.verseblock {
171 padding-left: 1.0em;
172 margin-left: 1.0em;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]173 margin-right: 10%;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]174 border-left: 5px solid #dddddd;
175 color: #777777;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]176}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]177
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]178div.quoteblock > div.attribution {
179 padding-top: 0.5em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]180 text-align: right;
181}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]182
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]183div.verseblock > div.content {
184 white-space: pre;
185}
186div.verseblock > div.attribution {
187 padding-top: 0.75em;
188 text-align: left;
189}
190/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]191div.verseblock + div.attribution {
192 text-align: left;
193}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]194
195div.admonitionblock .icon {
196 vertical-align: top;
197 font-size: 1.1em;
198 font-weight: bold;
199 text-decoration: underline;
200 color: #527bbd;
201 padding-right: 0.5em;
202}
203div.admonitionblock td.content {
204 padding-left: 0.5em;
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]205 border-left: 3px solid #dddddd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]206}
207
208div.exampleblock > div.content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]209 border-left: 3px solid #dddddd;
210 padding-left: 0.5em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]211}
212
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]213div.imageblock div.content { padding-left: 0; }
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]214span.image img { border-style: none; }
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]215a.image:visited { color: white; }
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]216
217dl {
218 margin-top: 0.8em;
219 margin-bottom: 0.8em;
220}
221dt {
222 margin-top: 0.5em;
223 margin-bottom: 0;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]224 font-style: normal;
225 color: navy;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]226}
227dd > *:first-child {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]228 margin-top: 0.1em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]229}
230
231ul, ol {
232 list-style-position: outside;
233}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]234ol.arabic {
235 list-style-type: decimal;
236}
237ol.loweralpha {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]238 list-style-type: lower-alpha;
239}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]240ol.upperalpha {
241 list-style-type: upper-alpha;
242}
243ol.lowerroman {
244 list-style-type: lower-roman;
245}
246ol.upperroman {
247 list-style-type: upper-roman;
248}
249
250div.compact ul, div.compact ol,
251div.compact p, div.compact p,
252div.compact div, div.compact div {
253 margin-top: 0.1em;
254 margin-bottom: 0.1em;
255}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]256
257div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]258 border: 3px solid #527bbd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]259}
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]260thead, p.table.header {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]261 font-family: sans-serif;
262 font-weight: bold;
263}
264tfoot {
265 font-weight: bold;
266}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]267td > div.verse {
268 white-space: pre;
269}
270p.table {
271 margin-top: 0;
272}
273/* Because the table frame attribute is overriden by CSS in most browsers. */
274div.tableblock > table[frame="void"] {
275 border-style: none;
276}
277div.tableblock > table[frame="hsides"] {
278 border-left-style: none;
279 border-right-style: none;
280}
281div.tableblock > table[frame="vsides"] {
282 border-top-style: none;
283 border-bottom-style: none;
284}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]285
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]286
287div.hdlist {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]288 margin-top: 0.8em;
289 margin-bottom: 0.8em;
290}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]291div.hdlist tr {
292 padding-bottom: 15px;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]293}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]294dt.hdlist1.strong, td.hdlist1.strong {
295 font-weight: bold;
296}
297td.hdlist1 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]298 vertical-align: top;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]299 font-style: normal;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]300 padding-right: 0.8em;
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]301 color: navy;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]302}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]303td.hdlist2 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]304 vertical-align: top;
305}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]306div.hdlist.compact tr {
307 margin: 0;
308 padding-bottom: 0;
309}
310
311.comment {
312 background: yellow;
313}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]314
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]315.footnote, .footnoteref {
316 font-size: 0.8em;
317}
318
319span.footnote, span.footnoteref {
320 vertical-align: super;
321}
322
323#footnotes {
324 margin: 20px 0 20px 0;
325 padding: 7px 0 0 0;
326}
327
328#footnotes div.footnote {
329 margin: 0 0 5px 0;
330}
331
332#footnotes hr {
333 border: none;
334 border-top: 1px solid silver;
335 height: 1px;
336 text-align: left;
337 margin-left: 0;
338 width: 20%;
339 min-width: 100px;
340}
341
342
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]343@media print {
344 div#footer-badges { display: none; }
345}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]346
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]347div#toc {
348 margin-bottom: 2.5em;
349}
350
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]351div#toctitle {
352 color: #527bbd;
353 font-family: sans-serif;
354 font-size: 1.1em;
355 font-weight: bold;
356 margin-top: 1.0em;
357 margin-bottom: 0.1em;
358}
359
360div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
361 margin-top: 0;
362 margin-bottom: 0;
363}
364div.toclevel2 {
365 margin-left: 2em;
366 font-size: 0.9em;
367}
368div.toclevel3 {
369 margin-left: 4em;
370 font-size: 0.9em;
371}
372div.toclevel4 {
373 margin-left: 6em;
374 font-size: 0.9em;
375}
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]376/* Overrides for manpage documents */
377h1 {
378 padding-top: 0.5em;
379 padding-bottom: 0.5em;
380 border-top: 2px solid silver;
381 border-bottom: 2px solid silver;
382}
383h2 {
384 border-style: none;
385}
386div.sectionbody {
387 margin-left: 5%;
388}
389
390@media print {
391 div#toc { display: none; }
392}
393
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]394/* Workarounds for IE6's broken and incomplete CSS2. */
395
396div.sidebar-content {
397 background: #ffffee;
398 border: 1px solid silver;
399 padding: 0.5em;
400}
401div.sidebar-title, div.image-title {
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]402 color: #527bbd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]403 font-family: sans-serif;
404 font-weight: bold;
405 margin-top: 0.0em;
406 margin-bottom: 0.5em;
407}
408
409div.listingblock div.content {
410 border: 1px solid silver;
411 background: #f4f4f4;
412 padding: 0.5em;
413}
414
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]415div.quoteblock-attribution {
416 padding-top: 0.5em;
417 text-align: right;
418}
419
420div.verseblock-content {
421 white-space: pre;
422}
423div.verseblock-attribution {
424 padding-top: 0.75em;
425 text-align: left;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]426}
427
428div.exampleblock-content {
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]429 border-left: 3px solid #dddddd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]430 padding-left: 0.5em;
431}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]432
433/* IE6 sets dynamically generated links as visited. */
434div#toc a:visited { color: blue; }
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]435</style>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]436<script type="text/javascript">
437/*<![CDATA[*/
438window.onload = function(){asciidoc.footnotes();}
439var asciidoc = { // Namespace.
440
441/////////////////////////////////////////////////////////////////////
442// Table Of Contents generator
443/////////////////////////////////////////////////////////////////////
444
445/* Author: Mihai Bazon, September 2002
446 * http://students.infoiasi.ro/~mishoo
447 *
448 * Table Of Content generator
449 * Version: 0.4
450 *
451 * Feel free to use this script under the terms of the GNU General Public
452 * License, as long as you do not remove or alter this notice.
453 */
454
455 /* modified by Troy D. Hanson, September 2006. License: GPL */
456 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
457
458// toclevels = 1..4.
459toc: function (toclevels) {
460
461 function getText(el) {
462 var text = "";
463 for (var i = el.firstChild; i != null; i = i.nextSibling) {
464 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
465 text += i.data;
466 else if (i.firstChild != null)
467 text += getText(i);
468 }
469 return text;
470 }
471
472 function TocEntry(el, text, toclevel) {
473 this.element = el;
474 this.text = text;
475 this.toclevel = toclevel;
476 }
477
478 function tocEntries(el, toclevels) {
479 var result = new Array;
480 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
481 // Function that scans the DOM tree for header elements (the DOM2
482 // nodeIterator API would be a better technique but not supported by all
483 // browsers).
484 var iterate = function (el) {
485 for (var i = el.firstChild; i != null; i = i.nextSibling) {
486 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
487 var mo = re.exec(i.tagName);
488 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
489 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
490 }
491 iterate(i);
492 }
493 }
494 }
495 iterate(el);
496 return result;
497 }
498
499 var toc = document.getElementById("toc");
500 var entries = tocEntries(document.getElementById("content"), toclevels);
501 for (var i = 0; i < entries.length; ++i) {
502 var entry = entries[i];
503 if (entry.element.id == "")
504 entry.element.id = "_toc_" + i;
505 var a = document.createElement("a");
506 a.href = "#" + entry.element.id;
507 a.appendChild(document.createTextNode(entry.text));
508 var div = document.createElement("div");
509 div.appendChild(a);
510 div.className = "toclevel" + entry.toclevel;
511 toc.appendChild(div);
512 }
513 if (entries.length == 0)
514 toc.parentNode.removeChild(toc);
515},
516
517
518/////////////////////////////////////////////////////////////////////
519// Footnotes generator
520/////////////////////////////////////////////////////////////////////
521
522/* Based on footnote generation code from:
523 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
524 */
525
526footnotes: function () {
527 var cont = document.getElementById("content");
528 var noteholder = document.getElementById("footnotes");
529 var spans = cont.getElementsByTagName("span");
530 var refs = {};
531 var n = 0;
532 for (i=0; i<spans.length; i++) {
533 if (spans[i].className == "footnote") {
534 n++;
535 // Use [\s\S] in place of . so multi-line matches work.
536 // Because JavaScript has no s (dotall) regex flag.
537 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
538 noteholder.innerHTML +=
539 "<div class='footnote' id='_footnote_" + n + "'>" +
540 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
541 n + "</a>. " + note + "</div>";
542 spans[i].innerHTML =
543 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
544 "' title='View footnote' class='footnote'>" + n + "</a>]";
545 var id =spans[i].getAttribute("id");
546 if (id != null) refs["#"+id] = n;
547 }
548 }
549 if (n == 0)
550 noteholder.parentNode.removeChild(noteholder);
551 else {
552 // Process footnoterefs.
553 for (i=0; i<spans.length; i++) {
554 if (spans[i].className == "footnoteref") {
555 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
556 href = href.match(/#.*/)[0]; // Because IE return full URL.
557 n = refs[href];
558 spans[i].innerHTML =
559 "[<a href='#_footnote_" + n +
560 "' title='View footnote' class='footnote'>" + n + "</a>]";
561 }
562 }
563 }
564}
565
566}
567/*]]>*/
568</script>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]569</head>
570<body>
571<div id="header">
572<h1>
573git-fast-import(1) Manual Page
574</h1>
575<h2>NAME</h2>
576<div class="sectionbody">
577<p>git-fast-import -
Junio C Hamano053827f2007-02-14 07:23:58[diff] [blame]578 Backend for fast Git data importers
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]579</p>
580</div>
581</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]582<div id="content">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]583<h2 id="_synopsis">SYNOPSIS</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]584<div class="sectionbody">
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]585<div class="verseblock">
586<div class="verseblock-content">frontend | <em>git fast-import</em> [options]</div>
587<div class="verseblock-attribution">
588</div></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]589</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]590<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]591<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]592<div class="paragraph"><p>This program is usually not what the end user wants to run directly.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]593Most end users want to use one of the existing frontend programs,
594which parses a specific type of foreign source and feeds the contents
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]595stored there to <em>git fast-import</em>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]596<div class="paragraph"><p>fast-import reads a mixed command/data stream from standard input and
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]597writes one or more packfiles directly into the current repository.
598When EOF is received on standard input, fast import writes out
599updated branch and tag refs, fully updating the current repository
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]600with the newly imported data.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]601<div class="paragraph"><p>The fast-import backend itself can import into an empty repository (one that
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]602has already been initialized by <em>git init</em>) or incrementally
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]603update an existing populated repository. Whether or not incremental
604imports are supported from a particular foreign source depends on
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]605the frontend program in use.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]606</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]607<h2 id="_options">OPTIONS</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]608<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]609<div class="dlist"><dl>
610<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]611--date-format=&lt;fmt&gt;
612</dt>
613<dd>
614<p>
615 Specify the type of dates the frontend will supply to
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]616 fast-import within <tt>author</tt>, <tt>committer</tt> and <tt>tagger</tt> commands.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]617 See &#8220;Date Formats&#8221; below for details about which formats
618 are supported, and their syntax.
619</p>
620</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]621<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]622--force
623</dt>
624<dd>
625<p>
626 Force updating modified existing branches, even if doing
627 so would cause commits to be lost (as the new commit does
628 not contain the old commit).
629</p>
630</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]631<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]632--max-pack-size=&lt;n&gt;
633</dt>
634<dd>
635<p>
Junio C Hamanod3304322010-02-05 03:28:27[diff] [blame]636 Maximum size of each output packfile.
Junio C Hamano4fdccb22010-02-19 09:58:14[diff] [blame]637 The default is unlimited.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]638</p>
639</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]640<dt class="hdlist1">
Junio C Hamano5c246f22010-02-03 07:34:53[diff] [blame]641--big-file-threshold=&lt;n&gt;
642</dt>
643<dd>
644<p>
645 Maximum size of a blob that fast-import will attempt to
646 create a delta for, expressed in bytes. The default is 512m
647 (512 MiB). Some importers may wish to lower this on systems
648 with constrained memory.
649</p>
650</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]651<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]652--depth=&lt;n&gt;
653</dt>
654<dd>
655<p>
656 Maximum delta depth, for blob and tree deltification.
657 Default is 10.
658</p>
659</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]660<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]661--active-branches=&lt;n&gt;
662</dt>
663<dd>
664<p>
665 Maximum number of branches to maintain active at once.
666 See &#8220;Memory Utilization&#8221; below for details. Default is 5.
667</p>
668</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]669<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]670--export-marks=&lt;file&gt;
671</dt>
672<dd>
673<p>
674 Dumps the internal marks table to &lt;file&gt; when complete.
675 Marks are written one per line as <tt>:markid SHA-1</tt>.
676 Frontends can use this file to validate imports after they
Junio C Hamanod15328a2007-03-09 09:06:40[diff] [blame]677 have been completed, or to save the marks table across
678 incremental runs. As &lt;file&gt; is only opened and truncated
679 at checkpoint (or completion) the same path can also be
680 safely given to --import-marks.
681</p>
682</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]683<dt class="hdlist1">
Junio C Hamanod15328a2007-03-09 09:06:40[diff] [blame]684--import-marks=&lt;file&gt;
685</dt>
686<dd>
687<p>
688 Before processing any input, load the marks specified in
689 &lt;file&gt;. The input file must exist, must be readable, and
690 must use the same format as produced by --export-marks.
691 Multiple options may be supplied to import more than one
692 set of marks. If a mark is defined to different values,
693 the last file wins.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]694</p>
695</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]696<dt class="hdlist1">
Junio C Hamano23e3f532011-02-10 02:05:29[diff] [blame]697--import-marks-if-exists=&lt;file&gt;
698</dt>
699<dd>
700<p>
701 Like --import-marks but instead of erroring out, silently
702 skips the file if it does not exist.
703</p>
704</dd>
705<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]706--relative-marks
707</dt>
708<dd>
709<p>
Junio C Hamanoa0dac242011-05-06 05:10:29[diff] [blame]710 After specifying --relative-marks the paths specified
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]711 with --import-marks= and --export-marks= are relative
712 to an internal directory in the current repository.
713 In git-fast-import this means that the paths are relative
714 to the .git/info/fast-import directory. However, other
715 importers may use a different location.
716</p>
717</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]718<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]719--no-relative-marks
720</dt>
721<dd>
722<p>
723 Negates a previous --relative-marks. Allows for combining
724 relative and non-relative marks by interweaving
Junio C Hamanoa0dac242011-05-06 05:10:29[diff] [blame]725 --(no-)-relative-marks with the --(import|export)-marks=
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]726 options.
727</p>
728</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]729<dt class="hdlist1">
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]730--cat-blob-fd=&lt;fd&gt;
731</dt>
732<dd>
733<p>
Junio C Hamano4eda1362012-04-23 20:55:49[diff] [blame]734 Write responses to <tt>cat-blob</tt> and <tt>ls</tt> queries to the
735 file descriptor &lt;fd&gt; instead of <tt>stdout</tt>. Allows <tt>progress</tt>
736 output intended for the end-user to be separated from other
737 output.
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]738</p>
739</dd>
740<dt class="hdlist1">
Junio C Hamanofbc773c2011-08-02 00:09:12[diff] [blame]741--done
742</dt>
743<dd>
744<p>
745 Require a <tt>done</tt> command at the end of the stream.
746 This option might be useful for detecting errors that
747 cause the frontend to terminate before it has started to
748 write a stream.
749</p>
750</dd>
751<dt class="hdlist1">
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]752--export-pack-edges=&lt;file&gt;
753</dt>
754<dd>
755<p>
756 After creating a packfile, print a line of data to
757 &lt;file&gt; listing the filename of the packfile and the last
758 commit on each branch that was written to that packfile.
759 This information may be useful after importing projects
760 whose total object set exceeds the 4 GiB packfile limit,
761 as these commits can be used as edge points during calls
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]762 to <em>git pack-objects</em>.
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]763</p>
764</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]765<dt class="hdlist1">
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]766--quiet
767</dt>
768<dd>
769<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]770 Disable all non-fatal output, making fast-import silent when it
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]771 is successful. This option disables the output shown by
772 --stats.
773</p>
774</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]775<dt class="hdlist1">
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]776--stats
777</dt>
778<dd>
779<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]780 Display some basic statistics about the objects fast-import has
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]781 created, the packfiles they were stored into, and the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]782 memory used by fast-import during this run. Showing this output
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]783 is currently the default, but can be disabled with --quiet.
784</p>
785</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]786</dl></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]787</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]788<h2 id="_performance">Performance</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]789<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]790<div class="paragraph"><p>The design of fast-import allows it to import large projects in a minimum
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]791amount of memory usage and processing time. Assuming the frontend
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]792is able to keep up with fast-import and feed it a constant stream of data,
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]793import times for projects holding 10+ years of history and containing
794100,000+ individual commits are generally completed in just 1-2
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]795hours on quite modest (~$2,000 USD) hardware.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]796<div class="paragraph"><p>Most bottlenecks appear to be in foreign source data access (the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]797source just cannot extract revisions fast enough) or disk IO (fast-import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]798writes as fast as the disk will take the data). Imports will run
799faster if the source data is stored on a different drive than the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]800destination Git repository (due to less IO contention).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]801</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]802<h2 id="_development_cost">Development Cost</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]803<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]804<div class="paragraph"><p>A typical frontend for fast-import tends to weigh in at approximately 200
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]805lines of Perl/Python/Ruby code. Most developers have been able to
806create working importers in just a couple of hours, even though it
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]807is their first exposure to fast-import, and sometimes even to Git. This is
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]808an ideal situation, given that most conversion tools are throw-away
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]809(use once, and never look back).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]810</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]811<h2 id="_parallel_operation">Parallel Operation</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]812<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]813<div class="paragraph"><p>Like <em>git push</em> or <em>git fetch</em>, imports handled by fast-import are safe to
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]814run alongside parallel <tt>git repack -a -d</tt> or <tt>git gc</tt> invocations,
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]815or any other Git operation (including <em>git prune</em>, as loose objects
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]816are never used by fast-import).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]817<div class="paragraph"><p>fast-import does not lock the branch or tag refs it is actively importing.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]818After the import, during its ref update phase, fast-import tests each
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]819existing branch ref to verify the update will be a fast-forward
820update (the commit stored in the ref is contained in the new
821history of the commit to be written). If the update is not a
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]822fast-forward update, fast-import will skip updating that ref and instead
823prints a warning message. fast-import will always attempt to update all
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]824branch refs, and does not stop on the first failure.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]825<div class="paragraph"><p>Branch updates can be forced with --force, but it&#8217;s recommended that
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]826this only be used on an otherwise quiet repository. Using --force
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]827is not necessary for an initial import into an empty repository.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]828</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]829<h2 id="_technical_discussion">Technical Discussion</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]830<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]831<div class="paragraph"><p>fast-import tracks a set of branches in memory. Any branch can be created
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]832or modified at any point during the import process by sending a
833<tt>commit</tt> command on the input stream. This design allows a frontend
834program to process an unlimited number of branches simultaneously,
835generating commits in the order they are available from the source
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]836data. It also simplifies the frontend programs considerably.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]837<div class="paragraph"><p>fast-import does not use or alter the current working directory, or any
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]838file within it. (It does however update the current Git repository,
839as referenced by <tt>GIT_DIR</tt>.) Therefore an import frontend may use
840the working directory for its own purposes, such as extracting file
841revisions from the foreign source. This ignorance of the working
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]842directory also allows fast-import to run very quickly, as it does not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]843need to perform any costly file update operations when switching
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]844between branches.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]845</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]846<h2 id="_input_format">Input Format</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]847<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]848<div class="paragraph"><p>With the exception of raw file data (which Git does not interpret)
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]849the fast-import input format is text (ASCII) based. This text based
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]850format simplifies development and debugging of frontend programs,
851especially when a higher level language such as Perl, Python or
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]852Ruby is being used.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]853<div class="paragraph"><p>fast-import is very strict about its input. Where we say SP below we mean
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]854<strong>exactly</strong> one space. Likewise LF means one (and only one) linefeed
855and HT one (and only one) horizontal tab.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]856Supplying additional whitespace characters will cause unexpected
857results, such as branch names or file names with leading or trailing
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]858spaces in their name, or early termination of fast-import when it encounters
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]859unexpected input.</p></div>
860<h3 id="_stream_comments">Stream Comments</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]861<div class="paragraph"><p>To aid in debugging frontends fast-import ignores any line that
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]862begins with <tt>#</tt> (ASCII pound/hash) up to and including the line
863ending <tt>LF</tt>. A comment line may contain any sequence of bytes
864that does not contain an LF and therefore may be used to include
865any detailed debugging information that might be specific to the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]866frontend and useful when inspecting a fast-import data stream.</p></div>
867<h3 id="_date_formats">Date Formats</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]868<div class="paragraph"><p>The following date formats are supported. A frontend should select
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]869the format it will use for this import by passing the format name
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]870in the --date-format=&lt;fmt&gt; command line option.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]871<div class="dlist"><dl>
872<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]873<tt>raw</tt>
874</dt>
875<dd>
876<p>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]877 This is the Git native format and is <tt>&lt;time&gt; SP &lt;offutc&gt;</tt>.
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]878 It is also fast-import&#8217;s default format, if --date-format was
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]879 not specified.
880</p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]881<div class="paragraph"><p>The time of the event is specified by <tt>&lt;time&gt;</tt> as the number of
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]882seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]883written as an ASCII decimal integer.</p></div>
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]884<div class="paragraph"><p>The local offset is specified by &#8216;&lt;offutc&gt;` as a positive or negative
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]885offset from UTC. For example EST (which is 5 hours behind UTC)
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]886would be expressed in <tt>&lt;tz&gt;</tt> by <tt>`-0500'' while UTC is `</tt>+0000&#8217;'.
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]887The local offset does not affect <tt>&lt;time&gt;</tt>; it is used only as an
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]888advisement to help formatting routines display the timestamp.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]889<div class="paragraph"><p>If the local offset is not available in the source material, use
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]890&#8220;+0000&#8221;, or the most common local offset. For example many
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]891organizations have a CVS repository which has only ever been accessed
892by users who are located in the same location and timezone. In this
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]893case a reasonable offset from UTC could be assumed.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]894<div class="paragraph"><p>Unlike the <tt>rfc2822</tt> format, this format is very strict. Any
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]895variation in formatting will cause fast-import to reject the value.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]896</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]897<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]898<tt>rfc2822</tt>
899</dt>
900<dd>
901<p>
902 This is the standard email format as described by RFC 2822.
903</p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]904<div class="paragraph"><p>An example value is &#8220;Tue Feb 6 11:22:18 2007 -0500&#8221;. The Git
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]905parser is accurate, but a little on the lenient side. It is the
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]906same parser used by <em>git am</em> when applying patches
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]907received from email.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]908<div class="paragraph"><p>Some malformed strings may be accepted as valid dates. In some of
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]909these cases Git will still be able to obtain the correct date from
910the malformed string. There are also some types of malformed
911strings which Git will parse wrong, and yet consider valid.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]912Seriously malformed strings will be rejected.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]913<div class="paragraph"><p>Unlike the <tt>raw</tt> format above, the timezone/UTC offset information
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]914contained in an RFC 2822 date string is used to adjust the date
915value to UTC prior to storage. Therefore it is important that
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]916this information be as accurate as possible.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]917<div class="paragraph"><p>If the source material uses RFC 2822 style dates,
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]918the frontend should let fast-import handle the parsing and conversion
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]919(rather than attempting to do it itself) as the Git parser has
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]920been well tested in the wild.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]921<div class="paragraph"><p>Frontends should prefer the <tt>raw</tt> format if the source material
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]922already uses UNIX-epoch format, can be coaxed to give dates in that
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]923format, or its format is easily convertible to it, as there is no
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]924ambiguity in parsing.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]925</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]926<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]927<tt>now</tt>
928</dt>
929<dd>
930<p>
931 Always use the current time and timezone. The literal
932 <tt>now</tt> must always be supplied for <tt>&lt;when&gt;</tt>.
933</p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]934<div class="paragraph"><p>This is a toy format. The current time and timezone of this system
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]935is always copied into the identity string at the time it is being
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]936created by fast-import. There is no way to specify a different time or
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]937timezone.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]938<div class="paragraph"><p>This particular format is supplied as it&#8217;s short to implement and
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]939may be useful to a process that wants to create a new commit
940right now, without needing to use a working directory or
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]941<em>git update-index</em>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]942<div class="paragraph"><p>If separate <tt>author</tt> and <tt>committer</tt> commands are used in a <tt>commit</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]943the timestamps may not match, as the system clock will be polled
944twice (once for each command). The only way to ensure that both
945author and committer identity information has the same timestamp
946is to omit <tt>author</tt> (thus copying from <tt>committer</tt>) or to use a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]947date format other than <tt>now</tt>.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]948</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]949</dl></div>
950<h3 id="_commands">Commands</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]951<div class="paragraph"><p>fast-import accepts several commands to update the current repository
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]952and control the current import process. More detailed discussion
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]953(with examples) of each command follows later.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]954<div class="dlist"><dl>
955<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]956<tt>commit</tt>
957</dt>
958<dd>
959<p>
960 Creates a new branch or updates an existing branch by
961 creating a new commit and updating the branch to point at
962 the newly created commit.
963</p>
964</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]965<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]966<tt>tag</tt>
967</dt>
968<dd>
969<p>
970 Creates an annotated tag object from an existing commit or
971 branch. Lightweight tags are not supported by this command,
972 as they are not recommended for recording meaningful points
973 in time.
974</p>
975</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]976<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]977<tt>reset</tt>
978</dt>
979<dd>
980<p>
981 Reset an existing branch (or a new branch) to a specific
982 revision. This command must be used to change a branch to
983 a specific revision without making a commit on it.
984</p>
985</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]986<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]987<tt>blob</tt>
988</dt>
989<dd>
990<p>
991 Convert raw file data into a blob, for future use in a
992 <tt>commit</tt> command. This command is optional and is not
993 needed to perform an import.
994</p>
995</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]996<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]997<tt>checkpoint</tt>
998</dt>
999<dd>
1000<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1001 Forces fast-import to close the current packfile, generate its
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1002 unique SHA-1 checksum and index, and start a new packfile.
1003 This command is optional and is not needed to perform
1004 an import.
1005</p>
1006</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1007<dt class="hdlist1">
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1008<tt>progress</tt>
1009</dt>
1010<dd>
1011<p>
1012 Causes fast-import to echo the entire line to its own
1013 standard output. This command is optional and is not needed
1014 to perform an import.
1015</p>
1016</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1017<dt class="hdlist1">
Junio C Hamanofbc773c2011-08-02 00:09:12[diff] [blame]1018<tt>done</tt>
1019</dt>
1020<dd>
1021<p>
1022 Marks the end of the stream. This command is optional
1023 unless the <tt>done</tt> feature was requested using the
1024 <tt>--done</tt> command line option or <tt>feature done</tt> command.
1025</p>
1026</dd>
1027<dt class="hdlist1">
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1028<tt>cat-blob</tt>
1029</dt>
1030<dd>
1031<p>
1032 Causes fast-import to print a blob in <em>cat-file --batch</em>
1033 format to the file descriptor set with <tt>--cat-blob-fd</tt> or
1034 <tt>stdout</tt> if unspecified.
1035</p>
1036</dd>
1037<dt class="hdlist1">
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]1038<tt>ls</tt>
1039</dt>
1040<dd>
1041<p>
1042 Causes fast-import to print a line describing a directory
1043 entry in <em>ls-tree</em> format to the file descriptor set with
1044 <tt>--cat-blob-fd</tt> or <tt>stdout</tt> if unspecified.
1045</p>
1046</dd>
1047<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1048<tt>feature</tt>
1049</dt>
1050<dd>
1051<p>
1052 Require that fast-import supports the specified feature, or
1053 abort if it does not.
1054</p>
1055</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1056<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1057<tt>option</tt>
1058</dt>
1059<dd>
1060<p>
1061 Specify any of the options listed under OPTIONS that do not
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1062 change stream semantic to suit the frontend&#8217;s needs. This
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1063 command is optional and is not needed to perform an import.
1064</p>
1065</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1066</dl></div>
1067<h3 id="_tt_commit_tt"><tt>commit</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1068<div class="paragraph"><p>Create or update a branch with a new commit, recording one logical
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1069change to the project.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1070<div class="literalblock">
1071<div class="content">
1072<pre><tt> 'commit' SP &lt;ref&gt; LF
1073 mark?
Junio C Hamano6d325df2010-01-01 00:02:47[diff] [blame]1074 ('author' (SP &lt;name&gt;)? SP LT &lt;email&gt; GT SP &lt;when&gt; LF)?
1075 'committer' (SP &lt;name&gt;)? SP LT &lt;email&gt; GT SP &lt;when&gt; LF
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1076 data
1077 ('from' SP &lt;committish&gt; LF)?
1078 ('merge' SP &lt;committish&gt; LF)?
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1079 (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1080 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1081</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1082<div class="paragraph"><p>where <tt>&lt;ref&gt;</tt> is the name of the branch to make the commit on.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1083Typically branch names are prefixed with <tt>refs/heads/</tt> in
1084Git, so importing the CVS branch symbol <tt>RELENG-1_0</tt> would use
1085<tt>refs/heads/RELENG-1_0</tt> for the value of <tt>&lt;ref&gt;</tt>. The value of
1086<tt>&lt;ref&gt;</tt> must be a valid refname in Git. As <tt>LF</tt> is not valid in
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1087a Git refname, no quoting or escaping syntax is supported here.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1088<div class="paragraph"><p>A <tt>mark</tt> command may optionally appear, requesting fast-import to save a
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1089reference to the newly created commit for future use by the frontend
1090(see below for format). It is very common for frontends to mark
1091every commit they create, thereby allowing future branch creation
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1092from any imported commit.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1093<div class="paragraph"><p>The <tt>data</tt> command following <tt>committer</tt> must supply the commit
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1094message (see below for <tt>data</tt> command syntax). To import an empty
1095commit message use a 0 length data. Commit messages are free-form
1096and are not interpreted by Git. Currently they must be encoded in
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1097UTF-8, as fast-import does not permit other encodings to be specified.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1098<div class="paragraph"><p>Zero or more <tt>filemodify</tt>, <tt>filedelete</tt>, <tt>filecopy</tt>, <tt>filerename</tt>,
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1099<tt>filedeleteall</tt> and <tt>notemodify</tt> commands
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1100may be included to update the contents of the branch prior to
1101creating the commit. These commands may be supplied in any order.
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1102However it is recommended that a <tt>filedeleteall</tt> command precede
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1103all <tt>filemodify</tt>, <tt>filecopy</tt>, <tt>filerename</tt> and <tt>notemodify</tt> commands in
1104the same commit, as <tt>filedeleteall</tt> wipes the branch clean (see below).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1105<div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1106<h4 id="_tt_author_tt"><tt>author</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1107<div class="paragraph"><p>An <tt>author</tt> command may optionally appear, if the author information
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1108might differ from the committer information. If <tt>author</tt> is omitted
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1109then fast-import will automatically use the committer&#8217;s information for
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1110the author portion of the commit. See below for a description of
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1111the fields in <tt>author</tt>, as they are identical to <tt>committer</tt>.</p></div>
1112<h4 id="_tt_committer_tt"><tt>committer</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1113<div class="paragraph"><p>The <tt>committer</tt> command indicates who made this commit, and when
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1114they made it.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1115<div class="paragraph"><p>Here <tt>&lt;name&gt;</tt> is the person&#8217;s display name (for example
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]1116<tt>`Com M Itter'') and `&lt;email&gt;</tt> is the person&#8217;s email address
1117(<tt>`cm@example.com''). `LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1118and greater-than (\x3e) symbols. These are required to delimit
1119the email address from the other fields in the line. Note that
Junio C Hamano6e41cb32011-08-29 07:12:49[diff] [blame]1120<tt>&lt;name&gt;</tt> and <tt>&lt;email&gt;</tt> are free-form and may contain any sequence
1121of bytes, except <tt>LT</tt>, <tt>GT</tt> and <tt>LF</tt>. <tt>&lt;name&gt;</tt> is typically UTF-8 encoded.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1122<div class="paragraph"><p>The time of the change is specified by <tt>&lt;when&gt;</tt> using the date format
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1123that was selected by the --date-format=&lt;fmt&gt; command line option.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1124See &#8220;Date Formats&#8221; above for the set of supported formats, and
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1125their syntax.</p></div>
1126<h4 id="_tt_from_tt"><tt>from</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1127<div class="paragraph"><p>The <tt>from</tt> command is used to specify the commit to initialize
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]1128this branch from. This revision will be the first ancestor of the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1129new commit.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1130<div class="paragraph"><p>Omitting the <tt>from</tt> command in the first commit of a new branch
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]1131will cause fast-import to create that commit with no ancestor. This
1132tends to be desired only for the initial commit of a project.
Junio C Hamano25c0b702008-03-23 09:41:37[diff] [blame]1133If the frontend creates all files from scratch when making a new
1134branch, a <tt>merge</tt> command may be used instead of <tt>from</tt> to start
1135the commit with an empty tree.
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]1136Omitting the <tt>from</tt> command on existing branches is usually desired,
1137as the current commit on that branch is automatically assumed to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1138be the first ancestor of the new commit.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1139<div class="paragraph"><p>As <tt>LF</tt> is not valid in a Git refname or SHA-1 expression, no
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1140quoting or escaping syntax is supported within <tt>&lt;committish&gt;</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1141<div class="paragraph"><p>Here <tt>&lt;committish&gt;</tt> is any of the following:</p></div>
1142<div class="ulist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1143<li>
1144<p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1145The name of an existing branch already in fast-import&#8217;s internal branch
1146 table. If fast-import doesn&#8217;t know the name, it&#8217;s treated as a SHA-1
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1147 expression.
1148</p>
1149</li>
1150<li>
1151<p>
1152A mark reference, <tt>:&lt;idnum&gt;</tt>, where <tt>&lt;idnum&gt;</tt> is the mark number.
1153</p>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1154<div class="paragraph"><p>The reason fast-import uses <tt>:</tt> to denote a mark reference is this character
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1155is not legal in a Git branch name. The leading <tt>:</tt> makes it easy
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1156to distinguish between the mark 42 (<tt>:42</tt>) and the branch 42 (<tt>42</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1157or <tt>refs/heads/42</tt>), or an abbreviated SHA-1 which happened to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1158consist only of base-10 digits.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1159<div class="paragraph"><p>Marks must be declared (via <tt>mark</tt>) before they can be used.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1160</li>
1161<li>
1162<p>
1163A complete 40 byte or abbreviated commit SHA-1 in hex.
1164</p>
1165</li>
1166<li>
1167<p>
1168Any valid Git SHA-1 expression that resolves to a commit. See
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]1169 &#8220;SPECIFYING REVISIONS&#8221; in <a href="gitrevisions.html">gitrevisions(7)</a> for details.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1170</p>
1171</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1172</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1173<div class="paragraph"><p>The special case of restarting an incremental import from the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1174current branch value should be written as:</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1175<div class="listingblock">
1176<div class="content">
1177<pre><tt> from refs/heads/branch^0</tt></pre>
1178</div></div>
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]1179<div class="paragraph"><p>The <tt>^0</tt> suffix is necessary as fast-import does not permit a branch to
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1180start from itself, and the branch is created in memory before the
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]1181<tt>from</tt> command is even read from the input. Adding <tt>^0</tt> will force
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1182fast-import to resolve the commit through Git&#8217;s revision parsing library,
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1183rather than its internal branch table, thereby loading in the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1184existing value of the branch.</p></div>
1185<h4 id="_tt_merge_tt"><tt>merge</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1186<div class="paragraph"><p>Includes one additional ancestor commit. If the <tt>from</tt> command is
Junio C Hamano25c0b702008-03-23 09:41:37[diff] [blame]1187omitted when creating a new branch, the first <tt>merge</tt> commit will be
1188the first ancestor of the current commit, and the branch will start
1189out with no files. An unlimited number of <tt>merge</tt> commands per
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1190commit are permitted by fast-import, thereby establishing an n-way merge.
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1191However Git&#8217;s other tools never create commits with more than 15
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1192additional ancestors (forming a 16-way merge). For this reason
1193it is suggested that frontends do not use more than 15 <tt>merge</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1194commands per commit; 16, if starting a new, empty branch.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1195<div class="paragraph"><p>Here <tt>&lt;committish&gt;</tt> is any of the commit specification expressions
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1196also accepted by <tt>from</tt> (see above).</p></div>
1197<h4 id="_tt_filemodify_tt"><tt>filemodify</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1198<div class="paragraph"><p>Included in a <tt>commit</tt> command to add a new file or change the
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1199content of an existing file. This command has two different means
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1200of specifying the content of the file.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1201<div class="dlist"><dl>
1202<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1203External data format
1204</dt>
1205<dd>
1206<p>
1207 The data content for the file was already supplied by a prior
1208 <tt>blob</tt> command. The frontend just needs to connect it.
1209</p>
1210<div class="literalblock">
1211<div class="content">
1212<pre><tt> 'M' SP &lt;mode&gt; SP &lt;dataref&gt; SP &lt;path&gt; LF</tt></pre>
1213</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1214<div class="paragraph"><p>Here usually <tt>&lt;dataref&gt;</tt> must be either a mark reference (<tt>:&lt;idnum&gt;</tt>)
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1215set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an
Junio C Hamano619596a2010-08-18 22:15:35[diff] [blame]1216existing Git blob object. If <tt>&lt;mode&gt;</tt> is <tt>040000</tt>` then
1217<tt>&lt;dataref&gt;</tt> must be the full 40-byte SHA-1 of an existing
1218Git tree object or a mark reference set with <tt>--import-marks</tt>.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1219</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1220<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1221Inline data format
1222</dt>
1223<dd>
1224<p>
1225 The data content for the file has not been supplied yet.
1226 The frontend wants to supply it as part of this modify
1227 command.
1228</p>
1229<div class="literalblock">
1230<div class="content">
1231<pre><tt> 'M' SP &lt;mode&gt; SP 'inline' SP &lt;path&gt; LF
1232 data</tt></pre>
1233</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1234<div class="paragraph"><p>See below for a detailed description of the <tt>data</tt> command.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1235</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1236</dl></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1237<div class="paragraph"><p>In both formats <tt>&lt;mode&gt;</tt> is the type of file entry, specified
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1238in octal. Git only supports the following modes:</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1239<div class="ulist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1240<li>
1241<p>
1242<tt>100644</tt> or <tt>644</tt>: A normal (not-executable) file. The majority
1243 of files in most projects use this mode. If in doubt, this is
1244 what you want.
1245</p>
1246</li>
1247<li>
1248<p>
1249<tt>100755</tt> or <tt>755</tt>: A normal, but executable, file.
1250</p>
1251</li>
1252<li>
1253<p>
1254<tt>120000</tt>: A symlink, the content of the file will be the link target.
1255</p>
1256</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]1257<li>
1258<p>
1259<tt>160000</tt>: A gitlink, SHA-1 of the object refers to a commit in
1260 another repository. Git links can only be specified by SHA or through
1261 a commit mark. They are used to implement submodules.
1262</p>
1263</li>
Junio C Hamano619596a2010-08-18 22:15:35[diff] [blame]1264<li>
1265<p>
1266<tt>040000</tt>: A subdirectory. Subdirectories can only be specified by
1267 SHA or through a tree mark set with <tt>--import-marks</tt>.
1268</p>
1269</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1270</ul></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1271<div class="paragraph"><p>In both formats <tt>&lt;path&gt;</tt> is the complete path of the file to be added
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1272(if not already existing) or modified (if already existing).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1273<div class="paragraph"><p>A <tt>&lt;path&gt;</tt> string must use UNIX-style directory separators (forward
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1274slash <tt>/</tt>), may contain any byte other than <tt>LF</tt>, and must not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1275start with double quote (<tt>"</tt>).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1276<div class="paragraph"><p>If an <tt>LF</tt> or double quote must be encoded into <tt>&lt;path&gt;</tt> shell-style
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1277quoting should be used, e.g. <tt>"path/with\n and \" in it"</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1278<div class="paragraph"><p>The value of <tt>&lt;path&gt;</tt> must be in canonical form. That is it must not:</p></div>
1279<div class="ulist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1280<li>
1281<p>
1282contain an empty directory component (e.g. <tt>foo//bar</tt> is invalid),
1283</p>
1284</li>
1285<li>
1286<p>
Junio C Hamanoc51fede2007-03-12 07:29:20[diff] [blame]1287end with a directory separator (e.g. <tt>foo/</tt> is invalid),
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1288</p>
1289</li>
1290<li>
1291<p>
Junio C Hamanoc51fede2007-03-12 07:29:20[diff] [blame]1292start with a directory separator (e.g. <tt>/foo</tt> is invalid),
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1293</p>
1294</li>
1295<li>
1296<p>
1297contain the special component <tt>.</tt> or <tt>..</tt> (e.g. <tt>foo/./bar</tt> and
1298 <tt>foo/../bar</tt> are invalid).
1299</p>
1300</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1301</ul></div>
Junio C Hamanoe089c4e2011-01-19 22:34:12[diff] [blame]1302<div class="paragraph"><p>The root of the tree can be represented by an empty string as <tt>&lt;path&gt;</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1303<div class="paragraph"><p>It is recommended that <tt>&lt;path&gt;</tt> always be encoded using UTF-8.</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1304<h4 id="_tt_filedelete_tt"><tt>filedelete</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1305<div class="paragraph"><p>Included in a <tt>commit</tt> command to remove a file or recursively
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1306delete an entire directory from the branch. If the file or directory
1307removal makes its parent directory empty, the parent directory will
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1308be automatically removed too. This cascades up the tree until the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1309first non-empty directory or the root is reached.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1310<div class="literalblock">
1311<div class="content">
1312<pre><tt> 'D' SP &lt;path&gt; LF</tt></pre>
1313</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1314<div class="paragraph"><p>here <tt>&lt;path&gt;</tt> is the complete path of the file or subdirectory to
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1315be removed from the branch.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1316See <tt>filemodify</tt> above for a detailed description of <tt>&lt;path&gt;</tt>.</p></div>
1317<h4 id="_tt_filecopy_tt"><tt>filecopy</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1318<div class="paragraph"><p>Recursively copies an existing file or subdirectory to a different
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]1319location within the branch. The existing file or directory must
1320exist. If the destination exists it will be completely replaced
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1321by the content copied from the source.</p></div>
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]1322<div class="literalblock">
1323<div class="content">
1324<pre><tt> 'C' SP &lt;path&gt; SP &lt;path&gt; LF</tt></pre>
1325</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1326<div class="paragraph"><p>here the first <tt>&lt;path&gt;</tt> is the source location and the second
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]1327<tt>&lt;path&gt;</tt> is the destination. See <tt>filemodify</tt> above for a detailed
1328description of what <tt>&lt;path&gt;</tt> may look like. To use a source path
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1329that contains SP the path must be quoted.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1330<div class="paragraph"><p>A <tt>filecopy</tt> command takes effect immediately. Once the source
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]1331location has been copied to the destination any future commands
1332applied to the source location will not impact the destination of
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1333the copy.</p></div>
1334<h4 id="_tt_filerename_tt"><tt>filerename</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1335<div class="paragraph"><p>Renames an existing file or subdirectory to a different location
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1336within the branch. The existing file or directory must exist. If
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1337the destination exists it will be replaced by the source directory.</p></div>
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1338<div class="literalblock">
1339<div class="content">
1340<pre><tt> 'R' SP &lt;path&gt; SP &lt;path&gt; LF</tt></pre>
1341</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1342<div class="paragraph"><p>here the first <tt>&lt;path&gt;</tt> is the source location and the second
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1343<tt>&lt;path&gt;</tt> is the destination. See <tt>filemodify</tt> above for a detailed
1344description of what <tt>&lt;path&gt;</tt> may look like. To use a source path
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1345that contains SP the path must be quoted.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1346<div class="paragraph"><p>A <tt>filerename</tt> command takes effect immediately. Once the source
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]1347location has been renamed to the destination any future commands
1348applied to the source location will create new files there and not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1349impact the destination of the rename.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1350<div class="paragraph"><p>Note that a <tt>filerename</tt> is the same as a <tt>filecopy</tt> followed by a
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]1351<tt>filedelete</tt> of the source location. There is a slight performance
1352advantage to using <tt>filerename</tt>, but the advantage is so small
1353that it is never worth trying to convert a delete/add pair in
1354source material into a rename for fast-import. This <tt>filerename</tt>
1355command is provided just to simplify frontends that already have
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1356rename information and don&#8217;t want bother with decomposing it into a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1357<tt>filecopy</tt> followed by a <tt>filedelete</tt>.</p></div>
1358<h4 id="_tt_filedeleteall_tt"><tt>filedeleteall</tt></h4>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1359<div class="paragraph"><p>Included in a <tt>commit</tt> command to remove all files (and also all
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1360directories) from the branch. This command resets the internal
1361branch structure to have no files in it, allowing the frontend
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1362to subsequently add all interesting files from scratch.</p></div>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1363<div class="literalblock">
1364<div class="content">
1365<pre><tt> 'deleteall' LF</tt></pre>
1366</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1367<div class="paragraph"><p>This command is extremely useful if the frontend does not know
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1368(or does not care to know) what files are currently on the branch,
1369and therefore cannot generate the proper <tt>filedelete</tt> commands to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1370update the content.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1371<div class="paragraph"><p>Issuing a <tt>filedeleteall</tt> followed by the needed <tt>filemodify</tt>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1372commands to set the correct content will produce the same results
1373as sending only the needed <tt>filemodify</tt> and <tt>filedelete</tt> commands.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1374The <tt>filedeleteall</tt> approach may however require fast-import to use slightly
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1375more memory per active branch (less than 1 MiB for even most large
1376projects); so frontends that can easily obtain only the affected
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1377paths for a commit are encouraged to do so.</p></div>
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1378<h4 id="_tt_notemodify_tt"><tt>notemodify</tt></h4>
Junio C Hamano15567bc2011-07-23 00:51:59[diff] [blame]1379<div class="paragraph"><p>Included in a <tt>commit</tt> <tt>&lt;notes_ref&gt;</tt> command to add a new note
1380annotating a <tt>&lt;committish&gt;</tt> or change this annotation contents.
1381Internally it is similar to filemodify 100644 on <tt>&lt;committish&gt;</tt>
1382path (maybe split into subdirectories). It&#8217;s not advised to
1383use any other commands to write to the <tt>&lt;notes_ref&gt;</tt> tree except
1384<tt>filedeleteall</tt> to delete all existing notes in this tree.
1385This command has two different means of specifying the content
1386of the note.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1387<div class="dlist"><dl>
1388<dt class="hdlist1">
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1389External data format
1390</dt>
1391<dd>
1392<p>
1393 The data content for the note was already supplied by a prior
1394 <tt>blob</tt> command. The frontend just needs to connect it to the
1395 commit that is to be annotated.
1396</p>
1397<div class="literalblock">
1398<div class="content">
1399<pre><tt> 'N' SP &lt;dataref&gt; SP &lt;committish&gt; LF</tt></pre>
1400</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1401<div class="paragraph"><p>Here <tt>&lt;dataref&gt;</tt> can be either a mark reference (<tt>:&lt;idnum&gt;</tt>)
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1402set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an
1403existing Git blob object.</p></div>
1404</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1405<dt class="hdlist1">
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1406Inline data format
1407</dt>
1408<dd>
1409<p>
1410 The data content for the note has not been supplied yet.
1411 The frontend wants to supply it as part of this modify
1412 command.
1413</p>
1414<div class="literalblock">
1415<div class="content">
1416<pre><tt> 'N' SP 'inline' SP &lt;committish&gt; LF
1417 data</tt></pre>
1418</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1419<div class="paragraph"><p>See below for a detailed description of the <tt>data</tt> command.</p></div>
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1420</dd>
1421</dl></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1422<div class="paragraph"><p>In both formats <tt>&lt;committish&gt;</tt> is any of the commit specification
Junio C Hamano3b70d3c2009-11-21 17:37:37[diff] [blame]1423expressions also accepted by <tt>from</tt> (see above).</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1424<h3 id="_tt_mark_tt"><tt>mark</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1425<div class="paragraph"><p>Arranges for fast-import to save a reference to the current object, allowing
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1426the frontend to recall this object at a future point in time, without
1427knowing its SHA-1. Here the current object is the object creation
1428command the <tt>mark</tt> command appears within. This can be <tt>commit</tt>,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1429<tt>tag</tt>, and <tt>blob</tt>, but <tt>commit</tt> is the most common usage.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1430<div class="literalblock">
1431<div class="content">
1432<pre><tt> 'mark' SP ':' &lt;idnum&gt; LF</tt></pre>
1433</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1434<div class="paragraph"><p>where <tt>&lt;idnum&gt;</tt> is the number assigned by the frontend to this mark.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1435The value of <tt>&lt;idnum&gt;</tt> is expressed as an ASCII decimal integer.
1436The value 0 is reserved and cannot be used as
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1437a mark. Only values greater than or equal to 1 may be used as marks.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1438<div class="paragraph"><p>New marks are created automatically. Existing marks can be moved
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1439to another object simply by reusing the same <tt>&lt;idnum&gt;</tt> in another
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1440<tt>mark</tt> command.</p></div>
1441<h3 id="_tt_tag_tt"><tt>tag</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1442<div class="paragraph"><p>Creates an annotated tag referring to a specific commit. To create
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1443lightweight (non-annotated) tags see the <tt>reset</tt> command below.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1444<div class="literalblock">
1445<div class="content">
1446<pre><tt> 'tag' SP &lt;name&gt; LF
1447 'from' SP &lt;committish&gt; LF
Junio C Hamano6d325df2010-01-01 00:02:47[diff] [blame]1448 'tagger' (SP &lt;name&gt;)? SP LT &lt;email&gt; GT SP &lt;when&gt; LF
Junio C Hamanoea5dae62007-05-10 23:25:08[diff] [blame]1449 data</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1450</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1451<div class="paragraph"><p>where <tt>&lt;name&gt;</tt> is the name of the tag to create.</p></div>
1452<div class="paragraph"><p>Tag names are automatically prefixed with <tt>refs/tags/</tt> when stored
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1453in Git, so importing the CVS branch symbol <tt>RELENG-1_0-FINAL</tt> would
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1454use just <tt>RELENG-1_0-FINAL</tt> for <tt>&lt;name&gt;</tt>, and fast-import will write the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1455corresponding ref as <tt>refs/tags/RELENG-1_0-FINAL</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1456<div class="paragraph"><p>The value of <tt>&lt;name&gt;</tt> must be a valid refname in Git and therefore
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1457may contain forward slashes. As <tt>LF</tt> is not valid in a Git refname,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1458no quoting or escaping syntax is supported here.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1459<div class="paragraph"><p>The <tt>from</tt> command is the same as in the <tt>commit</tt> command; see
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1460above for details.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1461<div class="paragraph"><p>The <tt>tagger</tt> command uses the same format as <tt>committer</tt> within
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1462<tt>commit</tt>; again see above for details.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1463<div class="paragraph"><p>The <tt>data</tt> command following <tt>tagger</tt> must supply the annotated tag
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1464message (see below for <tt>data</tt> command syntax). To import an empty
1465tag message use a 0 length data. Tag messages are free-form and are
1466not interpreted by Git. Currently they must be encoded in UTF-8,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1467as fast-import does not permit other encodings to be specified.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1468<div class="paragraph"><p>Signing annotated tags during import from within fast-import is not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1469supported. Trying to include your own PGP/GPG signature is not
1470recommended, as the frontend does not (easily) have access to the
1471complete set of bytes which normally goes into such a signature.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1472If signing is required, create lightweight tags from within fast-import with
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1473<tt>reset</tt>, then create the annotated versions of those tags offline
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]1474with the standard <em>git tag</em> process.</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1475<h3 id="_tt_reset_tt"><tt>reset</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1476<div class="paragraph"><p>Creates (or recreates) the named branch, optionally starting from
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1477a specific revision. The reset command allows a frontend to issue
1478a new <tt>from</tt> command for an existing branch, or to create a new
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1479branch from an existing commit without creating a new commit.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1480<div class="literalblock">
1481<div class="content">
1482<pre><tt> 'reset' SP &lt;ref&gt; LF
1483 ('from' SP &lt;committish&gt; LF)?
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1484 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1485</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1486<div class="paragraph"><p>For a detailed description of <tt>&lt;ref&gt;</tt> and <tt>&lt;committish&gt;</tt> see above
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1487under <tt>commit</tt> and <tt>from</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1488<div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
1489<div class="paragraph"><p>The <tt>reset</tt> command can also be used to create lightweight
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1490(non-annotated) tags. For example:</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1491<div class="exampleblock">
1492<div class="exampleblock-content">
1493<div class="literalblock">
1494<div class="content">
1495<pre><tt>reset refs/tags/938
1496from :938</tt></pre>
1497</div></div>
1498</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1499<div class="paragraph"><p>would create the lightweight tag <tt>refs/tags/938</tt> referring to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1500whatever commit mark <tt>:938</tt> references.</p></div>
1501<h3 id="_tt_blob_tt"><tt>blob</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1502<div class="paragraph"><p>Requests writing one file revision to the packfile. The revision
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1503is not connected to any commit; this connection must be formed in
1504a subsequent <tt>commit</tt> command by referencing the blob through an
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1505assigned mark.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1506<div class="literalblock">
1507<div class="content">
1508<pre><tt> 'blob' LF
1509 mark?
1510 data</tt></pre>
1511</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1512<div class="paragraph"><p>The mark command is optional here as some frontends have chosen
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1513to generate the Git SHA-1 for the blob on their own, and feed that
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1514directly to <tt>commit</tt>. This is typically more work than it&#8217;s worth
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1515however, as marks are inexpensive to store and easy to use.</p></div>
1516<h3 id="_tt_data_tt"><tt>data</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1517<div class="paragraph"><p>Supplies raw data (for use as blob/file content, commit messages, or
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1518annotated tag messages) to fast-import. Data can be supplied using an exact
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1519byte count or delimited with a terminating line. Real frontends
1520intended for production-quality conversions should always use the
1521exact byte count format, as it is more robust and performs better.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1522The delimited format is intended primarily for testing fast-import.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1523<div class="paragraph"><p>Comment lines appearing within the <tt>&lt;raw&gt;</tt> part of <tt>data</tt> commands
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1524are always taken to be part of the body of the data and are therefore
1525never ignored by fast-import. This makes it safe to import any
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1526file/message content whose lines might start with <tt>#</tt>.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1527<div class="dlist"><dl>
1528<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1529Exact byte count format
1530</dt>
1531<dd>
1532<p>
1533 The frontend must specify the number of bytes of data.
1534</p>
1535<div class="literalblock">
1536<div class="content">
1537<pre><tt> 'data' SP &lt;count&gt; LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1538 &lt;raw&gt; LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1539</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1540<div class="paragraph"><p>where <tt>&lt;count&gt;</tt> is the exact number of bytes appearing within
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1541<tt>&lt;raw&gt;</tt>. The value of <tt>&lt;count&gt;</tt> is expressed as an ASCII decimal
1542integer. The <tt>LF</tt> on either side of <tt>&lt;raw&gt;</tt> is not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1543included in <tt>&lt;count&gt;</tt> and will not be included in the imported data.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1544<div class="paragraph"><p>The <tt>LF</tt> after <tt>&lt;raw&gt;</tt> is optional (it used to be required) but
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1545recommended. Always including it makes debugging a fast-import
1546stream easier as the next command always starts in column 0
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1547of the next line, even if <tt>&lt;raw&gt;</tt> did not end with an <tt>LF</tt>.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1548</dd>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1549<dt class="hdlist1">
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1550Delimited format
1551</dt>
1552<dd>
1553<p>
1554 A delimiter string is used to mark the end of the data.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1555 fast-import will compute the length by searching for the delimiter.
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1556 This format is primarily useful for testing and is not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1557 recommended for real data.
1558</p>
1559<div class="literalblock">
1560<div class="content">
1561<pre><tt> 'data' SP '&lt;&lt;' &lt;delim&gt; LF
1562 &lt;raw&gt; LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1563 &lt;delim&gt; LF
1564 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1565</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1566<div class="paragraph"><p>where <tt>&lt;delim&gt;</tt> is the chosen delimiter string. The string <tt>&lt;delim&gt;</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1567must not appear on a line by itself within <tt>&lt;raw&gt;</tt>, as otherwise
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1568fast-import will think the data ends earlier than it really does. The <tt>LF</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1569immediately trailing <tt>&lt;raw&gt;</tt> is part of <tt>&lt;raw&gt;</tt>. This is one of
1570the limitations of the delimited format, it is impossible to supply
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1571a data chunk which does not have an LF as its last byte.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1572<div class="paragraph"><p>The <tt>LF</tt> after <tt>&lt;delim&gt; LF</tt> is optional (it used to be required).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1573</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1574</dl></div>
1575<h3 id="_tt_checkpoint_tt"><tt>checkpoint</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1576<div class="paragraph"><p>Forces fast-import to close the current packfile, start a new one, and to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1577save out all current branch refs, tags and marks.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1578<div class="literalblock">
1579<div class="content">
1580<pre><tt> 'checkpoint' LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1581 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1582</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1583<div class="paragraph"><p>Note that fast-import automatically switches packfiles when the current
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1584packfile reaches --max-pack-size, or 4 GiB, whichever limit is
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1585smaller. During an automatic packfile switch fast-import does not update
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1586the branch refs, tags or marks.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1587<div class="paragraph"><p>As a <tt>checkpoint</tt> can require a significant amount of CPU time and
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1588disk IO (to compute the overall pack SHA-1 checksum, generate the
1589corresponding index file, and update the refs) it can easily take
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1590several minutes for a single <tt>checkpoint</tt> command to complete.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1591<div class="paragraph"><p>Frontends may choose to issue checkpoints during extremely large
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1592and long running imports, or when they need to allow another Git
1593process access to a branch. However given that a 30 GiB Subversion
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1594repository can be loaded into Git through fast-import in about 3 hours,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1595explicit checkpointing may not be necessary.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1596<div class="paragraph"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1597<h3 id="_tt_progress_tt"><tt>progress</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1598<div class="paragraph"><p>Causes fast-import to print the entire <tt>progress</tt> line unmodified to
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1599its standard output channel (file descriptor 1) when the command is
1600processed from the input stream. The command otherwise has no impact
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1601on the current import, or on any of fast-import&#8217;s internal state.</p></div>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1602<div class="literalblock">
1603<div class="content">
1604<pre><tt> 'progress' SP &lt;any&gt; LF
1605 LF?</tt></pre>
1606</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1607<div class="paragraph"><p>The <tt>&lt;any&gt;</tt> part of the command may contain any sequence of bytes
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1608that does not contain <tt>LF</tt>. The <tt>LF</tt> after the command is optional.
1609Callers may wish to process the output through a tool such as sed to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1610remove the leading part of the line, for example:</p></div>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1611<div class="exampleblock">
1612<div class="exampleblock-content">
1613<div class="literalblock">
1614<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1615<pre><tt>frontend | git fast-import | sed 's/^progress //'</tt></pre>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1616</div></div>
1617</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1618<div class="paragraph"><p>Placing a <tt>progress</tt> command immediately after a <tt>checkpoint</tt> will
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1619inform the reader when the <tt>checkpoint</tt> has been completed and it
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1620can safely access the refs that fast-import updated.</p></div>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1621<h3 id="_tt_cat_blob_tt"><tt>cat-blob</tt></h3><div style="clear:left"></div>
1622<div class="paragraph"><p>Causes fast-import to print a blob to a file descriptor previously
1623arranged with the <tt>--cat-blob-fd</tt> argument. The command otherwise
1624has no impact on the current import; its main purpose is to
1625retrieve blobs that may be in fast-import&#8217;s memory but not
1626accessible from the target repository.</p></div>
1627<div class="literalblock">
1628<div class="content">
1629<pre><tt> 'cat-blob' SP &lt;dataref&gt; LF</tt></pre>
1630</div></div>
1631<div class="paragraph"><p>The <tt>&lt;dataref&gt;</tt> can be either a mark reference (<tt>:&lt;idnum&gt;</tt>)
1632set previously or a full 40-byte SHA-1 of a Git blob, preexisting or
1633ready to be written.</p></div>
Junio C Hamano64ebb092011-01-18 18:53:06[diff] [blame]1634<div class="paragraph"><p>Output uses the same format as <tt>git cat-file --batch</tt>:</p></div>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1635<div class="exampleblock">
1636<div class="exampleblock-content">
1637<div class="literalblock">
1638<div class="content">
1639<pre><tt>&lt;sha1&gt; SP 'blob' SP &lt;size&gt; LF
1640&lt;contents&gt; LF</tt></pre>
1641</div></div>
1642</div></div>
1643<div class="paragraph"><p>This command can be used anywhere in the stream that comments are
1644accepted. In particular, the <tt>cat-blob</tt> command can be used in the
1645middle of a commit but not in the middle of a <tt>data</tt> command.</p></div>
Junio C Hamano4eda1362012-04-23 20:55:49[diff] [blame]1646<div class="paragraph"><p>See &#8220;Responses To Commands&#8221; below for details about how to read
1647this output safely.</p></div>
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]1648<h3 id="_tt_ls_tt"><tt>ls</tt></h3><div style="clear:left"></div>
1649<div class="paragraph"><p>Prints information about the object at a path to a file descriptor
1650previously arranged with the <tt>--cat-blob-fd</tt> argument. This allows
1651printing a blob from the active commit (with <tt>cat-blob</tt>) or copying a
1652blob or tree from a previous commit for use in the current one (with
1653<tt>filemodify</tt>).</p></div>
1654<div class="paragraph"><p>The <tt>ls</tt> command can be used anywhere in the stream that comments are
1655accepted, including the middle of a commit.</p></div>
1656<div class="dlist"><dl>
1657<dt class="hdlist1">
1658Reading from the active commit
1659</dt>
1660<dd>
1661<p>
1662 This form can only be used in the middle of a <tt>commit</tt>.
1663 The path names a directory entry within fast-import&#8217;s
1664 active commit. The path must be quoted in this case.
1665</p>
1666<div class="literalblock">
1667<div class="content">
1668<pre><tt> 'ls' SP &lt;path&gt; LF</tt></pre>
1669</div></div>
1670</dd>
1671<dt class="hdlist1">
1672Reading from a named tree
1673</dt>
1674<dd>
1675<p>
1676 The <tt>&lt;dataref&gt;</tt> can be a mark reference (<tt>:&lt;idnum&gt;</tt>) or the
1677 full 40-byte SHA-1 of a Git tag, commit, or tree object,
1678 preexisting or waiting to be written.
1679 The path is relative to the top level of the tree
1680 named by <tt>&lt;dataref&gt;</tt>.
1681</p>
1682<div class="literalblock">
1683<div class="content">
1684<pre><tt> 'ls' SP &lt;dataref&gt; SP &lt;path&gt; LF</tt></pre>
1685</div></div>
1686</dd>
1687</dl></div>
1688<div class="paragraph"><p>See <tt>filemodify</tt> above for a detailed description of <tt>&lt;path&gt;</tt>.</p></div>
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]1689<div class="paragraph"><p>Output uses the same format as <tt>git ls-tree &lt;tree&gt; -- &lt;path&gt;</tt>:</p></div>
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]1690<div class="exampleblock">
1691<div class="exampleblock-content">
1692<div class="literalblock">
1693<div class="content">
1694<pre><tt>&lt;mode&gt; SP ('blob' | 'tree' | 'commit') SP &lt;dataref&gt; HT &lt;path&gt; LF</tt></pre>
1695</div></div>
1696</div></div>
1697<div class="paragraph"><p>The &lt;dataref&gt; represents the blob, tree, or commit object at &lt;path&gt;
1698and can be used in later <em>cat-blob</em>, <em>filemodify</em>, or <em>ls</em> commands.</p></div>
1699<div class="paragraph"><p>If there is no file or subtree at that path, <em>git fast-import</em> will
1700instead report</p></div>
1701<div class="exampleblock">
1702<div class="exampleblock-content">
1703<div class="literalblock">
1704<div class="content">
1705<pre><tt>missing SP &lt;path&gt; LF</tt></pre>
1706</div></div>
1707</div></div>
Junio C Hamano4eda1362012-04-23 20:55:49[diff] [blame]1708<div class="paragraph"><p>See &#8220;Responses To Commands&#8221; below for details about how to read
1709this output safely.</p></div>
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1710<h3 id="_tt_feature_tt"><tt>feature</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1711<div class="paragraph"><p>Require that fast-import supports the specified feature, or abort if
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1712it does not.</p></div>
1713<div class="literalblock">
1714<div class="content">
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1715<pre><tt> 'feature' SP &lt;feature&gt; ('=' &lt;argument&gt;)? LF</tt></pre>
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1716</div></div>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1717<div class="paragraph"><p>The &lt;feature&gt; part of the command may be any one of the following:</p></div>
1718<div class="dlist"><dl>
1719<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1720date-format
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1721</dt>
1722<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1723export-marks
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1724</dt>
1725<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1726relative-marks
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1727</dt>
1728<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1729no-relative-marks
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1730</dt>
1731<dt class="hdlist1">
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1732force
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1733</dt>
1734<dd>
1735<p>
1736 Act as though the corresponding command-line option with
1737 a leading <em>--</em> was passed on the command line
1738 (see OPTIONS, above).
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1739</p>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1740</dd>
1741<dt class="hdlist1">
1742import-marks
1743</dt>
Junio C Hamanod8fa0222011-08-26 16:18:15[diff] [blame]1744<dt class="hdlist1">
1745import-marks-if-exists
1746</dt>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1747<dd>
1748<p>
1749 Like --import-marks except in two respects: first, only one
Junio C Hamanod8fa0222011-08-26 16:18:15[diff] [blame]1750 "feature import-marks" or "feature import-marks-if-exists"
1751 command is allowed per stream; second, an --import-marks=
1752 or --import-marks-if-exists command-line option overrides
1753 any of these "feature" commands in the stream; third,
1754 "feature import-marks-if-exists" like a corresponding
1755 command-line option silently skips a nonexistent file.
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1756</p>
1757</dd>
1758<dt class="hdlist1">
1759cat-blob
1760</dt>
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]1761<dt class="hdlist1">
1762ls
1763</dt>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1764<dd>
1765<p>
Junio C Hamano73d10512011-03-01 01:02:38[diff] [blame]1766 Require that the backend support the <em>cat-blob</em> or <em>ls</em> command.
1767 Versions of fast-import not supporting the specified command
1768 will exit with a message indicating so.
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1769 This lets the import error out early with a clear message,
1770 rather than wasting time on the early part of an import
1771 before the unsupported command is detected.
1772</p>
1773</dd>
Junio C Hamano23e3f532011-02-10 02:05:29[diff] [blame]1774<dt class="hdlist1">
1775notes
1776</dt>
1777<dd>
1778<p>
1779 Require that the backend support the <em>notemodify</em> (N)
1780 subcommand to the <em>commit</em> command.
1781 Versions of fast-import not supporting notes will exit
1782 with a message indicating so.
1783</p>
1784</dd>
Junio C Hamanofbc773c2011-08-02 00:09:12[diff] [blame]1785<dt class="hdlist1">
1786done
1787</dt>
1788<dd>
1789<p>
1790 Error out if the stream ends without a <em>done</em> command.
1791 Without this feature, errors causing the frontend to end
1792 abruptly at a convenient point in the stream can go
1793 undetected.
1794</p>
1795</dd>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1796</dl></div>
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1797<h3 id="_tt_option_tt"><tt>option</tt></h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1798<div class="paragraph"><p>Processes the specified option so that git fast-import behaves in a
1799way that suits the frontend&#8217;s needs.
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1800Note that options specified by the frontend are overridden by any
1801options the user may specify to git fast-import itself.</p></div>
1802<div class="literalblock">
1803<div class="content">
1804<pre><tt> 'option' SP &lt;option&gt; LF</tt></pre>
1805</div></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1806<div class="paragraph"><p>The <tt>&lt;option&gt;</tt> part of the command may contain any of the options
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1807listed in the OPTIONS section that do not change import semantics,
1808without the leading <em>--</em> and is treated in the same way.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1809<div class="paragraph"><p>Option commands must be the first commands on the input (not counting
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1810feature commands), to give an option command after any non-option
1811command is an error.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1812<div class="paragraph"><p>The following commandline options change import semantics and may therefore
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1813not be passed as option:</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1814<div class="ulist"><ul>
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1815<li>
1816<p>
1817date-format
1818</p>
1819</li>
1820<li>
1821<p>
1822import-marks
1823</p>
1824</li>
1825<li>
1826<p>
1827export-marks
1828</p>
1829</li>
1830<li>
1831<p>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]1832cat-blob-fd
1833</p>
1834</li>
1835<li>
1836<p>
Junio C Hamano6ce6b6c2010-01-18 01:25:50[diff] [blame]1837force
1838</p>
1839</li>
1840</ul></div>
Junio C Hamanofbc773c2011-08-02 00:09:12[diff] [blame]1841<h3 id="_tt_done_tt"><tt>done</tt></h3><div style="clear:left"></div>
1842<div class="paragraph"><p>If the <tt>done</tt> feature is not in use, treated as if EOF was read.
1843This can be used to tell fast-import to finish early.</p></div>
1844<div class="paragraph"><p>If the <tt>--done</tt> command line option or <tt>feature done</tt> command is
1845in use, the <tt>done</tt> command is mandatory and marks the end of the
1846stream.</p></div>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1847</div>
Junio C Hamano4eda1362012-04-23 20:55:49[diff] [blame]1848<h2 id="_responses_to_commands">Responses To Commands</h2>
1849<div class="sectionbody">
1850<div class="paragraph"><p>New objects written by fast-import are not available immediately.
1851Most fast-import commands have no visible effect until the next
1852checkpoint (or completion). The frontend can send commands to
1853fill fast-import&#8217;s input pipe without worrying about how quickly
1854they will take effect, which improves performance by simplifying
1855scheduling.</p></div>
1856<div class="paragraph"><p>For some frontends, though, it is useful to be able to read back
1857data from the current repository as it is being updated (for
1858example when the source material describes objects in terms of
1859patches to be applied to previously imported objects). This can
1860be accomplished by connecting the frontend and fast-import via
1861bidirectional pipes:</p></div>
1862<div class="exampleblock">
1863<div class="exampleblock-content">
1864<div class="literalblock">
1865<div class="content">
1866<pre><tt>mkfifo fast-import-output
1867frontend &lt;fast-import-output |
1868git fast-import &gt;fast-import-output</tt></pre>
1869</div></div>
1870</div></div>
1871<div class="paragraph"><p>A frontend set up this way can use <tt>progress</tt>, <tt>ls</tt>, and <tt>cat-blob</tt>
1872commands to read information from the import in progress.</p></div>
1873<div class="paragraph"><p>To avoid deadlock, such frontends must completely consume any
1874pending output from <tt>progress</tt>, <tt>ls</tt>, and <tt>cat-blob</tt> before
1875performing writes to fast-import that might block.</p></div>
1876</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1877<h2 id="_crash_reports">Crash Reports</h2>
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1878<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1879<div class="paragraph"><p>If fast-import is supplied invalid input it will terminate with a
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1880non-zero exit status and create a crash report in the top level of
1881the Git repository it was importing into. Crash reports contain
1882a snapshot of the internal fast-import state as well as the most
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1883recent commands that lead up to the crash.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1884<div class="paragraph"><p>All recent commands (including stream comments, file changes and
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1885progress commands) are shown in the command history within the crash
1886report, but raw file data and commit messages are excluded from the
1887crash report. This exclusion saves space within the report file
1888and reduces the amount of buffering that fast-import must perform
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1889during execution.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1890<div class="paragraph"><p>After writing a crash report fast-import will close the current
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1891packfile and export the marks table. This allows the frontend
1892developer to inspect the repository state and resume the import from
1893the point where it crashed. The modified branches and tags are not
1894updated during a crash, as the import did not complete successfully.
1895Branch and tag information can be found in the crash report and
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1896must be applied manually if the update is needed.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1897<div class="paragraph"><p>An example crash:</p></div>
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1898<div class="exampleblock">
1899<div class="exampleblock-content">
1900<div class="literalblock">
1901<div class="content">
1902<pre><tt>$ cat &gt;in &lt;&lt;END_OF_INPUT
1903# my very first test commit
1904commit refs/heads/master
1905committer Shawn O. Pearce &lt;spearce&gt; 19283 -0400
1906# who is that guy anyway?
1907data &lt;&lt;EOF
1908this is my commit
1909EOF
1910M 644 inline .gitignore
1911data &lt;&lt;EOF
1912.gitignore
1913EOF
1914M 777 inline bob
1915END_OF_INPUT</tt></pre>
1916</div></div>
1917<div class="literalblock">
1918<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1919<pre><tt>$ git fast-import &lt;in
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1920fatal: Corrupt mode: M 777 inline bob
1921fast-import: dumping crash report to .git/fast_import_crash_8434</tt></pre>
1922</div></div>
1923<div class="literalblock">
1924<div class="content">
1925<pre><tt>$ cat .git/fast_import_crash_8434
1926fast-import crash report:
1927 fast-import process: 8434
1928 parent process : 1391
1929 at Sat Sep 1 00:58:12 2007</tt></pre>
1930</div></div>
1931<div class="literalblock">
1932<div class="content">
1933<pre><tt>fatal: Corrupt mode: M 777 inline bob</tt></pre>
1934</div></div>
1935<div class="literalblock">
1936<div class="content">
1937<pre><tt>Most Recent Commands Before Crash
1938---------------------------------
1939 # my very first test commit
1940 commit refs/heads/master
1941 committer Shawn O. Pearce &lt;spearce&gt; 19283 -0400
1942 # who is that guy anyway?
1943 data &lt;&lt;EOF
1944 M 644 inline .gitignore
1945 data &lt;&lt;EOF
1946* M 777 inline bob</tt></pre>
1947</div></div>
1948<div class="literalblock">
1949<div class="content">
1950<pre><tt>Active Branch LRU
1951-----------------
1952 active_branches = 1 cur, 5 max</tt></pre>
1953</div></div>
1954<div class="literalblock">
1955<div class="content">
1956<pre><tt>pos clock name
1957~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1958 1) 0 refs/heads/master</tt></pre>
1959</div></div>
1960<div class="literalblock">
1961<div class="content">
1962<pre><tt>Inactive Branches
1963-----------------
1964refs/heads/master:
1965 status : active loaded dirty
1966 tip commit : 0000000000000000000000000000000000000000
1967 old tree : 0000000000000000000000000000000000000000
1968 cur tree : 0000000000000000000000000000000000000000
1969 commit clock: 0
1970 last pack :</tt></pre>
1971</div></div>
1972<div class="literalblock">
1973<div class="content">
1974<pre><tt>-------------------
1975END OF CRASH REPORT</tt></pre>
1976</div></div>
1977</div></div>
1978</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1979<h2 id="_tips_and_tricks">Tips and Tricks</h2>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1980<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1981<div class="paragraph"><p>The following tips and tricks have been collected from various
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1982users of fast-import, and are offered here as suggestions.</p></div>
1983<h3 id="_use_one_mark_per_commit">Use One Mark Per Commit</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1984<div class="paragraph"><p>When doing a repository conversion, use a unique mark per commit
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1985(<tt>mark :&lt;n&gt;</tt>) and supply the --export-marks option on the command
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1986line. fast-import will dump a file which lists every mark and the Git
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1987object SHA-1 that corresponds to it. If the frontend can tie
1988the marks back to the source repository, it is easy to verify the
1989accuracy and completeness of the import by comparing each Git
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1990commit to the corresponding source revision.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1991<div class="paragraph"><p>Coming from a system such as Perforce or Subversion this should be
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1992quite simple, as the fast-import mark can also be the Perforce changeset
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1993number or the Subversion revision number.</p></div>
1994<h3 id="_freely_skip_around_branches">Freely Skip Around Branches</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1995<div class="paragraph"><p>Don&#8217;t bother trying to optimize the frontend to stick to one branch
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1996at a time during an import. Although doing so might be slightly
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1997faster for fast-import, it tends to increase the complexity of the frontend
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1998code considerably.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]1999<div class="paragraph"><p>The branch LRU builtin to fast-import tends to behave very well, and the
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2000cost of activating an inactive branch is so low that bouncing around
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2001between branches has virtually no impact on import performance.</p></div>
2002<h3 id="_handling_renames">Handling Renames</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2003<div class="paragraph"><p>When importing a renamed file or directory, simply delete the old
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]2004name(s) and modify the new name(s) during the corresponding commit.
2005Git performs rename detection after-the-fact, rather than explicitly
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2006during a commit.</p></div>
2007<h3 id="_use_tag_fixup_branches">Use Tag Fixup Branches</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2008<div class="paragraph"><p>Some other SCM systems let the user create a tag from multiple
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2009files which are not from the same commit/changeset. Or to create
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2010tags which are a subset of the files available in the repository.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2011<div class="paragraph"><p>Importing these tags as-is in Git is impossible without making at
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]2012least one commit which <tt>`fixes up'' the files to match the content
2013of the tag. Use fast-import's `reset</tt> command to reset a dummy branch
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2014outside of your normal branch space to the base commit for the tag,
2015then commit one or more file fixup commits, and finally tag the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2016dummy branch.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2017<div class="paragraph"><p>For example since all normal branches are stored under <tt>refs/heads/</tt>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2018name the tag fixup branch <tt>TAG_FIXUP</tt>. This way it is impossible for
2019the fixup branch used by the importer to have namespace conflicts
2020with real branches imported from the source (the name <tt>TAG_FIXUP</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2021is not <tt>refs/heads/TAG_FIXUP</tt>).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2022<div class="paragraph"><p>When committing fixups, consider using <tt>merge</tt> to connect the
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2023commit(s) which are supplying file revisions to the fixup branch.
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]2024Doing so will allow tools such as <em>git blame</em> to track
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2025through the real commit history and properly annotate the source
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2026files.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2027<div class="paragraph"><p>After fast-import terminates the frontend will need to do <tt>rm .git/TAG_FIXUP</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2028to remove the dummy branch.</p></div>
2029<h3 id="_import_now_repack_later">Import Now, Repack Later</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2030<div class="paragraph"><p>As soon as fast-import completes the Git repository is completely valid
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]2031and ready for use. Typically this takes only a very short time,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2032even for considerably large projects (100,000+ commits).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2033<div class="paragraph"><p>However repacking the repository is necessary to improve data
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2034locality and access performance. It can also take hours on extremely
2035large projects (especially if -f and a large --window parameter is
2036used). Since repacking is safe to run alongside readers and writers,
2037run the repack in the background and let it finish when it finishes.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2038There is no reason to wait to explore your new Git project!</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2039<div class="paragraph"><p>If you choose to wait for the repack, don&#8217;t try to run benchmarks
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2040or performance tests until repacking is completed. fast-import outputs
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2041suboptimal packfiles that are simply never seen in real use
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2042situations.</p></div>
2043<h3 id="_repacking_historical_data">Repacking Historical Data</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2044<div class="paragraph"><p>If you are repacking very old imported data (e.g. older than the
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2045last year), consider expending some extra CPU time and supplying
Junio C Hamano1aa40d22010-01-21 17:46:43[diff] [blame]2046--window=50 (or higher) when you run <em>git repack</em>.
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]2047This will take longer, but will also produce a smaller packfile.
2048You only need to expend the effort once, and everyone using your
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2049project will benefit from the smaller repository.</p></div>
2050<h3 id="_include_some_progress_messages">Include Some Progress Messages</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2051<div class="paragraph"><p>Every once in a while have your frontend emit a <tt>progress</tt> message
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]2052to fast-import. The contents of the messages are entirely free-form,
2053so one suggestion would be to output the current month and year
2054each time the current commit date moves into the next month.
2055Your users will feel better knowing how much of the data stream
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2056has been processed.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2057</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2058<h2 id="_packfile_optimization">Packfile Optimization</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2059<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2060<div class="paragraph"><p>When packing a blob fast-import always attempts to deltify against the last
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2061blob written. Unless specifically arranged for by the frontend,
2062this will probably not be a prior version of the same file, so the
2063generated delta will not be the smallest possible. The resulting
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2064packfile will be compressed, but will not be optimal.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2065<div class="paragraph"><p>Frontends which have efficient access to all revisions of a
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2066single file (for example reading an RCS/CVS ,v file) can choose
2067to supply all revisions of that file as a sequence of consecutive
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2068<tt>blob</tt> commands. This allows fast-import to deltify the different file
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2069revisions against each other, saving space in the final packfile.
2070Marks can be used to later identify individual file revisions during
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2071a sequence of <tt>commit</tt> commands.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2072<div class="paragraph"><p>The packfile(s) created by fast-import do not encourage good disk access
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2073patterns. This is caused by fast-import writing the data in the order
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2074it is received on standard input, while Git typically organizes
2075data within packfiles to make the most recent (current tip) data
2076appear before historical data. Git also clusters commits together,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2077speeding up revision traversal through better cache locality.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2078<div class="paragraph"><p>For this reason it is strongly recommended that users repack the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2079repository with <tt>git repack -a -d</tt> after fast-import completes, allowing
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2080Git to reorganize the packfiles for faster data access. If blob
2081deltas are suboptimal (see above) then also adding the <tt>-f</tt> option
2082to force recomputation of all deltas can significantly reduce the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2083final packfile size (30-50% smaller can be quite typical).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2084</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2085<h2 id="_memory_utilization">Memory Utilization</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2086<div class="sectionbody">
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2087<div class="paragraph"><p>There are a number of factors which affect how much memory fast-import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2088requires to perform an import. Like critical sections of core
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]2089Git, fast-import uses its own memory allocators to amortize any overheads
2090associated with malloc. In practice fast-import tends to amortize any
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2091malloc overheads to 0, due to its use of large block allocations.</p></div>
2092<h3 id="_per_object">per object</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2093<div class="paragraph"><p>fast-import maintains an in-memory structure for every object written in
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2094this execution. On a 32 bit system the structure is 32 bytes,
2095on a 64 bit system the structure is 40 bytes (due to the larger
2096pointer sizes). Objects in the table are not deallocated until
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2097fast-import terminates. Importing 2 million objects on a 32 bit system
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2098will require approximately 64 MiB of memory.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2099<div class="paragraph"><p>The object table is actually a hashtable keyed on the object name
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2100(the unique SHA-1). This storage configuration allows fast-import to reuse
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2101an existing or already written object and avoid writing duplicates
2102to the output packfile. Duplicate blobs are surprisingly common
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2103in an import, typically due to branch merges in the source.</p></div>
2104<h3 id="_per_mark">per mark</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2105<div class="paragraph"><p>Marks are stored in a sparse array, using 1 pointer (4 bytes or 8
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2106bytes, depending on pointer size) per mark. Although the array
2107is sparse, frontends are still strongly encouraged to use marks
2108between 1 and n, where n is the total number of marks required for
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2109this import.</p></div>
2110<h3 id="_per_branch">per branch</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2111<div class="paragraph"><p>Branches are classified as active and inactive. The memory usage
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2112of the two classes is significantly different.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2113<div class="paragraph"><p>Inactive branches are stored in a structure which uses 96 or 120
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2114bytes (32 bit or 64 bit systems, respectively), plus the length of
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2115the branch name (typically under 200 bytes), per branch. fast-import will
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2116easily handle as many as 10,000 inactive branches in under 2 MiB
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2117of memory.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2118<div class="paragraph"><p>Active branches have the same overhead as inactive branches, but
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2119also contain copies of every tree that has been recently modified on
2120that branch. If subtree <tt>include</tt> has not been modified since the
2121branch became active, its contents will not be loaded into memory,
2122but if subtree <tt>src</tt> has been modified by a commit since the branch
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2123became active, then its contents will be loaded in memory.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2124<div class="paragraph"><p>As active branches store metadata about the files contained on that
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2125branch, their in-memory storage size can grow to a considerable size
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2126(see below).</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2127<div class="paragraph"><p>fast-import automatically moves active branches to inactive status based on
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2128a simple least-recently-used algorithm. The LRU chain is updated on
2129each <tt>commit</tt> command. The maximum number of active branches can be
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2130increased or decreased on the command line with --active-branches=.</p></div>
2131<h3 id="_per_active_tree">per active tree</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2132<div class="paragraph"><p>Trees (aka directories) use just 12 bytes of memory on top of the
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2133memory required for their entries (see &#8220;per active file&#8221; below).
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]2134The cost of a tree is virtually 0, as its overhead amortizes out
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2135over the individual file entries.</p></div>
2136<h3 id="_per_active_file_entry">per active file entry</h3><div style="clear:left"></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2137<div class="paragraph"><p>Files (and pointers to subtrees) within active trees require 52 or 64
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2138bytes (32/64 bit platforms) per entry. To conserve space, file and
2139tree names are pooled in a common string table, allowing the filename
2140&#8220;Makefile&#8221; to use just 16 bytes (after including the string header
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2141overhead) no matter how many times it occurs within the project.</p></div>
Junio C Hamano68cf15a2010-11-06 01:01:59[diff] [blame]2142<div class="paragraph"><p>The active branch LRU, when coupled with the filename string pool
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]2143and lazy loading of subtrees, allows fast-import to efficiently import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2144projects with 2,000+ branches and 45,114+ files in a very limited
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2145memory footprint (less than 2.7 MiB per active branch).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2146</div>
Junio C Hamano0d75e872010-12-17 06:57:26[diff] [blame]2147<h2 id="_signals">Signals</h2>
2148<div class="sectionbody">
2149<div class="paragraph"><p>Sending <strong>SIGUSR1</strong> to the <em>git fast-import</em> process ends the current
2150packfile early, simulating a <tt>checkpoint</tt> command. The impatient
2151operator can use this facility to peek at the objects and refs from an
2152import in progress, at the cost of some added running time and worse
2153compression.</p></div>
2154</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]2155<h2 id="_git">GIT</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2156<div class="sectionbody">
Junio C Hamanoa28a9202012-06-21 07:08:23[diff] [blame]2157<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2158</div>
Junio C Hamano7bd050f2011-09-22 06:32:22[diff] [blame]2159</div>
2160<div id="footnotes"><hr /></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2161<div id="footer">
2162<div id="footer-text">
Junio C Hamanob76a6862012-05-02 22:02:46[diff] [blame]2163Last updated 2012-05-02 15:00:44 PDT
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]2164</div>
2165</div>
2166</body>
2167</html>