On Tue, 3 Oct 2023 16:06:59 -0400
Jeff King wrote:
>> 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.]
>> -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
