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