On Fri, Sep 30, 2022 at 2:10 PM Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> wrote: > 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/ > 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/ > * 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@xxxxxxxxx>
