From: Junio C Hamano Date: Tue, 18 Sep 2012 21:33:52 +0000 (-0700) Subject: Merge branch 'er/doc-fast-import-done' into maint X-Git-Tag: v1.7.12.1~1 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/39e2e020608716e8710ff391e0d2b6d035cb3dd6?ds=inline;hp=-c Merge branch 'er/doc-fast-import-done' into maint * er/doc-fast-import-done: fast-import: document the --done option --- 39e2e020608716e8710ff391e0d2b6d035cb3dd6 diff --combined Documentation/git-fast-import.txt index 2620d28b4b,3e7e62057e..6603a7ab73 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@@ -8,7 -8,6 +8,7 @@@ git-fast-import - Backend for fast Git SYNOPSIS -------- +[verse] frontend | 'git fast-import' [options] DESCRIPTION @@@ -39,6 -38,10 +39,10 @@@ OPTION See ``Date Formats'' below for details about which formats are supported, and their syntax. + -- done:: + Terminate with error if there is no 'done' command at the + end of the stream. + --force:: Force updating modified existing branches, even if doing so would cause commits to be lost (as the new commit does @@@ -98,10 -101,9 +102,10 @@@ options. --cat-blob-fd=:: - Specify the file descriptor that will be written to - when the `cat-blob` command is encountered in the stream. - The default behaviour is to write to `stdout`. + Write responses to `cat-blob` and `ls` queries to the + file descriptor instead of `stdout`. Allows `progress` + output intended for the end-user to be separated from other + output. --done:: Require a `done` command at the end of the stream. @@@ -426,8 -428,8 +430,8 @@@ Here `` is the person's display n (``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) and greater-than (\x3e) symbols. These are required to delimit the email address from the other fields in the line. Note that -`` is free-form and may contain any sequence of bytes, except -`LT` and `LF`. It is typically UTF-8 encoded. +`` and `` are free-form and may contain any sequence +of bytes, except `LT`, `GT` and `LF`. `` is typically UTF-8 encoded. The time of the change is specified by `` using the date format that was selected by the \--date-format= command line option. @@@ -479,9 -481,9 +483,9 @@@ current branch value should be written ---- from refs/heads/branch^0 ---- -The `{caret}0` suffix is necessary as fast-import does not permit a branch to +The `^0` suffix is necessary as fast-import does not permit a branch to start from itself, and the branch is created in memory before the -`from` command is even read from the input. Adding `{caret}0` will force +`from` command is even read from the input. Adding `^0` will force fast-import to resolve the commit through Git's revision parsing library, rather than its internal branch table, thereby loading in the existing value of the branch. @@@ -661,14 -663,9 +665,14 @@@ paths for a commit are encouraged to d `notemodify` ^^^^^^^^^^^^ -Included in a `commit` command to add a new note (annotating a given -commit) or change the content of an existing note. This command has -two different means of specifying the content of the note. +Included in a `commit` `` command to add a new note +annotating a `` or change this annotation contents. +Internally it is similar to filemodify 100644 on `` +path (maybe split into subdirectories). It's not advised to +use any other commands to write to the `` tree except +`filedeleteall` to delete all existing notes in this tree. +This command has two different means of specifying the content +of the note. External data format:: The data content for the note was already supplied by a prior @@@ -943,9 -940,6 +947,9 @@@ This command can be used anywhere in th accepted. In particular, the `cat-blob` command can be used in the middle of a commit but not in the middle of a `data` command. +See ``Responses To Commands'' below for details about how to read +this output safely. + `ls` ~~~~ Prints information about the object at a path to a file descriptor @@@ -979,7 -973,7 +983,7 @@@ Reading from a named tree: See `filemodify` above for a detailed description of ``. -Output uses the same format as `git ls-tree {litdd} `: +Output uses the same format as `git ls-tree -- `: ==== SP ('blob' | 'tree' | 'commit') SP HT LF @@@ -995,9 -989,6 +999,9 @@@ instead repor missing SP LF ==== +See ``Responses To Commands'' below for details about how to read +this output safely. + `feature` ~~~~~~~~~ Require that fast-import supports the specified feature, or abort if @@@ -1019,14 -1010,10 +1023,14 @@@ force: (see OPTIONS, above). import-marks:: +import-marks-if-exists:: Like --import-marks except in two respects: first, only one - "feature import-marks" command is allowed per stream; - second, an --import-marks= command-line option overrides - any "feature import-marks" command in the stream. + "feature import-marks" or "feature import-marks-if-exists" + command is allowed per stream; second, an --import-marks= + or --import-marks-if-exists command-line option overrides + any of these "feature" commands in the stream; third, + "feature import-marks-if-exists" like a corresponding + command-line option silently skips a nonexistent file. cat-blob:: ls:: @@@ -1047,7 -1034,9 +1051,9 @@@ done: Error out if the stream ends without a 'done' command. Without this feature, errors causing the frontend to end abruptly at a convenient point in the stream can go - undetected. + undetected. This may occur, for example, if an import + front end dies in mid-operation without emitting SIGTERM + or SIGKILL at its subordinate git fast-import instance. `option` ~~~~~~~~ @@@ -1086,35 -1075,6 +1092,35 @@@ If the `--done` command line option or in use, the `done` command is mandatory and marks the end of the stream. +Responses To Commands +--------------------- +New objects written by fast-import are not available immediately. +Most fast-import commands have no visible effect until the next +checkpoint (or completion). The frontend can send commands to +fill fast-import's input pipe without worrying about how quickly +they will take effect, which improves performance by simplifying +scheduling. + +For some frontends, though, it is useful to be able to read back +data from the current repository as it is being updated (for +example when the source material describes objects in terms of +patches to be applied to previously imported objects). This can +be accomplished by connecting the frontend and fast-import via +bidirectional pipes: + +==== + mkfifo fast-import-output + frontend fast-import-output +==== + +A frontend set up this way can use `progress`, `ls`, and `cat-blob` +commands to read information from the import in progress. + +To avoid deadlock, such frontends must completely consume any +pending output from `progress`, `ls`, and `cat-blob` before +performing writes to fast-import that might block. + Crash Reports ------------- If fast-import is supplied invalid input it will terminate with a