Re: [PATCH] doc: add --show-names for git config

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 19, 2024, 16:04 UTC
Message-ID: <xmqqcym4fqhp.fsf@gitster.g>
In-Reply-To: <CAEg0tHRL9+tqY0k2GiGzhc-VgMVsHqppLRFHbc=M33R6AoLXEg@mail.gmail.com>

Yukai Chou <muzimuzhi@gmail.com> writes:

> Option "--show-names" was introduced along with the "get" subcommand
> of git-config(1) [1]. It was used in Deprecated Modes doc examples,

There is no [1].

Show 6 quoted lines

> normal and completion tests, but not documented.
>
> It's known by both "get" and "list", though has no effect on "list".
>
> Signed-off-by: Yukai Chou <muzimuzhi@gmail.com>
> ---

I'd probably write it more like so

    4e513890 (builtin/config: introduce "get" subcommand,
    2024-05-06) introduced "--show-names" option that is used to
    give the name of the configuraiton variable to each output entry
    in addition to the value.  It however forgot to document it,
    even though the option is used in a few examples.

    Document it.

if I were doing this commit.

> +--show-names::
> + Output also the names of config variables for `list` or
> + `get`.

Considering how long the later "Find the color setting" line is, I think it is better to write that on a single line, i.e.

> + Output also the names of config variables for `list` or `get`.

It fills only 66-column counting the quote "> " and diff formatting "+".

> +
>  --get-colorbool <name> [<stdout-is-tty>]::
>
>   Find the color setting for `<name>` (e.g. `color.diff`) and output

As to the name, I tend to agree that --show-names is a strange name for the option, and I would have even suggest making "--all" to show the name by default and give "--hide-name" option to countermand it if we were adding this topic afresh today. But that unfortunately is all too late to change without much more effort than just changing the name.