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