Re: [PATCH] doc/cat-file: clarify description regarding various command forms

From: Štěpán Němec <stepnem@smrk.net>
Date: Oct 5, 2023, 11:20 UTC
Message-ID: <20231005132018+0200.47596-stepnem@smrk.net>
In-Reply-To: <20231003200659.GC1562@coredump.intra.peff.net>

On Tue, 3 Oct 2023 16:06:59 -0400 Jeff King wrote:

Show 16 quoted lines

>>  DESCRIPTION
>>  -----------
>> -In its first form, the command provides the content or the type of an object in
>> +This command can operate in two modes, depending on whether an option from
>> +the `--batch` family is specified.
>> +
>> +In non-batch mode, the command provides the content or the type of an object in
>>  the repository. The type is required unless `-t` or `-p` is used to find the
>>  object type, or `-s` is used to find the object size, or `--textconv` or
>>  `--filters` is used (which imply type "blob").
>
> The existing text here is already a bit vague, considering the number of
> operations it covers (like "-e", for example, which is not showing "the
> content or the type" at all). But that is not new in your patch, and it
> is maybe even OK to be a bit vague here, and let the OPTIONS section
> cover the specifics.

So how about we just butcher the DESCRIPTION completely; after all, the information it gives is not quite correct (other than what you already mentioned, e.g., -e is omitted in the "type not required" part; one is left to wonder what <format> refers to: you have to go read the OPTIONS and BATCH OUTPUT sections anyway), and the correct parts only duplicate information given in the following sections, providing opportunities to become out of date when the command and its documentation evolve:

Changes (if we agree this is the way to go, I'll also update the --help
output):
  synopsis:
    - move the (--textconv | --filters) form before --batch, closer
      to the other non-batch forms
    - cosmetics: swap -t and -s, --filters and --textconv (sort
      alphabetically)
  description:
    - reformulate, omit vague/imprecise information better
      provided in the detailed options list

SYNOPSIS
    git cat-file <type> <object>
    git cat-file (-e | -p) <object>
    git cat-file (-s | -t) [--allow-unknown-type] <object>
    git cat-file (--filters | --textconv)
                 [<rev>:<path|tree-ish> | --path=<path|tree-ish> <rev>]
    git cat-file (--batch | --batch-check | --batch-command) [--batch-all-objects]
                 [--buffer] [--follow-symlinks] [--unordered]
                 [--filters | --textconv] [-Z]

DESCRIPTION
    This command can operate in two modes, depending on whether an
    option from the --batch family is specified.

    In non-batch mode, the command provides information on an object
    named on the command line.

    In batch mode, arguments are read from standard input.

[That's all for a summary, read the following sections for details.]

Show 10 quoted lines

>> -In the second form, a list of objects (separated by linefeeds) is provided on
>> +In batch mode, a list of objects (separated by linefeeds) is provided on
>>  stdin, and the SHA-1, type, and size of each object is printed on stdout. The
>>  output format can be overridden using the optional `<format>` argument. If
>>  either `--textconv` or `--filters` was specified, the input is expected to
>
> I think this got a bit inaccurate with "--batch-command", which is a
> whole different mode itself compared to --batch and --batch-check. I
> don't think your patch is really making anything worse, but arguably
> there are three "major modes" here.

This is not obvious to me (the "three major modes" part). AIUI it's still mainly a batch (read from stdin) vs. non-batch (args on command line) dichotomy. The details differ (just args vs. command + args), but so does e.g. -e differ in providing information via exit code rather than stdout.

(But please note I'm not trying to pose as an expert here: this all started with me coming to git-cat-file(1) to _learn_ about cat-file and finding the description more than a little confusing.)

-- 
Štěpán