Re: [PATCH v3 35/36] tests: start asserting that *.txt SYNOPSIS matches -h output

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 2, 2022, 01:25 UTC
Message-ID: <CAPig+cRq_qdg_o9wgWszmagYNi+s=wkczng9+vHz31DiAhKE+A@mail.gmail.com>
In-Reply-To: <patch-v3-35.36-22da68abce3-20220930T180415Z-avarab@gmail.com>

On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

Show 9 quoted lines

> There's been a lot of incremental effort to make the SYNOPSIS output
> in our documentation consistent with the -h output,
> e.g. cbe485298bf (git reflog [expire|delete]: make -h output
> consistent with SYNOPSIS, 2022-03-17) is one recent example, but that
> effort has been an uphill battle due to the lack of regression
> testing.
>
> This adds such regression testing, we can parse out the SYNOPSIS
> output with "sed", and is turns out it's relatively easy to normalize

s/is/it/

Show 11 quoted lines

> it and the "-h" output to match on another.
>
> Some of the issues that are left:
>
>  * "git show -h", "git whatchanged -h" and "git reflog --oneline -h"
>    all showing "git log" and "git show" usage output. I.e. the
>    "builtin_log_usage" in builtin/log.c doesn't take into account what
>    command we're running.
>
>  * Likewise "git stage -h" shows "git add" usage, but should be aware
>    of what command it's running. The same for "annotate" and "blame".

Is this mention of annotate/blame out of date? Doesn't [28/36] make these commands emit the correct usage text? Or am I misunderstanding what this is saying?

>  * Commands which implement subcommands such as like
>    "multi-pack-index", "notes", "remote" etc. having their subcommands
>    in a very different order in the *.txt and *.c. Fixing it would
>    require some verbose diffs, so it's been left alone for onw.

s/onw/now/

Show 10 quoted lines

>  * Commands such as "format-patch" have a very long argument list in
>    the *.txt, but just "[<options>]" in the *.c.
>
>    What to do about these has been left out of this series, except to
>    the extent that preceding commits changed "[<options>]" (or
>    equivalent) to the list of options in cases where that list of
>    options was tiny, or we clearly meant to exhaustively list the
>    options in both *.txt and *.c.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>