mirror of
https://github.com/git/git
synced 2024-08-25 02:35:46 +00:00
fast-import doc: cat-blob and ls responses need to be consumed quickly
If fast-import's command pipe and the frontend's cat-blob/ls response pipe are both filled, there can be a deadlock. Luckily all existing frontends consume any pending cat-blob/ls responses completely before writing the next command. Document the requirements so future frontend authors and users can be spared from the problem, too. It is not always easy to catch that kind of bug by testing. To set the scene, add some words of explanation to help the novice understand that "cat-blob" and "ls" output are meant for consumption by the frontend. Reported-by: Junio C Hamano <gitster@pobox.com> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
This commit is contained in:
parent
e8dde3e5f9
commit
d57e490af3
|
@ -98,9 +98,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.
|
||||
|
@ -942,6 +943,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
|
||||
|
@ -991,6 +995,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
|
||||
|
@ -1079,6 +1086,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
|
||||
|
|
Loading…
Reference in a new issue