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