Google Git
Sign in
chromium / external / gitster / git-htmldocs / 4060a6a703de464eb99764be3a8ca46c6a2b42e7 / . / git-fast-import.html
blob: 9cca8940b6c4543ea6208e0b17b27094e01d25db [file] [log] [blame]
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]26
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]47h1, h2, h3 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]59
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]83 font-size: 1.1em;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]84}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]164
165div.attribution {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]166 text-align: right;
167}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]214div.olist2 ol {
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
274include1::./stylesheets/xhtml11-manpage.css[]
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]275/* Workarounds for IE6's broken and incomplete CSS2. */
276
277div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
281}
282div.sidebar-title, div.image-title {
283 font-family: sans-serif;
284 font-weight: bold;
285 margin-top: 0.0em;
286 margin-bottom: 0.5em;
287}
288
289div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
293}
294
295div.quoteblock-content {
296 padding-left: 2.0em;
297}
298
299div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
302}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]303
304/* IE6 sets dynamically generated links as visited. */
305div#toc a:visited { color: blue; }
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]306</style>
307<title>git-fast-import(1)</title>
308</head>
309<body>
310<div id="header">
311<h1>
312git-fast-import(1) Manual Page
313</h1>
314<h2>NAME</h2>
315<div class="sectionbody">
316<p>git-fast-import -
Junio C Hamano053827f2007-02-14 07:23:58[diff] [blame]317 Backend for fast Git data importers
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]318</p>
319</div>
320</div>
321<h2>SYNOPSIS</h2>
322<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]323<div class="para"><p>frontend | <em>git fast-import</em> [options]</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]324</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]325<h2 id="_description">DESCRIPTION</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]326<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]327<div class="para"><p>This program is usually not what the end user wants to run directly.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]328Most end users want to use one of the existing frontend programs,
329which parses a specific type of foreign source and feeds the contents
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]330stored there to <em>git-fast-import</em>.</p></div>
331<div class="para"><p>fast-import reads a mixed command/data stream from standard input and
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]332writes one or more packfiles directly into the current repository.
333When EOF is received on standard input, fast import writes out
334updated branch and tag refs, fully updating the current repository
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]335with the newly imported data.</p></div>
336<div class="para"><p>The fast-import backend itself can import into an empty repository (one that
337has already been initialized by <em>git-init</em>) or incrementally
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]338update an existing populated repository. Whether or not incremental
339imports are supported from a particular foreign source depends on
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]340the frontend program in use.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]341</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]342<h2 id="_options">OPTIONS</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]343<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]344<div class="vlist"><dl>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]345<dt>
346--date-format=&lt;fmt&gt;
347</dt>
348<dd>
349<p>
350 Specify the type of dates the frontend will supply to
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]351 fast-import within <tt>author</tt>, <tt>committer</tt> and <tt>tagger</tt> commands.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]352 See &#8220;Date Formats&#8221; below for details about which formats
353 are supported, and their syntax.
354</p>
355</dd>
356<dt>
357--force
358</dt>
359<dd>
360<p>
361 Force updating modified existing branches, even if doing
362 so would cause commits to be lost (as the new commit does
363 not contain the old commit).
364</p>
365</dd>
366<dt>
367--max-pack-size=&lt;n&gt;
368</dt>
369<dd>
370<p>
371 Maximum size of each output packfile, expressed in MiB.
372 The default is 4096 (4 GiB) as that is the maximum allowed
373 packfile size (due to file format limitations). Some
374 importers may wish to lower this, such as to ensure the
375 resulting packfiles fit on CDs.
376</p>
377</dd>
378<dt>
379--depth=&lt;n&gt;
380</dt>
381<dd>
382<p>
383 Maximum delta depth, for blob and tree deltification.
384 Default is 10.
385</p>
386</dd>
387<dt>
388--active-branches=&lt;n&gt;
389</dt>
390<dd>
391<p>
392 Maximum number of branches to maintain active at once.
393 See &#8220;Memory Utilization&#8221; below for details. Default is 5.
394</p>
395</dd>
396<dt>
397--export-marks=&lt;file&gt;
398</dt>
399<dd>
400<p>
401 Dumps the internal marks table to &lt;file&gt; when complete.
402 Marks are written one per line as <tt>:markid SHA-1</tt>.
403 Frontends can use this file to validate imports after they
Junio C Hamanod15328a2007-03-09 09:06:40[diff] [blame]404 have been completed, or to save the marks table across
405 incremental runs. As &lt;file&gt; is only opened and truncated
406 at checkpoint (or completion) the same path can also be
407 safely given to --import-marks.
408</p>
409</dd>
410<dt>
411--import-marks=&lt;file&gt;
412</dt>
413<dd>
414<p>
415 Before processing any input, load the marks specified in
416 &lt;file&gt;. The input file must exist, must be readable, and
417 must use the same format as produced by --export-marks.
418 Multiple options may be supplied to import more than one
419 set of marks. If a mark is defined to different values,
420 the last file wins.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]421</p>
422</dd>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]423<dt>
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]424--export-pack-edges=&lt;file&gt;
425</dt>
426<dd>
427<p>
428 After creating a packfile, print a line of data to
429 &lt;file&gt; listing the filename of the packfile and the last
430 commit on each branch that was written to that packfile.
431 This information may be useful after importing projects
432 whose total object set exceeds the 4 GiB packfile limit,
433 as these commits can be used as edge points during calls
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]434 to <em>git-pack-objects</em>.
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]435</p>
436</dd>
437<dt>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]438--quiet
439</dt>
440<dd>
441<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]442 Disable all non-fatal output, making fast-import silent when it
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]443 is successful. This option disables the output shown by
444 --stats.
445</p>
446</dd>
447<dt>
448--stats
449</dt>
450<dd>
451<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]452 Display some basic statistics about the objects fast-import has
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]453 created, the packfiles they were stored into, and the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]454 memory used by fast-import during this run. Showing this output
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]455 is currently the default, but can be disabled with --quiet.
456</p>
457</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]458</dl></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]459</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]460<h2 id="_performance">Performance</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]461<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]462<div class="para"><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]463amount of memory usage and processing time. Assuming the frontend
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]464is 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]465import times for projects holding 10+ years of history and containing
466100,000+ individual commits are generally completed in just 1-2
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]467hours on quite modest (~$2,000 USD) hardware.</p></div>
468<div class="para"><p>Most bottlenecks appear to be in foreign source data access (the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]469source just cannot extract revisions fast enough) or disk IO (fast-import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]470writes as fast as the disk will take the data). Imports will run
471faster if the source data is stored on a different drive than the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]472destination Git repository (due to less IO contention).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]473</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]474<h2 id="_development_cost">Development Cost</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]475<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]476<div class="para"><p>A typical frontend for fast-import tends to weigh in at approximately 200
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]477lines of Perl/Python/Ruby code. Most developers have been able to
478create working importers in just a couple of hours, even though it
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]479is their first exposure to fast-import, and sometimes even to Git. This is
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]480an ideal situation, given that most conversion tools are throw-away
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]481(use once, and never look back).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]482</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]483<h2 id="_parallel_operation">Parallel Operation</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]484<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]485<div class="para"><p>Like <em>git-push</em> or <em>git-fetch</em>, imports handled by fast-import are safe to
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]486run alongside parallel <tt>git repack -a -d</tt> or <tt>git gc</tt> invocations,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]487or any other Git operation (including <em>git-prune</em>, as loose objects
488are never used by fast-import).</p></div>
489<div class="para"><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]490After the import, during its ref update phase, fast-import tests each
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]491existing branch ref to verify the update will be a fast-forward
492update (the commit stored in the ref is contained in the new
493history of the commit to be written). If the update is not a
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]494fast-forward update, fast-import will skip updating that ref and instead
495prints a warning message. fast-import will always attempt to update all
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]496branch refs, and does not stop on the first failure.</p></div>
497<div class="para"><p>Branch updates can be forced with --force, but its recommended that
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]498this only be used on an otherwise quiet repository. Using --force
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]499is not necessary for an initial import into an empty repository.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]500</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]501<h2 id="_technical_discussion">Technical Discussion</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]502<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]503<div class="para"><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]504or modified at any point during the import process by sending a
505<tt>commit</tt> command on the input stream. This design allows a frontend
506program to process an unlimited number of branches simultaneously,
507generating commits in the order they are available from the source
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]508data. It also simplifies the frontend programs considerably.</p></div>
509<div class="para"><p>fast-import does not use or alter the current working directory, or any
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]510file within it. (It does however update the current Git repository,
511as referenced by <tt>GIT_DIR</tt>.) Therefore an import frontend may use
512the working directory for its own purposes, such as extracting file
513revisions from the foreign source. This ignorance of the working
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]514directory also allows fast-import to run very quickly, as it does not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]515need to perform any costly file update operations when switching
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]516between branches.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]517</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]518<h2 id="_input_format">Input Format</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]519<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]520<div class="para"><p>With the exception of raw file data (which Git does not interpret)
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]521the fast-import input format is text (ASCII) based. This text based
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]522format simplifies development and debugging of frontend programs,
523especially when a higher level language such as Perl, Python or
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]524Ruby is being used.</p></div>
525<div class="para"><p>fast-import is very strict about its input. Where we say SP below we mean
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]526<strong>exactly</strong> one space. Likewise LF means one (and only one) linefeed.
527Supplying additional whitespace characters will cause unexpected
528results, such as branch names or file names with leading or trailing
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]529spaces in their name, or early termination of fast-import when it encounters
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]530unexpected input.</p></div>
531<h3 id="_stream_comments">Stream Comments</h3><div style="clear:left"></div>
532<div class="para"><p>To aid in debugging frontends fast-import ignores any line that
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]533begins with <tt>#</tt> (ASCII pound/hash) up to and including the line
534ending <tt>LF</tt>. A comment line may contain any sequence of bytes
535that does not contain an LF and therefore may be used to include
536any detailed debugging information that might be specific to the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]537frontend and useful when inspecting a fast-import data stream.</p></div>
538<h3 id="_date_formats">Date Formats</h3><div style="clear:left"></div>
539<div class="para"><p>The following date formats are supported. A frontend should select
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]540the format it will use for this import by passing the format name
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]541in the --date-format=&lt;fmt&gt; command line option.</p></div>
542<div class="vlist"><dl>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]543<dt>
544<tt>raw</tt>
545</dt>
546<dd>
547<p>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]548 This is the Git native format and is <tt>&lt;time&gt; SP &lt;offutc&gt;</tt>.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]549 It is also fast-import's default format, if --date-format was
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]550 not specified.
551</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]552<div class="para"><p>The time of the event is specified by <tt>&lt;time&gt;</tt> as the number of
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]553seconds since the UNIX epoch (midnight, Jan 1, 1970, UTC) and is
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]554written as an ASCII decimal integer.</p></div>
555<div class="para"><p>The local offset is specified by <tt>&lt;offutc&gt;</tt> as a positive or negative
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]556offset from UTC. For example EST (which is 5 hours behind UTC)
557would be expressed in <tt>&lt;tz&gt;</tt> by &#8220;-0500&#8221; while UTC is &#8220;+0000&#8221;.
558The local offset does not affect <tt>&lt;time&gt;</tt>; it is used only as an
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]559advisement to help formatting routines display the timestamp.</p></div>
560<div class="para"><p>If the local offset is not available in the source material, use
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]561&#8220;+0000&#8221;, or the most common local offset. For example many
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]562organizations have a CVS repository which has only ever been accessed
563by users who are located in the same location and timezone. In this
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]564case a reasonable offset from UTC could be assumed.</p></div>
565<div class="para"><p>Unlike the <tt>rfc2822</tt> format, this format is very strict. Any
566variation in formatting will cause fast-import to reject the value.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]567</dd>
568<dt>
569<tt>rfc2822</tt>
570</dt>
571<dd>
572<p>
573 This is the standard email format as described by RFC 2822.
574</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]575<div class="para"><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]576parser is accurate, but a little on the lenient side. It is the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]577same parser used by <em>git-am</em> when applying patches
578received from email.</p></div>
579<div class="para"><p>Some malformed strings may be accepted as valid dates. In some of
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]580these cases Git will still be able to obtain the correct date from
581the malformed string. There are also some types of malformed
582strings which Git will parse wrong, and yet consider valid.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]583Seriously malformed strings will be rejected.</p></div>
584<div class="para"><p>Unlike the <tt>raw</tt> format above, the timezone/UTC offset information
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]585contained in an RFC 2822 date string is used to adjust the date
586value to UTC prior to storage. Therefore it is important that
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]587this information be as accurate as possible.</p></div>
588<div class="para"><p>If the source material uses RFC 2822 style dates,
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]589the frontend should let fast-import handle the parsing and conversion
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]590(rather than attempting to do it itself) as the Git parser has
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]591been well tested in the wild.</p></div>
592<div class="para"><p>Frontends should prefer the <tt>raw</tt> format if the source material
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]593already uses UNIX-epoch format, can be coaxed to give dates in that
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]594format, or its format is easily convertible to it, as there is no
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]595ambiguity in parsing.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]596</dd>
597<dt>
598<tt>now</tt>
599</dt>
600<dd>
601<p>
602 Always use the current time and timezone. The literal
603 <tt>now</tt> must always be supplied for <tt>&lt;when&gt;</tt>.
604</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]605<div class="para"><p>This is a toy format. The current time and timezone of this system
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]606is always copied into the identity string at the time it is being
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]607created by fast-import. There is no way to specify a different time or
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]608timezone.</p></div>
609<div class="para"><p>This particular format is supplied as its short to implement and
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]610may be useful to a process that wants to create a new commit
611right now, without needing to use a working directory or
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]612<em>git-update-index</em>.</p></div>
613<div class="para"><p>If separate <tt>author</tt> and <tt>committer</tt> commands are used in a <tt>commit</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]614the timestamps may not match, as the system clock will be polled
615twice (once for each command). The only way to ensure that both
616author and committer identity information has the same timestamp
617is to omit <tt>author</tt> (thus copying from <tt>committer</tt>) or to use a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]618date format other than <tt>now</tt>.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]619</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]620</dl></div>
621<h3 id="_commands">Commands</h3><div style="clear:left"></div>
622<div class="para"><p>fast-import accepts several commands to update the current repository
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]623and control the current import process. More detailed discussion
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]624(with examples) of each command follows later.</p></div>
625<div class="vlist"><dl>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]626<dt>
627<tt>commit</tt>
628</dt>
629<dd>
630<p>
631 Creates a new branch or updates an existing branch by
632 creating a new commit and updating the branch to point at
633 the newly created commit.
634</p>
635</dd>
636<dt>
637<tt>tag</tt>
638</dt>
639<dd>
640<p>
641 Creates an annotated tag object from an existing commit or
642 branch. Lightweight tags are not supported by this command,
643 as they are not recommended for recording meaningful points
644 in time.
645</p>
646</dd>
647<dt>
648<tt>reset</tt>
649</dt>
650<dd>
651<p>
652 Reset an existing branch (or a new branch) to a specific
653 revision. This command must be used to change a branch to
654 a specific revision without making a commit on it.
655</p>
656</dd>
657<dt>
658<tt>blob</tt>
659</dt>
660<dd>
661<p>
662 Convert raw file data into a blob, for future use in a
663 <tt>commit</tt> command. This command is optional and is not
664 needed to perform an import.
665</p>
666</dd>
667<dt>
668<tt>checkpoint</tt>
669</dt>
670<dd>
671<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]672 Forces fast-import to close the current packfile, generate its
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]673 unique SHA-1 checksum and index, and start a new packfile.
674 This command is optional and is not needed to perform
675 an import.
676</p>
677</dd>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]678<dt>
679<tt>progress</tt>
680</dt>
681<dd>
682<p>
683 Causes fast-import to echo the entire line to its own
684 standard output. This command is optional and is not needed
685 to perform an import.
686</p>
687</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]688</dl></div>
689<h3 id="_tt_commit_tt"><tt>commit</tt></h3><div style="clear:left"></div>
690<div class="para"><p>Create or update a branch with a new commit, recording one logical
691change to the project.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]692<div class="literalblock">
693<div class="content">
694<pre><tt> 'commit' SP &lt;ref&gt; LF
695 mark?
696 ('author' SP &lt;name&gt; SP LT &lt;email&gt; GT SP &lt;when&gt; LF)?
697 'committer' SP &lt;name&gt; SP LT &lt;email&gt; GT SP &lt;when&gt; LF
698 data
699 ('from' SP &lt;committish&gt; LF)?
700 ('merge' SP &lt;committish&gt; LF)?
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]701 (filemodify | filedelete | filecopy | filerename | filedeleteall)*
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]702 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]703</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]704<div class="para"><p>where <tt>&lt;ref&gt;</tt> is the name of the branch to make the commit on.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]705Typically branch names are prefixed with <tt>refs/heads/</tt> in
706Git, so importing the CVS branch symbol <tt>RELENG-1_0</tt> would use
707<tt>refs/heads/RELENG-1_0</tt> for the value of <tt>&lt;ref&gt;</tt>. The value of
708<tt>&lt;ref&gt;</tt> must be a valid refname in Git. As <tt>LF</tt> is not valid in
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]709a Git refname, no quoting or escaping syntax is supported here.</p></div>
710<div class="para"><p>A <tt>mark</tt> command may optionally appear, requesting fast-import to save a
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]711reference to the newly created commit for future use by the frontend
712(see below for format). It is very common for frontends to mark
713every commit they create, thereby allowing future branch creation
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]714from any imported commit.</p></div>
715<div class="para"><p>The <tt>data</tt> command following <tt>committer</tt> must supply the commit
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]716message (see below for <tt>data</tt> command syntax). To import an empty
717commit message use a 0 length data. Commit messages are free-form
718and are not interpreted by Git. Currently they must be encoded in
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]719UTF-8, as fast-import does not permit other encodings to be specified.</p></div>
720<div class="para"><p>Zero or more <tt>filemodify</tt>, <tt>filedelete</tt>, <tt>filecopy</tt>, <tt>filerename</tt>
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]721and <tt>filedeleteall</tt> commands
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]722may be included to update the contents of the branch prior to
723creating the commit. These commands may be supplied in any order.
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]724However it is recommended that a <tt>filedeleteall</tt> command precede
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]725all <tt>filemodify</tt>, <tt>filecopy</tt> and <tt>filerename</tt> commands in the same
726commit, as <tt>filedeleteall</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]727wipes the branch clean (see below).</p></div>
728<div class="para"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
729<h4 id="_tt_author_tt"><tt>author</tt></h4>
730<div class="para"><p>An <tt>author</tt> command may optionally appear, if the author information
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]731might differ from the committer information. If <tt>author</tt> is omitted
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]732then fast-import will automatically use the committer's information for
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]733the author portion of the commit. See below for a description of
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]734the fields in <tt>author</tt>, as they are identical to <tt>committer</tt>.</p></div>
735<h4 id="_tt_committer_tt"><tt>committer</tt></h4>
736<div class="para"><p>The <tt>committer</tt> command indicates who made this commit, and when
737they made it.</p></div>
738<div class="para"><p>Here <tt>&lt;name&gt;</tt> is the person's display name (for example
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]739&#8220;Com M Itter&#8221;) and <tt>&lt;email&gt;</tt> is the person's email address
740(&#8220;cm@example.com&#8221;). <tt>LT</tt> and <tt>GT</tt> are the literal less-than (\x3c)
741and greater-than (\x3e) symbols. These are required to delimit
742the email address from the other fields in the line. Note that
743<tt>&lt;name&gt;</tt> is free-form and may contain any sequence of bytes, except
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]744<tt>LT</tt> and <tt>LF</tt>. It is typically UTF-8 encoded.</p></div>
745<div class="para"><p>The time of the change is specified by <tt>&lt;when&gt;</tt> using the date format
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]746that was selected by the --date-format=&lt;fmt&gt; command line option.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]747See &#8220;Date Formats&#8221; above for the set of supported formats, and
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]748their syntax.</p></div>
749<h4 id="_tt_from_tt"><tt>from</tt></h4>
750<div class="para"><p>The <tt>from</tt> command is used to specify the commit to initialize
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]751this branch from. This revision will be the first ancestor of the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]752new commit.</p></div>
753<div class="para"><p>Omitting the <tt>from</tt> command in the first commit of a new branch
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]754will cause fast-import to create that commit with no ancestor. This
755tends to be desired only for the initial commit of a project.
Junio C Hamano25c0b702008-03-23 09:41:37[diff] [blame]756If the frontend creates all files from scratch when making a new
757branch, a <tt>merge</tt> command may be used instead of <tt>from</tt> to start
758the commit with an empty tree.
Junio C Hamano5dad0832007-02-13 05:16:23[diff] [blame]759Omitting the <tt>from</tt> command on existing branches is usually desired,
760as the current commit on that branch is automatically assumed to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]761be the first ancestor of the new commit.</p></div>
762<div class="para"><p>As <tt>LF</tt> is not valid in a Git refname or SHA-1 expression, no
763quoting or escaping syntax is supported within <tt>&lt;committish&gt;</tt>.</p></div>
764<div class="para"><p>Here <tt>&lt;committish&gt;</tt> is any of the following:</p></div>
765<div class="ilist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]766<li>
767<p>
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]768The name of an existing branch already in fast-import's internal branch
769 table. If fast-import doesn't know the name, its treated as a SHA-1
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]770 expression.
771</p>
772</li>
773<li>
774<p>
775A mark reference, <tt>:&lt;idnum&gt;</tt>, where <tt>&lt;idnum&gt;</tt> is the mark number.
776</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]777<div class="para"><p>The reason fast-import uses <tt>:</tt> to denote a mark reference is this character
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]778is not legal in a Git branch name. The leading <tt>:</tt> makes it easy
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]779to distinguish between the mark 42 (<tt>:42</tt>) and the branch 42 (<tt>42</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]780or <tt>refs/heads/42</tt>), or an abbreviated SHA-1 which happened to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]781consist only of base-10 digits.</p></div>
782<div class="para"><p>Marks must be declared (via <tt>mark</tt>) before they can be used.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]783</li>
784<li>
785<p>
786A complete 40 byte or abbreviated commit SHA-1 in hex.
787</p>
788</li>
789<li>
790<p>
791Any valid Git SHA-1 expression that resolves to a commit. See
792 &#8220;SPECIFYING REVISIONS&#8221; in <a href="git-rev-parse.html">git-rev-parse(1)</a> for details.
793</p>
794</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]795</ul></div>
796<div class="para"><p>The special case of restarting an incremental import from the
797current branch value should be written as:</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]798<div class="listingblock">
799<div class="content">
800<pre><tt> from refs/heads/branch^0</tt></pre>
801</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]802<div class="para"><p>The <tt>&#94;0</tt> suffix is necessary as fast-import does not permit a branch to
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]803start from itself, and the branch is created in memory before the
Junio C Hamano6926bef2007-06-16 09:54:05[diff] [blame]804<tt>from</tt> command is even read from the input. Adding <tt>&#94;0</tt> will force
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]805fast-import to resolve the commit through Git's revision parsing library,
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]806rather than its internal branch table, thereby loading in the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]807existing value of the branch.</p></div>
808<h4 id="_tt_merge_tt"><tt>merge</tt></h4>
809<div class="para"><p>Includes one additional ancestor commit. If the <tt>from</tt> command is
Junio C Hamano25c0b702008-03-23 09:41:37[diff] [blame]810omitted when creating a new branch, the first <tt>merge</tt> commit will be
811the first ancestor of the current commit, and the branch will start
812out with no files. An unlimited number of <tt>merge</tt> commands per
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]813commit are permitted by fast-import, thereby establishing an n-way merge.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]814However Git's other tools never create commits with more than 15
815additional ancestors (forming a 16-way merge). For this reason
816it is suggested that frontends do not use more than 15 <tt>merge</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]817commands per commit; 16, if starting a new, empty branch.</p></div>
818<div class="para"><p>Here <tt>&lt;committish&gt;</tt> is any of the commit specification expressions
819also accepted by <tt>from</tt> (see above).</p></div>
820<h4 id="_tt_filemodify_tt"><tt>filemodify</tt></h4>
821<div class="para"><p>Included in a <tt>commit</tt> command to add a new file or change the
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]822content of an existing file. This command has two different means
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]823of specifying the content of the file.</p></div>
824<div class="vlist"><dl>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]825<dt>
826External data format
827</dt>
828<dd>
829<p>
830 The data content for the file was already supplied by a prior
831 <tt>blob</tt> command. The frontend just needs to connect it.
832</p>
833<div class="literalblock">
834<div class="content">
835<pre><tt> 'M' SP &lt;mode&gt; SP &lt;dataref&gt; SP &lt;path&gt; LF</tt></pre>
836</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]837<div class="para"><p>Here <tt>&lt;dataref&gt;</tt> can be either a mark reference (<tt>:&lt;idnum&gt;</tt>)
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]838set by a prior <tt>blob</tt> command, or a full 40-byte SHA-1 of an
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]839existing Git blob object.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]840</dd>
841<dt>
842Inline data format
843</dt>
844<dd>
845<p>
846 The data content for the file has not been supplied yet.
847 The frontend wants to supply it as part of this modify
848 command.
849</p>
850<div class="literalblock">
851<div class="content">
852<pre><tt> 'M' SP &lt;mode&gt; SP 'inline' SP &lt;path&gt; LF
853 data</tt></pre>
854</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]855<div class="para"><p>See below for a detailed description of the <tt>data</tt> command.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]856</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]857</dl></div>
858<div class="para"><p>In both formats <tt>&lt;mode&gt;</tt> is the type of file entry, specified
859in octal. Git only supports the following modes:</p></div>
860<div class="ilist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]861<li>
862<p>
863<tt>100644</tt> or <tt>644</tt>: A normal (not-executable) file. The majority
864 of files in most projects use this mode. If in doubt, this is
865 what you want.
866</p>
867</li>
868<li>
869<p>
870<tt>100755</tt> or <tt>755</tt>: A normal, but executable, file.
871</p>
872</li>
873<li>
874<p>
875<tt>120000</tt>: A symlink, the content of the file will be the link target.
876</p>
877</li>
Junio C Hamano915cd9b2008-07-20 01:24:17[diff] [blame]878<li>
879<p>
880<tt>160000</tt>: A gitlink, SHA-1 of the object refers to a commit in
881 another repository. Git links can only be specified by SHA or through
882 a commit mark. They are used to implement submodules.
883</p>
884</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]885</ul></div>
886<div class="para"><p>In both formats <tt>&lt;path&gt;</tt> is the complete path of the file to be added
887(if not already existing) or modified (if already existing).</p></div>
888<div class="para"><p>A <tt>&lt;path&gt;</tt> string must use UNIX-style directory separators (forward
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]889slash <tt>/</tt>), may contain any byte other than <tt>LF</tt>, and must not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]890start with double quote (<tt>"</tt>).</p></div>
891<div class="para"><p>If an <tt>LF</tt> or double quote must be encoded into <tt>&lt;path&gt;</tt> shell-style
892quoting should be used, e.g. <tt>"path/with\n and \" in it"</tt>.</p></div>
893<div class="para"><p>The value of <tt>&lt;path&gt;</tt> must be in canonical form. That is it must not:</p></div>
894<div class="ilist"><ul>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]895<li>
896<p>
897contain an empty directory component (e.g. <tt>foo//bar</tt> is invalid),
898</p>
899</li>
900<li>
901<p>
Junio C Hamanoc51fede2007-03-12 07:29:20[diff] [blame]902end with a directory separator (e.g. <tt>foo/</tt> is invalid),
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]903</p>
904</li>
905<li>
906<p>
Junio C Hamanoc51fede2007-03-12 07:29:20[diff] [blame]907start with a directory separator (e.g. <tt>/foo</tt> is invalid),
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]908</p>
909</li>
910<li>
911<p>
912contain the special component <tt>.</tt> or <tt>..</tt> (e.g. <tt>foo/./bar</tt> and
913 <tt>foo/../bar</tt> are invalid).
914</p>
915</li>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]916</ul></div>
917<div class="para"><p>It is recommended that <tt>&lt;path&gt;</tt> always be encoded using UTF-8.</p></div>
918<h4 id="_tt_filedelete_tt"><tt>filedelete</tt></h4>
919<div class="para"><p>Included in a <tt>commit</tt> command to remove a file or recursively
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]920delete an entire directory from the branch. If the file or directory
921removal makes its parent directory empty, the parent directory will
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]922be automatically removed too. This cascades up the tree until the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]923first non-empty directory or the root is reached.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]924<div class="literalblock">
925<div class="content">
926<pre><tt> 'D' SP &lt;path&gt; LF</tt></pre>
927</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]928<div class="para"><p>here <tt>&lt;path&gt;</tt> is the complete path of the file or subdirectory to
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]929be removed from the branch.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]930See <tt>filemodify</tt> above for a detailed description of <tt>&lt;path&gt;</tt>.</p></div>
931<h4 id="_tt_filecopy_tt"><tt>filecopy</tt></h4>
932<div class="para"><p>Recursively copies an existing file or subdirectory to a different
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]933location within the branch. The existing file or directory must
934exist. If the destination exists it will be completely replaced
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]935by the content copied from the source.</p></div>
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]936<div class="literalblock">
937<div class="content">
938<pre><tt> 'C' SP &lt;path&gt; SP &lt;path&gt; LF</tt></pre>
939</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]940<div class="para"><p>here the first <tt>&lt;path&gt;</tt> is the source location and the second
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]941<tt>&lt;path&gt;</tt> is the destination. See <tt>filemodify</tt> above for a detailed
942description of what <tt>&lt;path&gt;</tt> may look like. To use a source path
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]943that contains SP the path must be quoted.</p></div>
944<div class="para"><p>A <tt>filecopy</tt> command takes effect immediately. Once the source
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]945location has been copied to the destination any future commands
946applied to the source location will not impact the destination of
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]947the copy.</p></div>
948<h4 id="_tt_filerename_tt"><tt>filerename</tt></h4>
949<div class="para"><p>Renames an existing file or subdirectory to a different location
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]950within the branch. The existing file or directory must exist. If
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]951the destination exists it will be replaced by the source directory.</p></div>
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]952<div class="literalblock">
953<div class="content">
954<pre><tt> 'R' SP &lt;path&gt; SP &lt;path&gt; LF</tt></pre>
955</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]956<div class="para"><p>here the first <tt>&lt;path&gt;</tt> is the source location and the second
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]957<tt>&lt;path&gt;</tt> is the destination. See <tt>filemodify</tt> above for a detailed
958description of what <tt>&lt;path&gt;</tt> may look like. To use a source path
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]959that contains SP the path must be quoted.</p></div>
960<div class="para"><p>A <tt>filerename</tt> command takes effect immediately. Once the source
Junio C Hamano06216df2007-07-10 07:49:37[diff] [blame]961location has been renamed to the destination any future commands
962applied to the source location will create new files there and not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]963impact the destination of the rename.</p></div>
964<div class="para"><p>Note that a <tt>filerename</tt> is the same as a <tt>filecopy</tt> followed by a
Junio C Hamanoc0ea7c62007-07-15 07:19:06[diff] [blame]965<tt>filedelete</tt> of the source location. There is a slight performance
966advantage to using <tt>filerename</tt>, but the advantage is so small
967that it is never worth trying to convert a delete/add pair in
968source material into a rename for fast-import. This <tt>filerename</tt>
969command is provided just to simplify frontends that already have
970rename information and don't want bother with decomposing it into a
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]971<tt>filecopy</tt> followed by a <tt>filedelete</tt>.</p></div>
972<h4 id="_tt_filedeleteall_tt"><tt>filedeleteall</tt></h4>
973<div class="para"><p>Included in a <tt>commit</tt> command to remove all files (and also all
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]974directories) from the branch. This command resets the internal
975branch structure to have no files in it, allowing the frontend
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]976to subsequently add all interesting files from scratch.</p></div>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]977<div class="literalblock">
978<div class="content">
979<pre><tt> 'deleteall' LF</tt></pre>
980</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]981<div class="para"><p>This command is extremely useful if the frontend does not know
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]982(or does not care to know) what files are currently on the branch,
983and therefore cannot generate the proper <tt>filedelete</tt> commands to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]984update the content.</p></div>
985<div class="para"><p>Issuing a <tt>filedeleteall</tt> followed by the needed <tt>filemodify</tt>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]986commands to set the correct content will produce the same results
987as sending only the needed <tt>filemodify</tt> and <tt>filedelete</tt> commands.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]988The <tt>filedeleteall</tt> approach may however require fast-import to use slightly
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]989more memory per active branch (less than 1 MiB for even most large
990projects); so frontends that can easily obtain only the affected
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]991paths for a commit are encouraged to do so.</p></div>
992<h3 id="_tt_mark_tt"><tt>mark</tt></h3><div style="clear:left"></div>
993<div class="para"><p>Arranges for fast-import to save a reference to the current object, allowing
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]994the frontend to recall this object at a future point in time, without
995knowing its SHA-1. Here the current object is the object creation
996command the <tt>mark</tt> command appears within. This can be <tt>commit</tt>,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]997<tt>tag</tt>, and <tt>blob</tt>, but <tt>commit</tt> is the most common usage.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]998<div class="literalblock">
999<div class="content">
1000<pre><tt> 'mark' SP ':' &lt;idnum&gt; LF</tt></pre>
1001</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1002<div class="para"><p>where <tt>&lt;idnum&gt;</tt> is the number assigned by the frontend to this mark.
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1003The value of <tt>&lt;idnum&gt;</tt> is expressed as an ASCII decimal integer.
1004The value 0 is reserved and cannot be used as
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1005a mark. Only values greater than or equal to 1 may be used as marks.</p></div>
1006<div class="para"><p>New marks are created automatically. Existing marks can be moved
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1007to another object simply by reusing the same <tt>&lt;idnum&gt;</tt> in another
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1008<tt>mark</tt> command.</p></div>
1009<h3 id="_tt_tag_tt"><tt>tag</tt></h3><div style="clear:left"></div>
1010<div class="para"><p>Creates an annotated tag referring to a specific commit. To create
1011lightweight (non-annotated) tags see the <tt>reset</tt> command below.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1012<div class="literalblock">
1013<div class="content">
1014<pre><tt> 'tag' SP &lt;name&gt; LF
1015 'from' SP &lt;committish&gt; LF
1016 'tagger' SP &lt;name&gt; SP LT &lt;email&gt; GT SP &lt;when&gt; LF
Junio C Hamanoea5dae62007-05-10 23:25:08[diff] [blame]1017 data</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1018</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1019<div class="para"><p>where <tt>&lt;name&gt;</tt> is the name of the tag to create.</p></div>
1020<div class="para"><p>Tag names are automatically prefixed with <tt>refs/tags/</tt> when stored
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1021in Git, so importing the CVS branch symbol <tt>RELENG-1_0-FINAL</tt> would
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1022use just <tt>RELENG-1_0-FINAL</tt> for <tt>&lt;name&gt;</tt>, and fast-import will write the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1023corresponding ref as <tt>refs/tags/RELENG-1_0-FINAL</tt>.</p></div>
1024<div class="para"><p>The value of <tt>&lt;name&gt;</tt> must be a valid refname in Git and therefore
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1025may contain forward slashes. As <tt>LF</tt> is not valid in a Git refname,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1026no quoting or escaping syntax is supported here.</p></div>
1027<div class="para"><p>The <tt>from</tt> command is the same as in the <tt>commit</tt> command; see
1028above for details.</p></div>
1029<div class="para"><p>The <tt>tagger</tt> command uses the same format as <tt>committer</tt> within
1030<tt>commit</tt>; again see above for details.</p></div>
1031<div class="para"><p>The <tt>data</tt> command following <tt>tagger</tt> must supply the annotated tag
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1032message (see below for <tt>data</tt> command syntax). To import an empty
1033tag message use a 0 length data. Tag messages are free-form and are
1034not interpreted by Git. Currently they must be encoded in UTF-8,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1035as fast-import does not permit other encodings to be specified.</p></div>
1036<div class="para"><p>Signing annotated tags during import from within fast-import is not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1037supported. Trying to include your own PGP/GPG signature is not
1038recommended, as the frontend does not (easily) have access to the
1039complete set of bytes which normally goes into such a signature.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1040If signing is required, create lightweight tags from within fast-import with
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1041<tt>reset</tt>, then create the annotated versions of those tags offline
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1042with the standard <em>git-tag</em> process.</p></div>
1043<h3 id="_tt_reset_tt"><tt>reset</tt></h3><div style="clear:left"></div>
1044<div class="para"><p>Creates (or recreates) the named branch, optionally starting from
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1045a specific revision. The reset command allows a frontend to issue
1046a new <tt>from</tt> command for an existing branch, or to create a new
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1047branch from an existing commit without creating a new commit.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1048<div class="literalblock">
1049<div class="content">
1050<pre><tt> 'reset' SP &lt;ref&gt; LF
1051 ('from' SP &lt;committish&gt; LF)?
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1052 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1053</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1054<div class="para"><p>For a detailed description of <tt>&lt;ref&gt;</tt> and <tt>&lt;committish&gt;</tt> see above
1055under <tt>commit</tt> and <tt>from</tt>.</p></div>
1056<div class="para"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
1057<div class="para"><p>The <tt>reset</tt> command can also be used to create lightweight
1058(non-annotated) tags. For example:</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1059<div class="exampleblock">
1060<div class="exampleblock-content">
1061<div class="literalblock">
1062<div class="content">
1063<pre><tt>reset refs/tags/938
1064from :938</tt></pre>
1065</div></div>
1066</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1067<div class="para"><p>would create the lightweight tag <tt>refs/tags/938</tt> referring to
1068whatever commit mark <tt>:938</tt> references.</p></div>
1069<h3 id="_tt_blob_tt"><tt>blob</tt></h3><div style="clear:left"></div>
1070<div class="para"><p>Requests writing one file revision to the packfile. The revision
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1071is not connected to any commit; this connection must be formed in
1072a subsequent <tt>commit</tt> command by referencing the blob through an
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1073assigned mark.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1074<div class="literalblock">
1075<div class="content">
1076<pre><tt> 'blob' LF
1077 mark?
1078 data</tt></pre>
1079</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1080<div class="para"><p>The mark command is optional here as some frontends have chosen
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1081to generate the Git SHA-1 for the blob on their own, and feed that
1082directly to <tt>commit</tt>. This is typically more work than its worth
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1083however, as marks are inexpensive to store and easy to use.</p></div>
1084<h3 id="_tt_data_tt"><tt>data</tt></h3><div style="clear:left"></div>
1085<div class="para"><p>Supplies raw data (for use as blob/file content, commit messages, or
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1086annotated tag messages) to fast-import. Data can be supplied using an exact
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1087byte count or delimited with a terminating line. Real frontends
1088intended for production-quality conversions should always use the
1089exact byte count format, as it is more robust and performs better.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1090The delimited format is intended primarily for testing fast-import.</p></div>
1091<div class="para"><p>Comment lines appearing within the <tt>&lt;raw&gt;</tt> part of <tt>data</tt> commands
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1092are always taken to be part of the body of the data and are therefore
1093never ignored by fast-import. This makes it safe to import any
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1094file/message content whose lines might start with <tt>#</tt>.</p></div>
1095<div class="vlist"><dl>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1096<dt>
1097Exact byte count format
1098</dt>
1099<dd>
1100<p>
1101 The frontend must specify the number of bytes of data.
1102</p>
1103<div class="literalblock">
1104<div class="content">
1105<pre><tt> 'data' SP &lt;count&gt; LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1106 &lt;raw&gt; LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1107</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1108<div class="para"><p>where <tt>&lt;count&gt;</tt> is the exact number of bytes appearing within
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1109<tt>&lt;raw&gt;</tt>. The value of <tt>&lt;count&gt;</tt> is expressed as an ASCII decimal
1110integer. The <tt>LF</tt> on either side of <tt>&lt;raw&gt;</tt> is not
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1111included in <tt>&lt;count&gt;</tt> and will not be included in the imported data.</p></div>
1112<div class="para"><p>The <tt>LF</tt> after <tt>&lt;raw&gt;</tt> is optional (it used to be required) but
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1113recommended. Always including it makes debugging a fast-import
1114stream easier as the next command always starts in column 0
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1115of the next line, even if <tt>&lt;raw&gt;</tt> did not end with an <tt>LF</tt>.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1116</dd>
1117<dt>
1118Delimited format
1119</dt>
1120<dd>
1121<p>
1122 A delimiter string is used to mark the end of the data.
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1123 fast-import will compute the length by searching for the delimiter.
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1124 This format is primarily useful for testing and is not
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1125 recommended for real data.
1126</p>
1127<div class="literalblock">
1128<div class="content">
1129<pre><tt> 'data' SP '&lt;&lt;' &lt;delim&gt; LF
1130 &lt;raw&gt; LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1131 &lt;delim&gt; LF
1132 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1133</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1134<div class="para"><p>where <tt>&lt;delim&gt;</tt> is the chosen delimiter string. The string <tt>&lt;delim&gt;</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1135must not appear on a line by itself within <tt>&lt;raw&gt;</tt>, as otherwise
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1136fast-import will think the data ends earlier than it really does. The <tt>LF</tt>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1137immediately trailing <tt>&lt;raw&gt;</tt> is part of <tt>&lt;raw&gt;</tt>. This is one of
1138the limitations of the delimited format, it is impossible to supply
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1139a data chunk which does not have an LF as its last byte.</p></div>
1140<div class="para"><p>The <tt>LF</tt> after <tt>&lt;delim&gt; LF</tt> is optional (it used to be required).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1141</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1142</dl></div>
1143<h3 id="_tt_checkpoint_tt"><tt>checkpoint</tt></h3><div style="clear:left"></div>
1144<div class="para"><p>Forces fast-import to close the current packfile, start a new one, and to
1145save out all current branch refs, tags and marks.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1146<div class="literalblock">
1147<div class="content">
1148<pre><tt> 'checkpoint' LF
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1149 LF?</tt></pre>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1150</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1151<div class="para"><p>Note that fast-import automatically switches packfiles when the current
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1152packfile reaches --max-pack-size, or 4 GiB, whichever limit is
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1153smaller. During an automatic packfile switch fast-import does not update
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1154the branch refs, tags or marks.</p></div>
1155<div class="para"><p>As a <tt>checkpoint</tt> can require a significant amount of CPU time and
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1156disk IO (to compute the overall pack SHA-1 checksum, generate the
1157corresponding index file, and update the refs) it can easily take
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1158several minutes for a single <tt>checkpoint</tt> command to complete.</p></div>
1159<div class="para"><p>Frontends may choose to issue checkpoints during extremely large
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1160and long running imports, or when they need to allow another Git
1161process access to a branch. However given that a 30 GiB Subversion
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1162repository can be loaded into Git through fast-import in about 3 hours,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1163explicit checkpointing may not be necessary.</p></div>
1164<div class="para"><p>The <tt>LF</tt> after the command is optional (it used to be required).</p></div>
1165<h3 id="_tt_progress_tt"><tt>progress</tt></h3><div style="clear:left"></div>
1166<div class="para"><p>Causes fast-import to print the entire <tt>progress</tt> line unmodified to
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1167its standard output channel (file descriptor 1) when the command is
1168processed from the input stream. The command otherwise has no impact
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1169on the current import, or on any of fast-import's internal state.</p></div>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1170<div class="literalblock">
1171<div class="content">
1172<pre><tt> 'progress' SP &lt;any&gt; LF
1173 LF?</tt></pre>
1174</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1175<div class="para"><p>The <tt>&lt;any&gt;</tt> part of the command may contain any sequence of bytes
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1176that does not contain <tt>LF</tt>. The <tt>LF</tt> after the command is optional.
1177Callers may wish to process the output through a tool such as sed to
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1178remove the leading part of the line, for example:</p></div>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1179<div class="exampleblock">
1180<div class="exampleblock-content">
1181<div class="literalblock">
1182<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1183<pre><tt>frontend | git fast-import | sed 's/^progress //'</tt></pre>
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1184</div></div>
1185</div></div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1186<div class="para"><p>Placing a <tt>progress</tt> command immediately after a <tt>checkpoint</tt> will
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1187inform the reader when the <tt>checkpoint</tt> has been completed and it
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1188can safely access the refs that fast-import updated.</p></div>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1189</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1190<h2 id="_crash_reports">Crash Reports</h2>
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1191<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1192<div class="para"><p>If fast-import is supplied invalid input it will terminate with a
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1193non-zero exit status and create a crash report in the top level of
1194the Git repository it was importing into. Crash reports contain
1195a snapshot of the internal fast-import state as well as the most
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1196recent commands that lead up to the crash.</p></div>
1197<div class="para"><p>All recent commands (including stream comments, file changes and
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1198progress commands) are shown in the command history within the crash
1199report, but raw file data and commit messages are excluded from the
1200crash report. This exclusion saves space within the report file
1201and reduces the amount of buffering that fast-import must perform
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1202during execution.</p></div>
1203<div class="para"><p>After writing a crash report fast-import will close the current
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1204packfile and export the marks table. This allows the frontend
1205developer to inspect the repository state and resume the import from
1206the point where it crashed. The modified branches and tags are not
1207updated during a crash, as the import did not complete successfully.
1208Branch and tag information can be found in the crash report and
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1209must be applied manually if the update is needed.</p></div>
1210<div class="para"><p>An example crash:</p></div>
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1211<div class="exampleblock">
1212<div class="exampleblock-content">
1213<div class="literalblock">
1214<div class="content">
1215<pre><tt>$ cat &gt;in &lt;&lt;END_OF_INPUT
1216# my very first test commit
1217commit refs/heads/master
1218committer Shawn O. Pearce &lt;spearce&gt; 19283 -0400
1219# who is that guy anyway?
1220data &lt;&lt;EOF
1221this is my commit
1222EOF
1223M 644 inline .gitignore
1224data &lt;&lt;EOF
1225.gitignore
1226EOF
1227M 777 inline bob
1228END_OF_INPUT</tt></pre>
1229</div></div>
1230<div class="literalblock">
1231<div class="content">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]1232<pre><tt>$ git fast-import &lt;in
Junio C Hamano21391932008-02-16 10:02:54[diff] [blame]1233fatal: Corrupt mode: M 777 inline bob
1234fast-import: dumping crash report to .git/fast_import_crash_8434</tt></pre>
1235</div></div>
1236<div class="literalblock">
1237<div class="content">
1238<pre><tt>$ cat .git/fast_import_crash_8434
1239fast-import crash report:
1240 fast-import process: 8434
1241 parent process : 1391
1242 at Sat Sep 1 00:58:12 2007</tt></pre>
1243</div></div>
1244<div class="literalblock">
1245<div class="content">
1246<pre><tt>fatal: Corrupt mode: M 777 inline bob</tt></pre>
1247</div></div>
1248<div class="literalblock">
1249<div class="content">
1250<pre><tt>Most Recent Commands Before Crash
1251---------------------------------
1252 # my very first test commit
1253 commit refs/heads/master
1254 committer Shawn O. Pearce &lt;spearce&gt; 19283 -0400
1255 # who is that guy anyway?
1256 data &lt;&lt;EOF
1257 M 644 inline .gitignore
1258 data &lt;&lt;EOF
1259* M 777 inline bob</tt></pre>
1260</div></div>
1261<div class="literalblock">
1262<div class="content">
1263<pre><tt>Active Branch LRU
1264-----------------
1265 active_branches = 1 cur, 5 max</tt></pre>
1266</div></div>
1267<div class="literalblock">
1268<div class="content">
1269<pre><tt>pos clock name
1270~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1271 1) 0 refs/heads/master</tt></pre>
1272</div></div>
1273<div class="literalblock">
1274<div class="content">
1275<pre><tt>Inactive Branches
1276-----------------
1277refs/heads/master:
1278 status : active loaded dirty
1279 tip commit : 0000000000000000000000000000000000000000
1280 old tree : 0000000000000000000000000000000000000000
1281 cur tree : 0000000000000000000000000000000000000000
1282 commit clock: 0
1283 last pack :</tt></pre>
1284</div></div>
1285<div class="literalblock">
1286<div class="content">
1287<pre><tt>-------------------
1288END OF CRASH REPORT</tt></pre>
1289</div></div>
1290</div></div>
1291</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1292<h2 id="_tips_and_tricks">Tips and Tricks</h2>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1293<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1294<div class="para"><p>The following tips and tricks have been collected from various
1295users of fast-import, and are offered here as suggestions.</p></div>
1296<h3 id="_use_one_mark_per_commit">Use One Mark Per Commit</h3><div style="clear:left"></div>
1297<div class="para"><p>When doing a repository conversion, use a unique mark per commit
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1298(<tt>mark :&lt;n&gt;</tt>) and supply the --export-marks option on the command
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1299line. fast-import will dump a file which lists every mark and the Git
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1300object SHA-1 that corresponds to it. If the frontend can tie
1301the marks back to the source repository, it is easy to verify the
1302accuracy and completeness of the import by comparing each Git
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1303commit to the corresponding source revision.</p></div>
1304<div class="para"><p>Coming from a system such as Perforce or Subversion this should be
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1305quite simple, as the fast-import mark can also be the Perforce changeset
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1306number or the Subversion revision number.</p></div>
1307<h3 id="_freely_skip_around_branches">Freely Skip Around Branches</h3><div style="clear:left"></div>
1308<div class="para"><p>Don't bother trying to optimize the frontend to stick to one branch
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1309at a time during an import. Although doing so might be slightly
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1310faster for fast-import, it tends to increase the complexity of the frontend
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1311code considerably.</p></div>
1312<div class="para"><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]1313cost of activating an inactive branch is so low that bouncing around
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1314between branches has virtually no impact on import performance.</p></div>
1315<h3 id="_handling_renames">Handling Renames</h3><div style="clear:left"></div>
1316<div class="para"><p>When importing a renamed file or directory, simply delete the old
Junio C Hamano9dd8bb02007-02-12 07:15:35[diff] [blame]1317name(s) and modify the new name(s) during the corresponding commit.
1318Git performs rename detection after-the-fact, rather than explicitly
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1319during a commit.</p></div>
1320<h3 id="_use_tag_fixup_branches">Use Tag Fixup Branches</h3><div style="clear:left"></div>
1321<div class="para"><p>Some other SCM systems let the user create a tag from multiple
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1322files which are not from the same commit/changeset. Or to create
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1323tags which are a subset of the files available in the repository.</p></div>
1324<div class="para"><p>Importing these tags as-is in Git is impossible without making at
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1325least one commit which &#8220;fixes up&#8221; the files to match the content
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1326of the tag. Use fast-import's <tt>reset</tt> command to reset a dummy branch
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1327outside of your normal branch space to the base commit for the tag,
1328then commit one or more file fixup commits, and finally tag the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1329dummy branch.</p></div>
1330<div class="para"><p>For example since all normal branches are stored under <tt>refs/heads/</tt>
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1331name the tag fixup branch <tt>TAG_FIXUP</tt>. This way it is impossible for
1332the fixup branch used by the importer to have namespace conflicts
1333with real branches imported from the source (the name <tt>TAG_FIXUP</tt>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1334is not <tt>refs/heads/TAG_FIXUP</tt>).</p></div>
1335<div class="para"><p>When committing fixups, consider using <tt>merge</tt> to connect the
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1336commit(s) which are supplying file revisions to the fixup branch.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1337Doing so will allow tools such as <em>git-blame</em> to track
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1338through the real commit history and properly annotate the source
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1339files.</p></div>
1340<div class="para"><p>After fast-import terminates the frontend will need to do <tt>rm .git/TAG_FIXUP</tt>
1341to remove the dummy branch.</p></div>
1342<h3 id="_import_now_repack_later">Import Now, Repack Later</h3><div style="clear:left"></div>
1343<div class="para"><p>As soon as fast-import completes the Git repository is completely valid
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1344and ready for use. Typically this takes only a very short time,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1345even for considerably large projects (100,000+ commits).</p></div>
1346<div class="para"><p>However repacking the repository is necessary to improve data
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1347locality and access performance. It can also take hours on extremely
1348large projects (especially if -f and a large --window parameter is
1349used). Since repacking is safe to run alongside readers and writers,
1350run the repack in the background and let it finish when it finishes.
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1351There is no reason to wait to explore your new Git project!</p></div>
1352<div class="para"><p>If you choose to wait for the repack, don't try to run benchmarks
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1353or performance tests until repacking is completed. fast-import outputs
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1354suboptimal packfiles that are simply never seen in real use
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1355situations.</p></div>
1356<h3 id="_repacking_historical_data">Repacking Historical Data</h3><div style="clear:left"></div>
1357<div class="para"><p>If you are repacking very old imported data (e.g. older than the
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1358last year), consider expending some extra CPU time and supplying
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1359--window=50 (or higher) when you run <em>git-repack</em>.
Junio C Hamanodfc4ce72007-02-07 23:17:29[diff] [blame]1360This will take longer, but will also produce a smaller packfile.
1361You only need to expend the effort once, and everyone using your
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1362project will benefit from the smaller repository.</p></div>
1363<h3 id="_include_some_progress_messages">Include Some Progress Messages</h3><div style="clear:left"></div>
1364<div class="para"><p>Every once in a while have your frontend emit a <tt>progress</tt> message
Junio C Hamanoe52cf782007-08-19 19:15:52[diff] [blame]1365to fast-import. The contents of the messages are entirely free-form,
1366so one suggestion would be to output the current month and year
1367each time the current commit date moves into the next month.
1368Your users will feel better knowing how much of the data stream
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1369has been processed.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1370</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1371<h2 id="_packfile_optimization">Packfile Optimization</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1372<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1373<div class="para"><p>When packing a blob fast-import always attempts to deltify against the last
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1374blob written. Unless specifically arranged for by the frontend,
1375this will probably not be a prior version of the same file, so the
1376generated delta will not be the smallest possible. The resulting
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1377packfile will be compressed, but will not be optimal.</p></div>
1378<div class="para"><p>Frontends which have efficient access to all revisions of a
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1379single file (for example reading an RCS/CVS ,v file) can choose
1380to supply all revisions of that file as a sequence of consecutive
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1381<tt>blob</tt> commands. This allows fast-import to deltify the different file
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1382revisions against each other, saving space in the final packfile.
1383Marks can be used to later identify individual file revisions during
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1384a sequence of <tt>commit</tt> commands.</p></div>
1385<div class="para"><p>The packfile(s) created by fast-import do not encourage good disk access
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1386patterns. This is caused by fast-import writing the data in the order
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1387it is received on standard input, while Git typically organizes
1388data within packfiles to make the most recent (current tip) data
1389appear before historical data. Git also clusters commits together,
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1390speeding up revision traversal through better cache locality.</p></div>
1391<div class="para"><p>For this reason it is strongly recommended that users repack the
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1392repository with <tt>git repack -a -d</tt> after fast-import completes, allowing
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1393Git to reorganize the packfiles for faster data access. If blob
1394deltas are suboptimal (see above) then also adding the <tt>-f</tt> option
1395to force recomputation of all deltas can significantly reduce the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1396final packfile size (30-50% smaller can be quite typical).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1397</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1398<h2 id="_memory_utilization">Memory Utilization</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1399<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1400<div class="para"><p>There are a number of factors which affect how much memory fast-import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1401requires to perform an import. Like critical sections of core
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1402Git, fast-import uses its own memory allocators to amortize any overheads
1403associated with malloc. In practice fast-import tends to amortize any
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1404malloc overheads to 0, due to its use of large block allocations.</p></div>
1405<h3 id="_per_object">per object</h3><div style="clear:left"></div>
1406<div class="para"><p>fast-import maintains an in-memory structure for every object written in
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1407this execution. On a 32 bit system the structure is 32 bytes,
1408on a 64 bit system the structure is 40 bytes (due to the larger
1409pointer sizes). Objects in the table are not deallocated until
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1410fast-import terminates. Importing 2 million objects on a 32 bit system
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1411will require approximately 64 MiB of memory.</p></div>
1412<div class="para"><p>The object table is actually a hashtable keyed on the object name
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1413(the unique SHA-1). This storage configuration allows fast-import to reuse
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1414an existing or already written object and avoid writing duplicates
1415to the output packfile. Duplicate blobs are surprisingly common
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1416in an import, typically due to branch merges in the source.</p></div>
1417<h3 id="_per_mark">per mark</h3><div style="clear:left"></div>
1418<div class="para"><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]1419bytes, depending on pointer size) per mark. Although the array
1420is sparse, frontends are still strongly encouraged to use marks
1421between 1 and n, where n is the total number of marks required for
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1422this import.</p></div>
1423<h3 id="_per_branch">per branch</h3><div style="clear:left"></div>
1424<div class="para"><p>Branches are classified as active and inactive. The memory usage
1425of the two classes is significantly different.</p></div>
1426<div class="para"><p>Inactive branches are stored in a structure which uses 96 or 120
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1427bytes (32 bit or 64 bit systems, respectively), plus the length of
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1428the branch name (typically under 200 bytes), per branch. fast-import will
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1429easily handle as many as 10,000 inactive branches in under 2 MiB
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1430of memory.</p></div>
1431<div class="para"><p>Active branches have the same overhead as inactive branches, but
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1432also contain copies of every tree that has been recently modified on
1433that branch. If subtree <tt>include</tt> has not been modified since the
1434branch became active, its contents will not be loaded into memory,
1435but if subtree <tt>src</tt> has been modified by a commit since the branch
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1436became active, then its contents will be loaded in memory.</p></div>
1437<div class="para"><p>As active branches store metadata about the files contained on that
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1438branch, their in-memory storage size can grow to a considerable size
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1439(see below).</p></div>
1440<div class="para"><p>fast-import automatically moves active branches to inactive status based on
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1441a simple least-recently-used algorithm. The LRU chain is updated on
1442each <tt>commit</tt> command. The maximum number of active branches can be
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1443increased or decreased on the command line with --active-branches=.</p></div>
1444<h3 id="_per_active_tree">per active tree</h3><div style="clear:left"></div>
1445<div class="para"><p>Trees (aka directories) use just 12 bytes of memory on top of the
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1446memory required for their entries (see &#8220;per active file&#8221; below).
Junio C Hamanoa6387422007-08-25 03:54:27[diff] [blame]1447The cost of a tree is virtually 0, as its overhead amortizes out
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1448over the individual file entries.</p></div>
1449<h3 id="_per_active_file_entry">per active file entry</h3><div style="clear:left"></div>
1450<div class="para"><p>Files (and pointers to subtrees) within active trees require 52 or 64
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1451bytes (32/64 bit platforms) per entry. To conserve space, file and
1452tree names are pooled in a common string table, allowing the filename
1453&#8220;Makefile&#8221; to use just 16 bytes (after including the string header
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1454overhead) no matter how many times it occurs within the project.</p></div>
1455<div class="para"><p>The active branch LRU, when coupled with the filename string pool
Junio C Hamanod3339982007-02-09 08:38:48[diff] [blame]1456and lazy loading of subtrees, allows fast-import to efficiently import
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1457projects with 2,000+ branches and 45,114+ files in a very limited
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1458memory footprint (less than 2.7 MiB per active branch).</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1459</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1460<h2 id="_author">Author</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1461<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1462<div class="para"><p>Written by Shawn O. Pearce &lt;spearce@spearce.org&gt;.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1463</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1464<h2 id="_documentation">Documentation</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1465<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1466<div class="para"><p>Documentation by Shawn O. Pearce &lt;spearce@spearce.org&gt;.</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1467</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1468<h2 id="_git">GIT</h2>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1469<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]1470<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1471</div>
1472<div id="footer">
1473<div id="footer-text">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]1474Last updated 2008-09-19 06:32:53 UTC
Junio C Hamanodf60f442007-02-07 05:52:37[diff] [blame]1475</div>
1476</div>
1477</body>
1478</html>