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

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

[Yukai Chou]

Option "--show-names" was introduced along with the "get" subcommand
of git-config(1) [1]. It was used in Deprecated Modes doc examples,
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>
---
 Documentation/git-config.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 65c645d461..525c29fcff 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -268,6 +268,10 @@ Valid `<type>`'s include:
  all queried config options with the scope of that value
  (worktree, local, global, system, command).

+--show-names::
+ Output also the names of config variables for `list` or
+ `get`.
+
 --get-colorbool <name> [<stdout-is-tty>]::

  Find the color setting for `<name>` (e.g. `color.diff`) and output
-- 
2.46.0

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

[Yukai Chou]

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

A bit of inconsistency: both singular (`--name-only` [1]) and
plural (`--show-names`) forms are used in similar git-config(1)
options.

As both `--show-origin` and `--show-scope` use the singular forms,
perhaps `--show-names` can be renamed to `--show-name` too?

[1]: https://git-scm.com/docs/git-config#Documentation/git-config.txt---name-only

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

[Junio C Hamano]

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].

> 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.

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

[Yukai Chou]

4e513890 (builtin/config: introduce "get" subcommand,
2024-05-06) introduced "--show-names" option that is used to
give the name of the configuration 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.

Signed-off-by: Yukai Chou <muzimuzhi@gmail.com>
---
Thanks for your review and suggestions Junio. I must have stayed up
too late yesterday, so what the commit message was sent was not the
final version.

 Documentation/git-config.txt | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
index 65c645d461..16323c4ed0 100644
--- a/Documentation/git-config.txt
+++ b/Documentation/git-config.txt
@@ -268,6 +268,9 @@ Valid `<type>`'s include:
  all queried config options with the scope of that value
  (worktree, local, global, system, command).

+--show-names::
+ Output also the names of config variables for `list` or `get`.
+
 --get-colorbool <name> [<stdout-is-tty>]::

  Find the color setting for `<name>` (e.g. `color.diff`) and output
-- 
2.46.0

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

[Junio C Hamano]

[Cc-ing the author of 4e513890 that was referred to by this change.]

Yukai Chou <muzimuzhi@gmail.com> writes:

> 4e513890 (builtin/config: introduce "get" subcommand,
> 2024-05-06) introduced "--show-names" option that is used to
> give the name of the configuration 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.
>
> Signed-off-by: Yukai Chou <muzimuzhi@gmail.com>
> ---
> Thanks for your review and suggestions Junio. I must have stayed up
> too late yesterday, so what the commit message was sent was not the
> final version.
>
>  Documentation/git-config.txt | 3 +++
>  1 file changed, 3 insertions(+)
>
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 65c645d461..16323c4ed0 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -268,6 +268,9 @@ Valid `<type>`'s include:
>   all queried config options with the scope of that value
>   (worktree, local, global, system, command).
>
> +--show-names::
> + Output also the names of config variables for `list` or `get`.
> +
>  --get-colorbool <name> [<stdout-is-tty>]::
>
>   Find the color setting for `<name>` (e.g. `color.diff`) and output

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

[Patrick Steinhardt]

On Tue, Aug 20, 2024 at 02:27:56AM +0800, Yukai Chou wrote:
> 4e513890 (builtin/config: introduce "get" subcommand,
> 2024-05-06) introduced "--show-names" option that is used to
> give the name of the configuration 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.
> 
> Signed-off-by: Yukai Chou <muzimuzhi@gmail.com>
> ---
> Thanks for your review and suggestions Junio. I must have stayed up
> too late yesterday, so what the commit message was sent was not the
> final version.
> 
>  Documentation/git-config.txt | 3 +++
>  1 file changed, 3 insertions(+)
> 
> diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt
> index 65c645d461..16323c4ed0 100644
> --- a/Documentation/git-config.txt
> +++ b/Documentation/git-config.txt
> @@ -268,6 +268,9 @@ Valid `<type>`'s include:
>   all queried config options with the scope of that value
>   (worktree, local, global, system, command).
> 
> +--show-names::
> + Output also the names of config variables for `list` or `get`.
> +

This looks sensible. I'd probably drop the "also" here, which reads a
bit awkward. Do we also want to spell out how names and values are
separated from each other?

Patrick

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

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

>> +--show-names::
>> + Output also the names of config variables for `list` or `get`.
>> +
>
> This looks sensible. I'd probably drop the "also" here, which reads a
> bit awkward. Do we also want to spell out how names and values are
> separated from each other?

Sounds like a good thing to add.  Thanks.

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

[Patrick Steinhardt]

On Mon, Aug 19, 2024 at 09:04:50AM -0700, Junio C Hamano wrote:
> 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.

Mh. Yeah, that might've been the better default indeed. The new command
is still relatively young, but still, I don't know whether changing this
is in the picture now.

Patrick

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

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> writes:

> On Mon, Aug 19, 2024 at 09:04:50AM -0700, Junio C Hamano wrote:
>> 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.
>
> Mh. Yeah, that might've been the better default indeed. The new command
> is still relatively young, but still, I don't know whether changing this
> is in the picture now.

Yeah, it appeared only in the latest release, and may not be relied
on yet.