From: Derrick Stolee <stolee@xxxxxxxxx>
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@xxxxxxxxx>
---
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@xxxxxxxxx/
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
