Re: [PATCH] docs: explain the order of output in cat-file batch operations

From: Patrick Steinhardt <ps@pks.im>
Date: Aug 21, 2024, 07:00 UTC
Message-ID: <ZsWQgYclF4ahQPrQ@tanuki>
In-Reply-To: <pull.1761.git.git.1724070410906.gitgitgadget@gmail.com>

On Mon, Aug 19, 2024 at 12:26:50PM +0000, ahmed akef via GitGitGadget wrote:

> From: ahmed akef <aemed.akef.1@gmail.com>
> 
> the order of the output is not described explicitly so someone can make
> complex code to parse it instead of just depending on the order

We aim to write full sentences in commit messages. That is, they start with an upper-case letter and should end with some form of punctuation. It's also not immediately clear what "the output" refers to without referring to the subject. And last but not least, it could use some explanation that this all refers to the `--batch` mode, only.

I would have probably written something like this:

  The batched mode of git-cat-file(1) reads multiple objects from stdin
  and prints their respective contents to stdout. The order in which
  those objects are printed is not documented and may not be immediately
  obvious to the user. Document it.

This explains the context, proceeds to the problem and then says how we address the problem.

Show 24 quoted lines

> Signed-off-by: ahmed akef <aemed.akef.1@gmail.com>
> ---
>     explain the order of output in cat-file batch operations since it is not
>     explicit
> 
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1761%2Fahmedakef%2Fexplain-the-order-of-output-in-cat-file-batch-operations-v1
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1761/ahmedakef/explain-the-order-of-output-in-cat-file-batch-operations-v1
> Pull-Request: https://github.com/git/git/pull/1761
> 
>  Documentation/git-cat-file.txt | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt
> index bd95a6c10a7..f1e0b4a7219 100644
> --- a/Documentation/git-cat-file.txt
> +++ b/Documentation/git-cat-file.txt
> @@ -270,8 +270,8 @@ BATCH OUTPUT
>  ------------
>  
>  If `--batch` or `--batch-check` is given, `cat-file` will read objects
> -from stdin, one per line, and print information about them. By default,
> -the whole line is considered as an object, as if it were fed to
> +from stdin, one per line, and print information about them sequentially in the same order.
> +By default, the whole line is considered as an object, as if it were fed to

These lines are now overly long. We should likely wrap them at 72 characters.

I'd likely also replace "sequentially in the same order" with "in the same order as they have been read from stdin", which feels a bit more explicit to me.

Thanks!

Patrick