Re: [PATCH 1/3] doc: var: link -l to git config list

[Junio C Hamano <gitster@pobox.com>]

kristofferhaugsbakk@fastmail.com writes:

> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
>
> The option `-l` is deprecated and links to `git config -l` as the
> replacement—which is also deprecated. Break the deprecation chain by
> linking to `git config list`, the command which has superseded `git
> config -l`.
>
> Also promote this part from a parenthetical to a warning admonition.
>
> Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
> ---
>  Documentation/git-var.adoc | 5 +++--
>  1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/git-var.adoc b/Documentation/git-var.adoc
> index b606c2d6499..98f4dc1a479 100644
> --- a/Documentation/git-var.adoc
> +++ b/Documentation/git-var.adoc
> @@ -21,8 +21,9 @@ OPTIONS
>  `-l`::
>  	Display the logical variables. In addition, all the
>  	variables of the Git configuration file .git/config are listed
> -	as well. (However, the configuration variables listing functionality
> -	is deprecated in favor of `git config -l`.)
> +	as well.
> ++
> +WARNING: Deprecated in favor of `git config list`.

This changes the meaning, and I am afraid in a bad way.

Use if "git var -l" to ask values of configuration variables is
deprecated, as we would encourage use of "git config [-l | list]".
"git var -l" is and will stay to be the way to ask about logical
variables.

The new text, unlike the original, does not limit the deprecation
only for asking about configuration variables.

The logical variables are called logical because their values are
synthesized from information taken from different places (e.g., you
might not have user.name configured but may have GIT_AUTHOR_NAME
environment variable set and exported or your name configured
correctly in GECOS field.  We can ask what the value of
GIT_AUTHOR_IDENT is, without knowing where that value comes from,
and the source might be outside the usual Git configuration
subsystem, which makes it "logical").

I'd prefer to see this step just stick to `git config -l` => `git config list`
rewrite without the separate WARNING: style change.