advice: recommend GIT_ADVICE=0 for tools

[derrickstolee]

I'm finally getting around to this doc update that I promised [1] a few weeks ago.

[1] https://lore.kernel.org/git/e90949ed-8065-4498-9ddb-3d5c6afa7b35@gmail.com/

Thanks, -Stolee

cc: gitster@pobox.com
cc: Johannes.Schindelin@gmx.de
cc: ps@pks.im
cc: james@jamesliu.io
cc: Jeff King peff@peff.net
cc: Gabor Gombas gombasgg@gmail.com
cc: Eric Sunshine sunshine@sunshineco.com

[derrickstolee]

/submit

[gitgitgadget]

Submitted as pull.1781.git.1725559154387.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1781/derrickstolee/advice-docs-v1

To fetch this version to local tag pr-1781/derrickstolee/advice-docs-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1781/derrickstolee/advice-docs-v1

[gitgitgadget]

On the Git mailing list, Eric Sunshine wrote (reply to this):

On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> The GIT_ADVICE environment variable was added implicitly in b79deeb5544
> (advice: add --no-advice global option, 2024-05-03) but was not
> documented. Add documentation to show that it is an option for tools
> that want to disable these messages. Make note that while the
> --no-advice option exists, older Git versions will fail to parse that
> option. The environment variable presents a way to change the behavior
> of Git versions that understand it without disrupting older versions.
>
> Signed-off-by: Derrick Stolee <stolee@gmail.com>
> ---
> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
> @@ -1,8 +1,12 @@
>  advice.*::
>         These variables control various optional help messages designed to
> -       aid new users.  When left unconfigured, Git will give the message
> -       alongside instructions on how to squelch it.  You can tell Git
> -       that you do not need the help message by setting these to `false`:
> +       aid new users. These are output to `stderr` by default as they are
> +       intended to help human readers. Tools that execute Git as a subprocess
> +       can disable these messages by setting `GIT_ACVICE=0` in the environment.

s/GIT_ACVICE/GIT_ADVICE/

[gitgitgadget]

User Eric Sunshine <sunshine@sunshineco.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  advice.*::
>  	These variables control various optional help messages designed to
> -	aid new users.  When left unconfigured, Git will give the message
> -	alongside instructions on how to squelch it.  You can tell Git
> -	that you do not need the help message by setting these to `false`:
> +	aid new users. These are output to `stderr` by default as they are
> +	intended to help human readers. Tools that execute Git as a subprocess
> +	can disable these messages by setting `GIT_ACVICE=0` in the environment.
> ++
> +When left unconfigured, Git will give the message alongside instructions on how
> +to squelch it.  You can tell Git that you do not need the help message by
> +setting these to `false`:

This somehow makes it sounds like it is an "aside, by the way" that
these trigger by default and that you can selectively disable it by
setting these variables, but shouldn't the stress be the other way
around?  Shouldn't the mention of GIT_ADVICE be a side note, leaving
primary text target human users?

Perhaps like this?

Thanks.

 Documentation/config/advice.txt |  8 +++++++-
 Documentation/git.txt           | 11 +++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt
index 0ba8989820..d749aee7f4 100644
--- c/Documentation/config/advice.txt
+++ w/Documentation/config/advice.txt
@@ -2,7 +2,13 @@ advice.*::
 	These variables control various optional help messages designed to
 	aid new users.  When left unconfigured, Git will give the message
 	alongside instructions on how to squelch it.  You can tell Git
-	that you do not need the help message by setting these to `false`:
+	that you have understood the issue and no longer need a specific
+	help message by setting the corresponding variable to `false`.
++
+As they are intended to help human users, these messages are output
+to the standard error.  When tools that run Git as a subprocesses
+find them disruptive, they can set `GIT_ADVICE=0` in the environment
+to squelch all advice messages.
 +
 --
 	addEmbeddedRepo::
diff --git c/Documentation/git.txt w/Documentation/git.txt
index 4489e2297a..d15a869762 100644
--- c/Documentation/git.txt
+++ w/Documentation/git.txt
@@ -1027,6 +1027,17 @@ standard output.
 	adequate and support for it is likely to be removed in the
 	foreseeable future (along with the variable).
 
+`GIT_ADVICE`::
+	If set to `0`, then disable all advice messages. These messages are
+	intended to provide hints to human users that may help them get out of
+	problematic situations or take advantage of new features. Users can
+	disable individual messages using the `advice.*` config keys. These
+	messages may be disruptive to tools that execute Git processes, so this
+	variable is available to disable the messages. (The `--no-advice`
+	global option is also available, but old Git versions may fail when
+	this option is not understood. The environment variable will be ignored
+	by Git versions that do not understand it.)
+
 Discussion[[Discussion]]
 ------------------------
 

