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

From: Junio C Hamano <[email-masked]>
Date: Mon, 19 Aug 2024 09:04:50 -0700

Yukai Chou <[email-masked]> 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].

> 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 <[email-masked]>
> ---

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.