Re: [PATCH v2 25/35] doc txt & -h consistency: add missing options

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Sep 29, 2022, 04:36 UTC
Message-ID: <CAPig+cSwokKApLJi6xHVUs1JZGJkjdxd0wkLT1Hqsr9UpPN-JQ@mail.gmail.com>
In-Reply-To: <patch-v2-25.35-a4d75ea691c-20220928T082458Z-avarab@gmail.com>

On Wed, Sep 28, 2022 at 4:45 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:

> Change those built-in commands that were attempting to exhaustively
> the options in the "-h" output to actually do so, and always

s/exhaustively/exhaustively list/

Show 13 quoted lines

> have *.txt documentation know about the exhaustive list of options.
>
> Let's also fix the documentation and -h output for those built-in
> commands where the *.txt and -h output was a mismatch of missing
> options on both sides.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
>  'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress]
> -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress]
> +'git commit-graph write' [--object-dir <dir>] [--append]
> +                       [--split[=<strategy>]] [--reachable|--stdin-packs|--stdin-commits]

Should there be spaces around the vertical bars per [14/35]?

    [--split[=<strategy>]] [--reachable | --stdin-packs | --stdin-commits]

Show 8 quoted lines

> +                       [--changed-paths] [--[no-]max-new-filters <n>] [--[no-]progress]
> +                       <split options>
> diff --git a/Documentation/git-interpret-trailers.txt b/Documentation/git-interpret-trailers.txt
> -'git interpret-trailers' [<options>] [(--trailer <token>[(=|:)<value>])...] [<file>...]
> -'git interpret-trailers' [<options>] [--parse] [<file>...]
> +'git interpret-trailers' [--in-place] [--trim-empty]
> +                       [(--trailer <token>[(=|:)<value>])...]
> +                       [--parse] [<file>...]

This changes the interpretation from two distinct operating modes to a single mode. I had to go study the git-interpret-trailers documentation to convince myself that the revised synopsis is correct and matches the implementation, and that the old documented dual-mode behavior was misleading. This probably should have been mentioned in the commit message, or this change could have been split out to its own patch (not that I'm advocating making this series even longer).

Show 9 quoted lines

> diff --git a/builtin/hash-object.c b/builtin/hash-object.c
>  int cmd_hash_object(int argc, const char **argv, const char *prefix)
>  {
>         static const char * const hash_object_usage[] = {
> -               N_("git hash-object [-t <type>] [-w] [--path=<file> | --no-filters] [--stdin] [--] <file>..."),
> -               "git hash-object  --stdin-paths",
> +               N_("git hash-object [-t <type>] [-w] [--path=<file>|--no-filters]\n"
> +                  "                [--stdin [--literally]] [--] <file>..."),
> +               N_("git hash-object [-t <type>] [-w] --stdin-paths [--no-filters]"),

This removes spaces around vertical bars, which seems to contradict [14/35] (unless I'm misunderstanding [14/35]).