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>

diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt
index 5abdbaa51cf58e216bbc63d28039a5abfba01669..a7be80d48bf6fd6928186116f00f3b48cf564041 100644 (file)
--- a/Documentation/git-check-attr.txt
+++ b/Documentation/git-check-attr.txt
@@ -56,6 +56,11 @@ being queried and <info> can be either:
 'set';;                when the attribute is defined as true.
 <value>;;      when a value has been assigned to the attribute.
 
 'set';;                when the attribute is defined as true.
 <value>;;      when a value has been assigned to the attribute.
 

+Buffering happens as documented under the `GIT_FLUSH` option in
+linkgit:git[1].  The caller is responsible for avoiding deadlocks
+caused by overfilling an input buffer or reading from an empty output
+buffer.
+

 EXAMPLES
 --------
 
 EXAMPLES
 --------
 

diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt
index 7e3cabc9dd0f75896471784ab48ab5b0e8cb4d4c..8e1f7ab7ea93af4b7c496efc2251469ed553a55f 100644 (file)
--- a/Documentation/git-check-ignore.txt
+++ b/Documentation/git-check-ignore.txt
@@ -81,6 +81,11 @@ not.  (Without this option, it would be impossible to tell whether the
 absence of output for a given file meant that it didn't match any
 pattern, or that the output hadn't been generated yet.)
 
 absence of output for a given file meant that it didn't match any
 pattern, or that the output hadn't been generated yet.)
 

+Buffering happens as documented under the `GIT_FLUSH` option in
+linkgit:git[1].  The caller is responsible for avoiding deadlocks
+caused by overfilling an input buffer or reading from an empty output
+buffer.
+

 EXIT STATUS
 -----------
 
 EXIT STATUS
 -----------
 

diff --git a/Documentation/git.txt b/Documentation/git.txt
index 65c37c4544f2bed6c979000e726ee5500f588ceb..122b33f0663a1fbd0b267102fa618d9e818a5c87 100644 (file)
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -771,8 +771,9 @@ for further details.
 'GIT_FLUSH'::
        If this environment variable is set to "1", then commands such
        as 'git blame' (in incremental mode), 'git rev-list', 'git log',
 'GIT_FLUSH'::
        If this environment variable is set to "1", then commands such
        as 'git blame' (in incremental mode), 'git rev-list', 'git log',

-       and 'git whatchanged' will force a flush of the output stream
-       after each commit-oriented record have been flushed.   If this
+       'git check-attr', 'git check-ignore', and 'git whatchanged' will
+       force a flush of the output stream after each record have been
+       flushed. If this

        variable is set to "0", the output of these commands will be done
        using completely buffered I/O.   If this environment variable is
        not set, git will choose buffered or record-oriented flushing
        variable is set to "0", the output of these commands will be done
        using completely buffered I/O.   If this environment variable is
        not set, git will choose buffered or record-oriented flushing