Re: [PATCH/RFC] fast-import doc: deadlock avoidance in bidirectional mode
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Apr 11, 2012, 17:32 UTC
- Message-ID
- <7vlim2kwcv.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <20120411171707.GD4248@burratino>
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.
Show 34 quoted lines
> 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