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

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

IOW ...

... 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.