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>
Jonathan Nieder committed
Apr 11, 2012 at 16:25 UTC
d57e490af31dff940052a5929fe05947c7ad03ad
1 file changed
+39
-3
Documentation/git-fast-import.txt
+39
-3
@@ -98,9 +98,10 @@ OPTIONS
98
options.
99
100
--cat-blob-fd=<fd>::
101
- Specify the file descriptor that will be written to
102
- when the `cat-blob` command is encountered in the stream.
103
- The default behaviour is to write to `stdout`.
101
+ Write responses to `cat-blob` and `ls` queries to the
102
+ file descriptor <fd> instead of `stdout`. Allows `progress`
103
+ output intended for the end-user to be separated from other
104
+ output.
105
106
--done::
107
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
943
accepted. In particular, the `cat-blob` command can be used in the
944
middle of a commit but not in the middle of a `data` command.
945
946
+See ``Responses To Commands'' below for details about how to read
947
+this output safely.
948
+
949
`ls`
950
~~~~
951
Prints information about the object at a path to a file descriptor
@@ -991,6 +995,9 @@ instead report
995
missing SP <path> LF
996
====
997
998
+See ``Responses To Commands'' below for details about how to read
999
+this output safely.
1000
+
1001
`feature`
1002
~~~~~~~~~
1003
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
1086
in use, the `done` command is mandatory and marks the end of the
1087
stream.
1088
1089
+Responses To Commands
1090
+---------------------
1091
+New objects written by fast-import are not available immediately.
1092
+Most fast-import commands have no visible effect until the next
1093
+checkpoint (or completion). The frontend can send commands to
1094
+fill fast-import's input pipe without worrying about how quickly
1095
+they will take effect, which improves performance by simplifying
1096
+scheduling.
1097
+
1098
+For some frontends, though, it is useful to be able to read back
1099
+data from the current repository as it is being updated (for
1100
+example when the source material describes objects in terms of
1101
+patches to be applied to previously imported objects). This can
1102
+be accomplished by connecting the frontend and fast-import via
1103
+bidirectional pipes:
1104
+
1105
+====
1106
+ mkfifo fast-import-output
1107
+ frontend <fast-import-output |
1108
+ git fast-import >fast-import-output
1109
+====
1110
+
1111
+A frontend set up this way can use `progress`, `ls`, and `cat-blob`
1112
+commands to read information from the import in progress.
1113
+
1114
+To avoid deadlock, such frontends must completely consume any
1115
+pending output from `progress`, `ls`, and `cat-blob` before
1116
+performing writes to fast-import that might block.
1117
+
1118
Crash Reports
1119
-------------
1120
If fast-import is supplied invalid input it will terminate with a