Subject: [PATCH] advice: recommend GIT_ADVICE=0 for tools

From: "Derrick Stolee via GitGitGadget" <[email-masked]>
Date: Thu, 05 Sep 2024 17:59:14 +0000

From: Derrick Stolee <[email-masked]>

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 <[email-masked]>
---
    advice: recommend GIT_ADVICE=0 for tools
    
    I'm finally getting around to this doc update that I promised [1] a few
    weeks ago.
    
    [1]
    https://lore.kernel.org/git/[email-masked]/
    
    Thanks, -Stolee

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1781%2Fderrickstolee%2Fadvice-docs-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1781/derrickstolee/advice-docs-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1781

 Documentation/config/advice.txt | 10 +++++++---
 Documentation/git.txt           | 11 +++++++++++
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 0ba89898207..c05f42c27c8 100644
--- 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.
++
+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`:
 +
 --
 	addEmbeddedRepo::
diff --git a/Documentation/git.txt b/Documentation/git.txt
index 4489e2297a3..d15a8697625 100644
--- a/Documentation/git.txt
+++ b/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]]
 ------------------------

base-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c
-- 
gitgitgadget