diff options
Diffstat (limited to 'Documentation/git-fast-import.txt')
| -rw-r--r-- | Documentation/git-fast-import.txt | 74 |
1 files changed, 62 insertions, 12 deletions
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index ec6ef31197..68bca1a29d 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -39,6 +39,10 @@ OPTIONS 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,9 +102,10 @@ OPTIONS options. --cat-blob-fd=<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 <fd> 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. @@ -422,7 +427,7 @@ they made it. Here `<name>` is the person's display name (for example ``Com M Itter'') and `<email>` is the person's email address -(``cm@example.com''). `LT` and `GT` are the literal less-than (\x3c) +(``\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 `<name>` and `<email>` are free-form and may contain any sequence @@ -437,7 +442,9 @@ their syntax. ^^^^^^ The `from` command is used to specify the commit to initialize this branch from. This revision will be the first ancestor of the -new commit. +new commit. The state of the tree built at this commit will begin +with the state at the `from` commit, and be altered by the content +modifications in this commit. Omitting the `from` command in the first commit of a new branch will cause fast-import to create that commit with no ancestor. This @@ -478,16 +485,18 @@ current branch value should be written as: ---- 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. `merge` ^^^^^^^ -Includes one additional ancestor commit. If the `from` command is +Includes one additional ancestor commit. The additional ancestry +link does not change the way the tree state is built at this commit. +If the `from` command is omitted when creating a new branch, the first `merge` commit will be the first ancestor of the current commit, and the branch will start out with no files. An unlimited number of `merge` commands per @@ -553,8 +562,12 @@ A `<path>` string must use UNIX-style directory separators (forward slash `/`), may contain any byte other than `LF`, and must not start with double quote (`"`). -If an `LF` or double quote must be encoded into `<path>` shell-style -quoting should be used, e.g. `"path/with\n and \" in it"`. +A path can use C-style string quoting; this is accepted in all cases +and mandatory if the filename starts with double quote or contains +`LF`. In C-style quoting, the complete name should be surrounded with +double quotes, and any `LF`, backslash, or double quote characters +must be escaped by preceding them with a backslash (e.g., +`"path/with\n, \\ and \" in it"`). The value of `<path>` must be in canonical form. That is it must not: @@ -942,6 +955,9 @@ This command can be used anywhere in the stream that comments are 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 @@ -975,7 +991,7 @@ Reading from a named tree:: See `filemodify` above for a detailed description of `<path>`. -Output uses the same format as `git ls-tree <tree> {litdd} <path>`: +Output uses the same format as `git ls-tree <tree> -- <path>`: ==== <mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF @@ -991,6 +1007,9 @@ instead report missing SP <path> 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 @@ -1040,7 +1059,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` ~~~~~~~~ @@ -1079,6 +1100,35 @@ If the `--done` command line option or `feature done` command is 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 | + git fast-import >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 |