From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 07 Apr 2022 20:27:42 GMT
Subject: Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency
Message-ID: <xmqqv8vkr64h.fsf@gitster.g>
In-Reply-To: <patch-1.1-79404e05d73-20220407T185645Z-avarab@gmail.com>

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> Subject: Re: [PATCH] doc txt & -h consistency: fix recent "cat-file" inconsistency

IOW ...

> -'git cat-file' (--batch | --batch-check) [--batch-all-objects]
> +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]

... we forgot to add "--batch-command" to the documentation, even
though we added it to the usage text in the source.

And explained that way, this change makes quite a lot of sense.

It could be a worthwhile longer-term goal to make it consistent
between the synopsis and the usage text", but we are far away from
such a goal.  I'd rather keep such a topic outside this focused fix.

Given that we have been pushing to stop listing individual options
in SYNOPSIS, and instead using <option> placeholder, and also list
different operation mode of a single command on separate lines,
between

    $ git commit -h 2>&1 | sed -e '/^$/q'
    $ git commit --help | sed -ne '/^SYNOPSIS/,/^$/p'

we would want to pick the one we have from the command (i.e. the
former) and update the documentation source for the latter.

    Side note: and no, we do not want to tie the documentation to a
    particular build too tightly, and it is a no-no to generate the
    documentation source from 'git cmd -h' output.  Even when an
    option is conditionally excluded from a particular build, I'd
    like to be able to build and publish documentation for wider
    audience than just to myself.

Somebody needs to go through the comparison of individual
subcommands and present a good plan.  I find that, in comparison
between the -h and --help output, neither is quite satisfactory for
"git bisect", for example.  It would be a huge task and would be a
distraction during the pre-release period.

Thanks.