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

[Patrick Steinhardt <ps@pks.im>]

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.

> 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