[gitgitgadget]

This patch series was integrated into seen via git@436747c.

[gitgitgadget]

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 9/5/24 2:02 PM, Eric Sunshine wrote:
> On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> The GIT_ADVICE environment variable was added implicitly in b79deeb5544
>> (advice: add --no-advice global option, 2024-05-03) but was not
>> documented. Add documentation to show that it is an option for tools
>> that want to disable these messages. Make note that while the
>> --no-advice option exists, older Git versions will fail to parse that
>> option. The environment variable presents a way to change the behavior
>> of Git versions that understand it without disrupting older versions.
>>
>> Signed-off-by: Derrick Stolee <stolee@gmail.com>
>> ---
>> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
>> @@ -1,8 +1,12 @@
>>   advice.*::
>>          These variables control various optional help messages designed to
>> -       aid new users.  When left unconfigured, Git will give the message
>> -       alongside instructions on how to squelch it.  You can tell Git
>> -       that you do not need the help message by setting these to `false`:
>> +       aid new users. These are output to `stderr` by default as they are
>> +       intended to help human readers. Tools that execute Git as a subprocess
>> +       can disable these messages by setting `GIT_ACVICE=0` in the environment.
> > s/GIT_ACVICE/GIT_ADVICE/

Thank you for catching my typo!
-Stolee

[gitgitgadget]

On the Git mailing list, Derrick Stolee wrote (reply to this):

On 9/5/24 4:26 PM, Junio C Hamano wrote:

> This somehow makes it sounds like it is an "aside, by the way" that
> these trigger by default and that you can selectively disable it by
> setting these variables, but shouldn't the stress be the other way
> around?  Shouldn't the mention of GIT_ADVICE be a side note, leaving
> primary text target human users?
> > Perhaps like this?
> > Thanks.
> >   Documentation/config/advice.txt |  8 +++++++-
>   Documentation/git.txt           | 11 +++++++++++
>   2 files changed, 18 insertions(+), 1 deletion(-)
> > diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt
> index 0ba8989820..d749aee7f4 100644
> --- c/Documentation/config/advice.txt
> +++ w/Documentation/config/advice.txt
> @@ -2,7 +2,13 @@ advice.*::
>   	These variables control various optional help messages designed to
>   	aid new users.  When left unconfigured, Git will give the message
>   	alongside instructions on how to squelch it.  You can tell Git
> -	that you do not need the help message by setting these to `false`:
> +	that you have understood the issue and no longer need a specific
> +	help message by setting the corresponding variable to `false`.
> ++
> +As they are intended to help human users, these messages are output
> +to the standard error.  When tools that run Git as a subprocesses
> +find them disruptive, they can set `GIT_ADVICE=0` in the environment
> +to squelch all advice messages.
I like this a lot better. Your careful edit is substantial enough
that I will give you co-authored-by in v2.

Thanks,
-Stolee

[derrickstolee]

/submit

[gitgitgadget]

Submitted as pull.1781.v2.git.1725654155162.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-1781/derrickstolee/advice-docs-v2

To fetch this version to local tag pr-1781/derrickstolee/advice-docs-v2:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-1781/derrickstolee/advice-docs-v2

[gitgitgadget]

This patch series was integrated into seen via git@3a12ae9.

[gitgitgadget]

This patch series was integrated into seen via git@a6eb4d3.

[gitgitgadget]

This branch is now known as ds/doc-wholesale-disabling-advice-messages.

[gitgitgadget]

This patch series was integrated into seen via git@e785ff2.

[gitgitgadget]

This patch series was integrated into next via git@a52a31f.

[gitgitgadget]

There was a status update in the "New Topics" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <pull.1781.v2.git.1725654155162.gitgitgadget@gmail.com>

[gitgitgadget]

There was a status update in the "Cooking" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <pull.1781.v2.git.1725654155162.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@3175465.

[gitgitgadget]

This patch series was integrated into seen via git@984b774.

[gitgitgadget]

This patch series was integrated into seen via git@dc2f0e9.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch ds/doc-wholesale-disabling-advice-messages on the Git mailing list:

The environment GIT_ADVICE has been intentionally kept undocumented
to discourage its use by interactive users.  Add documentation to
help tool writers.

Will merge to 'master'.
source: <pull.1781.v2.git.1725654155162.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@3ae732c.

[gitgitgadget]

This patch series was integrated into seen via git@19de221.

[gitgitgadget]

This patch series was integrated into master via git@19de221.

[gitgitgadget]

This patch series was integrated into next via git@19de221.

[gitgitgadget]

Closed via 19de221.