advice: recommend GIT_ADVICE=0 for tools
PATCH 1/1 advice: recommend GIT_ADVICE=0 for tools
From: Derrick Stolee <[email protected]>
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.
---
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 protected]/
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(-)
Documentation/config/advice.txt +7 -3
@@ -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::
Documentation/git.txt +11 -0
@@ -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
Signature · 1 line
gitgitgadget
Quoted 12 lines · Derrick Stolee via GitGitGadget
The
GIT_ADVICEenvironment variable was added implicitly inb79deeb5544(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 protected]>---
Documentation/config/advice.txt line 5
Quoted 8 lines
Documentation/config/advice.txt +3
-3@@ -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/
Review
Quoted 12 lines · Derrick Stolee via GitGitGadget
advice.*::
(quoted diff) +7
-3These 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(-)
Documentation/config/advice.txt +7 -1
@@ -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::
Documentation/git.txt +11 -0
@@ -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]] ------------------------
Quoted 10 lines · Eric Sunshine
Quoted 8 lines · Derrick Stolee via GitGitGadget
The
GIT_ADVICEenvironment variable was added implicitly inb79deeb5544(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.
Quoted 14 lines
Documentation/config/advice.txt line 5
Quoted 12 lines
Signed-off-by Derrick Stolee <[email protected]>---
Documentation/config/advice.txt +3
-3@@ -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
Quoted 20 lines · Junio C Hamano
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_ADVICEbe 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(-)Documentation/config/advice.txt +0
-0@@ -2,7 +2,13 @@ advice.*:: These variables control various optional help messages designed to
Documentation/config/advice.txt advice.*:: · line 11
Quoted 10 lines
Documentation/config/advice.txt +7
-1aid 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
PATCH v2 1/1 advice: recommend GIT_ADVICE=0 for tools
In reply to Derrick Stolee via GitGitGadgetFrom: Derrick Stolee <[email protected]>
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.
---
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 protected]/
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 <[email protected]>
## 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(-)
Documentation/config/advice.txt +7 -1
@@ -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::
Documentation/git.txt +11 -0
@@ -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
Signature · 1 line
gitgitgadget