Re: [PATCH 8/8] Documentation/git-config: update to new-style syntax

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 7, 2024, 06:57 UTC
Message-ID: <CAPig+cQevQKb8YA1Yf-t=AHg11P7i848gELx2kPc39g5cOWbqw@mail.gmail.com>
In-Reply-To: <5ff2bf4a2286431a3b3048e0ea04d6551006d0d7.1709724089.git.ps@pks.im>

On Wed, Mar 6, 2024 at 6:32 AM Patrick Steinhardt <ps@pks.im> wrote:

Show 6 quoted lines

> Update our documentation of git-config(1) to stop mentioning the old
> syntax while starting to mention the new syntax. Remove the help
> mismatch in t0450 so that we start to ensure that the manpage and
> builtin synopsis match.
> [...]
> Signed-off-by: Patrick Steinhardt <ps@pks.im>

I'd like to push back on the part of this patch which completely eradicates mention of the old syntax. Doing so makes it difficult for people to figure out the meaning of git-config commands which they run across in blogs and existing tooling. For instance, the following recommendation is commonly encountered in the wild:

    git config --global user.name "Your Name"
    git config --global user.email "youremail@yourdomain.com"

Typically, we instead retain the old syntax (or options or whatever) in the documentation so that people who want to learn can learn, but we rewrite it to make it clear that it is deprecated, and explicitly point the reader at the modern replacement command or option (or whatever).

So, perhaps you can have a SYNOPSIS section for the deprecated usage, as well as a "DEPRECATED OPTIONS" section (or such), so that we don't leave readers entirely in the dark.