Re: [PATCH/RFC] fast-import doc: deadlock avoidance in bidirectional mode

[Junio C Hamano <gitster@pobox.com>]

Jonathan Nieder <jrnieder@gmail.com> writes:

> How about this?

I find all the explanation above this line (elided) understandable and
sensible.

The expected use of --cat-blob-fd is to loop it back to the frontend, and
that is obvious to _us_, but there is nothing in the existing text (or the
text added by this patch) that suggests that fact to the first time
reader.  "Frontends must consume" may not "click" without that knowledge.

>  Documentation/git-fast-import.txt |   13 ++++++++++++-
>  1 file changed, 12 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
> index ec6ef311..0ea649f4 100644
> --- a/Documentation/git-fast-import.txt
> +++ b/Documentation/git-fast-import.txt
> @@ -942,6 +942,12 @@ 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.
>  
> +While in some cases the 'cat-blob' result will fit in the pipe buffer,
> +allowing fast-import to continue processing additional commands, this
> +is not guaranteed.  Frontends must consume the cat-blob response
> +completely before performing any writes to fast-import that might
> +block.
> +
>  `ls`
>  ~~~~
>  Prints information about the object at a path to a file descriptor
> @@ -975,7 +981,12 @@ 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>`:
> +While in some cases the 'ls' response will fit in the pipe buffer,
> +allowing fast-import to continue processing additional commands, this
> +is not guaranteed.  Frontends must consume the ls response completely
> +before performing any writes to fast-import that might block.
> +
> +The 'ls' response uses the same format as `git ls-tree <tree> {litdd} <path>`:
>  
>  ====
>  	<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF