Documentation: add caveats about I/O buffering for check-{attr,ignore}
check-attr and check-ignore have the potential to deadlock callers which do not read back the output in real-time. For example, if a caller writes N paths out and then reads N lines back in, it risks becoming blocked on write() to check-*, and check-* is blocked on write back to the caller. Somebody has to buffer; the pipe buffers provide some leeway, but they are limited. Thanks to Peff for pointing this out: http://article.gmane.org/gmane.comp.version-control.git/220534 Signed-off-by: Adam Spiers <git@adamspiers.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adam Spiers committed
Apr 11, 2013 at 13:05 UTC
f1ed7fea7974218db15155f3b8d2e29d3fe0971c
3 files changed
+13
-2
Documentation/git-check-attr.txt
+5
@@ -56,6 +56,11 @@ being queried and <info> can be either:
56
'set';; when the attribute is defined as true.
57
<value>;; when a value has been assigned to the attribute.
58
59
+Buffering happens as documented under the `GIT_FLUSH` option in
60
+linkgit:git[1]. The caller is responsible for avoiding deadlocks
61
+caused by overfilling an input buffer or reading from an empty output
62
+buffer.
63
+
64
EXAMPLES
65
--------
66
Documentation/git-check-ignore.txt
+5
@@ -81,6 +81,11 @@ not. (Without this option, it would be impossible to tell whether the
81
absence of output for a given file meant that it didn't match any
82
pattern, or that the output hadn't been generated yet.)
83
84
+Buffering happens as documented under the `GIT_FLUSH` option in
85
+linkgit:git[1]. The caller is responsible for avoiding deadlocks
86
+caused by overfilling an input buffer or reading from an empty output
87
+buffer.
88
+
89
EXIT STATUS
90
-----------
91
Documentation/git.txt
+3
-2
@@ -771,8 +771,9 @@ for further details.
771
'GIT_FLUSH'::
772
If this environment variable is set to "1", then commands such
773
as 'git blame' (in incremental mode), 'git rev-list', 'git log',
774
- and 'git whatchanged' will force a flush of the output stream
775
- after each commit-oriented record have been flushed. If this
774
+ 'git check-attr', 'git check-ignore', and 'git whatchanged' will
775
+ force a flush of the output stream after each record have been
776
+ flushed. If this
777
variable is set to "0", the output of these commands will be done
778
using completely buffered I/O. If this environment variable is
779
not set, git will choose buffered or record-oriented flushing