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

["Derrick Stolee via GitGitGadget" <gitgitgadget@gmail.com>]

From: Derrick Stolee <stolee@gmail.com>

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.

Co-authored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Derrick Stolee <stolee@gmail.com>
---
    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/e90949ed-8065-4498-9ddb-3d5c6afa7b35@gmail.com/
    
    Thanks, -Stolee

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

Range-diff vs v1:

 1:  52f6450bbf8 ! 1:  aacc8c06017 advice: recommend GIT_ADVICE=0 for tools
     @@ Commit message
          option. The environment variable presents a way to change the behavior
          of Git versions that understand it without disrupting older versions.
      
     +    Co-authored-by: Junio C Hamano <gitster@pobox.com>
          Signed-off-by: Derrick Stolee <stolee@gmail.com>
      
       ## Documentation/config/advice.txt ##
     -@@
     - advice.*::
     +@@ Documentation/config/advice.txt: 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
     + 	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.
     ++	that you have understood the issue and no longer need a specific
     ++	help message by setting the corresponding variable to `false`.
      ++
     -+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`:
     ++As they are intended to help human users, these messages are output to
     ++the standard error. When tools that run Git as a subprocess find them
     ++disruptive, they can set `GIT_ADVICE=0` in the environment to squelch
     ++all advice messages.
       +
       --
       	addEmbeddedRepo::


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

diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt
index 0ba89898207..257db589181 100644
--- a/Documentation/config/advice.txt
+++ b/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 subprocess find them
+disruptive, they can set `GIT_ADVICE=0` in the environment to squelch
+all advice messages.
 +
 --
 	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