{"thread":{"id":"62069","subject":"[PATCH] advice: recommend GIT_ADVICE=0 for tools","startedAt":"2024-09-05T17:59:18Z","lastAt":"2024-09-06T20:22:38Z","messageCount":6,"participants":["Derrick Stolee via GitGitGadget","Eric Sunshine","Junio C Hamano","Derrick Stolee"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"502274","messageId":"pull.1781.git.1725559154387.gitgitgadget@gmail.com","threadId":"62069","inReplyTo":null,"subject":"[PATCH] advice: recommend GIT_ADVICE=0 for tools","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-05T17:59:14Z","receivedAt":"2024-09-05T17:59:18Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"From: Derrick Stolee \n\nThe GIT_ADVICE environment variable was added implicitly in b79deeb5544\n(advice: add --no-advice global option, 2024-05-03) but was not\ndocumented. Add documentation to show that it is an option for tools\nthat want to disable these messages. Make note that while the\n--no-advice option exists, older Git versions will fail to parse that\noption. The environment variable presents a way to change the behavior\nof Git versions that understand it without disrupting older versions.\n\nSigned-off-by: Derrick Stolee \n---\n advice: recommend GIT_ADVICE=0 for tools\n \n I'm finally getting around to this doc update that I promised [1] a few\n weeks ago.\n \n [1]\n https://lore.kernel.org/git/e90949ed-8065-4498-9ddb-3d5c6afa7b35@gmail.com/\n \n Thanks, -Stolee\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1781%2Fderrickstolee%2Fadvice-docs-v1\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1781/derrickstolee/advice-docs-v1\nPull-Request: https://github.com/gitgitgadget/git/pull/1781\n\n Documentation/config/advice.txt | 10 +++++++---\n Documentation/git.txt | 11 +++++++++++\n 2 files changed, 18 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt\nindex 0ba89898207..c05f42c27c8 100644\n--- a/Documentation/config/advice.txt\n+++ b/Documentation/config/advice.txt\n@@ -1,8 +1,12 @@\n advice.*::\n \tThese variables control various optional help messages designed to\n-\taid new users. When left unconfigured, Git will give the message\n-\talongside instructions on how to squelch it. You can tell Git\n-\tthat you do not need the help message by setting these to `false`:\n+\taid new users. These are output to `stderr` by default as they are\n+\tintended to help human readers. Tools that execute Git as a subprocess\n+\tcan disable these messages by setting `GIT_ACVICE=0` in the environment.\n++\n+When left unconfigured, Git will give the message alongside instructions on how\n+to squelch it. You can tell Git that you do not need the help message by\n+setting these to `false`:\n +\n --\n \taddEmbeddedRepo::\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 4489e2297a3..d15a8697625 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -1027,6 +1027,17 @@ standard output.\n \tadequate and support for it is likely to be removed in the\n \tforeseeable future (along with the variable).\n \n+`GIT_ADVICE`::\n+\tIf set to `0`, then disable all advice messages. These messages are\n+\tintended to provide hints to human users that may help them get out of\n+\tproblematic situations or take advantage of new features. Users can\n+\tdisable individual messages using the `advice.*` config keys. These\n+\tmessages may be disruptive to tools that execute Git processes, so this\n+\tvariable is available to disable the messages. (The `--no-advice`\n+\tglobal option is also available, but old Git versions may fail when\n+\tthis option is not understood. The environment variable will be ignored\n+\tby Git versions that do not understand it.)\n+\n Discussion[[Discussion]]\n ------------------------\n \n\nbase-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c\n-- \ngitgitgadget\n"},{"id":"502275","messageId":"CAPig+cSGry+QMpkkiJb8A94w1M+J_5beEKaT-xrGeL34xME4hA@mail.gmail.com","threadId":"62069","inReplyTo":"pull.1781.git.1725559154387.gitgitgadget@gmail.com","subject":"Re: [PATCH] advice: recommend GIT_ADVICE=0 for tools","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2024-09-05T18:02:56Z","receivedAt":"2024-09-05T18:03:08Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget\n wrote:\n> The GIT_ADVICE environment variable was added implicitly in b79deeb5544\n> (advice: add --no-advice global option, 2024-05-03) but was not\n> documented. Add documentation to show that it is an option for tools\n> that want to disable these messages. Make note that while the\n> --no-advice option exists, older Git versions will fail to parse that\n> option. The environment variable presents a way to change the behavior\n> of Git versions that understand it without disrupting older versions.\n>\n> Signed-off-by: Derrick Stolee \n> ---\n> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt\n> @@ -1,8 +1,12 @@\n> advice.*::\n> These variables control various optional help messages designed to\n> - aid new users. When left unconfigured, Git will give the message\n> - alongside instructions on how to squelch it. You can tell Git\n> - that you do not need the help message by setting these to `false`:\n> + aid new users. These are output to `stderr` by default as they are\n> + intended to help human readers. Tools that execute Git as a subprocess\n> + can disable these messages by setting `GIT_ACVICE=0` in the environment.\n\ns/GIT_ACVICE/GIT_ADVICE/\n"},{"id":"502282","messageId":"xmqq4j6t26fs.fsf@gitster.g","threadId":"62069","inReplyTo":"pull.1781.git.1725559154387.gitgitgadget@gmail.com","subject":"Re: [PATCH] advice: recommend GIT_ADVICE=0 for tools","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-05T20:26:15Z","receivedAt":"2024-09-05T20:26:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Derrick Stolee via GitGitGadget\" writes:\n\n> advice.*::\n> \tThese variables control various optional help messages designed to\n> -\taid new users. When left unconfigured, Git will give the message\n> -\talongside instructions on how to squelch it. You can tell Git\n> -\tthat you do not need the help message by setting these to `false`:\n> +\taid new users. These are output to `stderr` by default as they are\n> +\tintended to help human readers. Tools that execute Git as a subprocess\n> +\tcan disable these messages by setting `GIT_ACVICE=0` in the environment.\n> ++\n> +When left unconfigured, Git will give the message alongside instructions on how\n> +to squelch it. You can tell Git that you do not need the help message by\n> +setting these to `false`:\n\nThis somehow makes it sounds like it is an \"aside, by the way\" that\nthese trigger by default and that you can selectively disable it by\nsetting these variables, but shouldn't the stress be the other way\naround? Shouldn't the mention of GIT_ADVICE be a side note, leaving\nprimary text target human users?\n\nPerhaps like this?\n\nThanks.\n\n Documentation/config/advice.txt | 8 +++++++-\n Documentation/git.txt | 11 +++++++++++\n 2 files changed, 18 insertions(+), 1 deletion(-)\n\ndiff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt\nindex 0ba8989820..d749aee7f4 100644\n--- c/Documentation/config/advice.txt\n+++ w/Documentation/config/advice.txt\n@@ -2,7 +2,13 @@ advice.*::\n \tThese variables control various optional help messages designed to\n \taid new users. When left unconfigured, Git will give the message\n \talongside instructions on how to squelch it. You can tell Git\n-\tthat you do not need the help message by setting these to `false`:\n+\tthat you have understood the issue and no longer need a specific\n+\thelp message by setting the corresponding variable to `false`.\n++\n+As they are intended to help human users, these messages are output\n+to the standard error. When tools that run Git as a subprocesses\n+find them disruptive, they can set `GIT_ADVICE=0` in the environment\n+to squelch all advice messages.\n +\n --\n \taddEmbeddedRepo::\ndiff --git c/Documentation/git.txt w/Documentation/git.txt\nindex 4489e2297a..d15a869762 100644\n--- c/Documentation/git.txt\n+++ w/Documentation/git.txt\n@@ -1027,6 +1027,17 @@ standard output.\n \tadequate and support for it is likely to be removed in the\n \tforeseeable future (along with the variable).\n \n+`GIT_ADVICE`::\n+\tIf set to `0`, then disable all advice messages. These messages are\n+\tintended to provide hints to human users that may help them get out of\n+\tproblematic situations or take advantage of new features. Users can\n+\tdisable individual messages using the `advice.*` config keys. These\n+\tmessages may be disruptive to tools that execute Git processes, so this\n+\tvariable is available to disable the messages. (The `--no-advice`\n+\tglobal option is also available, but old Git versions may fail when\n+\tthis option is not understood. The environment variable will be ignored\n+\tby Git versions that do not understand it.)\n+\n Discussion[[Discussion]]\n ------------------------\n \n"},{"id":"502355","messageId":"a60b6cda-6f55-4133-9b26-5475e20cc839@gmail.com","threadId":"62069","inReplyTo":"CAPig+cSGry+QMpkkiJb8A94w1M+J_5beEKaT-xrGeL34xME4hA@mail.gmail.com","subject":"Re: [PATCH] advice: recommend GIT_ADVICE=0 for tools","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2024-09-06T19:47:01Z","receivedAt":"2024-09-06T19:47:04Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 9/5/24 2:02 PM, Eric Sunshine wrote:\n> On Thu, Sep 5, 2024 at 1:59 PM Derrick Stolee via GitGitGadget\n> wrote:\n>> The GIT_ADVICE environment variable was added implicitly in b79deeb5544\n>> (advice: add --no-advice global option, 2024-05-03) but was not\n>> documented. Add documentation to show that it is an option for tools\n>> that want to disable these messages. Make note that while the\n>> --no-advice option exists, older Git versions will fail to parse that\n>> option. The environment variable presents a way to change the behavior\n>> of Git versions that understand it without disrupting older versions.\n>>\n>> Signed-off-by: Derrick Stolee \n>> ---\n>> diff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt\n>> @@ -1,8 +1,12 @@\n>> advice.*::\n>> These variables control various optional help messages designed to\n>> - aid new users. When left unconfigured, Git will give the message\n>> - alongside instructions on how to squelch it. You can tell Git\n>> - that you do not need the help message by setting these to `false`:\n>> + aid new users. These are output to `stderr` by default as they are\n>> + intended to help human readers. Tools that execute Git as a subprocess\n>> + can disable these messages by setting `GIT_ACVICE=0` in the environment.\n> \n> s/GIT_ACVICE/GIT_ADVICE/\n\nThank you for catching my typo!\n-Stolee\n\n"},{"id":"502356","messageId":"da98da07-b2f4-4608-9038-7ce4b8e2d74b@gmail.com","threadId":"62069","inReplyTo":"xmqq4j6t26fs.fsf@gitster.g","subject":"Re: [PATCH] advice: recommend GIT_ADVICE=0 for tools","fromName":"Derrick Stolee","fromEmail":"stolee@gmail.com","sentAt":"2024-09-06T19:49:15Z","receivedAt":"2024-09-06T19:49:18Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"On 9/5/24 4:26 PM, Junio C Hamano wrote:\n\n> This somehow makes it sounds like it is an \"aside, by the way\" that\n> these trigger by default and that you can selectively disable it by\n> setting these variables, but shouldn't the stress be the other way\n> around? Shouldn't the mention of GIT_ADVICE be a side note, leaving\n> primary text target human users?\n> \n> Perhaps like this?\n> \n> Thanks.\n> \n> Documentation/config/advice.txt | 8 +++++++-\n> Documentation/git.txt | 11 +++++++++++\n> 2 files changed, 18 insertions(+), 1 deletion(-)\n> \n> diff --git c/Documentation/config/advice.txt w/Documentation/config/advice.txt\n> index 0ba8989820..d749aee7f4 100644\n> --- c/Documentation/config/advice.txt\n> +++ w/Documentation/config/advice.txt\n> @@ -2,7 +2,13 @@ advice.*::\n> \tThese variables control various optional help messages designed to\n> \taid new users. When left unconfigured, Git will give the message\n> \talongside instructions on how to squelch it. You can tell Git\n> -\tthat you do not need the help message by setting these to `false`:\n> +\tthat you have understood the issue and no longer need a specific\n> +\thelp message by setting the corresponding variable to `false`.\n> ++\n> +As they are intended to help human users, these messages are output\n> +to the standard error. When tools that run Git as a subprocesses\n> +find them disruptive, they can set `GIT_ADVICE=0` in the environment\n> +to squelch all advice messages.\nI like this a lot better. Your careful edit is substantial enough\nthat I will give you co-authored-by in v2.\n\nThanks,\n-Stolee\n\n"},{"id":"502359","messageId":"pull.1781.v2.git.1725654155162.gitgitgadget@gmail.com","threadId":"62069","inReplyTo":"pull.1781.git.1725559154387.gitgitgadget@gmail.com","subject":"[PATCH v2] advice: recommend GIT_ADVICE=0 for tools","fromName":"Derrick Stolee via GitGitGadget","fromEmail":"gitgitgadget@gmail.com","sentAt":"2024-09-06T20:22:35Z","receivedAt":"2024-09-06T20:22:38Z","isPatch":true,"sender":{"key":"stolee@gmail.com","avatar":"https://avatars.githubusercontent.com/u/570044?v=4"},"body":"From: Derrick Stolee \n\nThe GIT_ADVICE environment variable was added implicitly in b79deeb5544\n(advice: add --no-advice global option, 2024-05-03) but was not\ndocumented. Add documentation to show that it is an option for tools\nthat want to disable these messages. Make note that while the\n--no-advice option exists, older Git versions will fail to parse that\noption. The environment variable presents a way to change the behavior\nof Git versions that understand it without disrupting older versions.\n\nCo-authored-by: Junio C Hamano \nSigned-off-by: Derrick Stolee \n---\n advice: recommend GIT_ADVICE=0 for tools\n \n I'm finally getting around to this doc update that I promised [1] a few\n weeks ago.\n \n [1]\n https://lore.kernel.org/git/e90949ed-8065-4498-9ddb-3d5c6afa7b35@gmail.com/\n \n Thanks, -Stolee\n\nPublished-As: https://github.com/gitgitgadget/git/releases/tag/pr-1781%2Fderrickstolee%2Fadvice-docs-v2\nFetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1781/derrickstolee/advice-docs-v2\nPull-Request: https://github.com/gitgitgadget/git/pull/1781\n\nRange-diff vs v1:\n\n 1: 52f6450bbf8 ! 1: aacc8c06017 advice: recommend GIT_ADVICE=0 for tools\n @@ Commit message\n option. The environment variable presents a way to change the behavior\n of Git versions that understand it without disrupting older versions.\n \n + Co-authored-by: Junio C Hamano \n Signed-off-by: Derrick Stolee \n \n ## Documentation/config/advice.txt ##\n -@@\n - advice.*::\n +@@ Documentation/config/advice.txt: advice.*::\n \tThese variables control various optional help messages designed to\n --\taid new users. When left unconfigured, Git will give the message\n --\talongside instructions on how to squelch it. You can tell Git\n + \taid new users. When left unconfigured, Git will give the message\n + \talongside instructions on how to squelch it. You can tell Git\n -\tthat you do not need the help message by setting these to `false`:\n -+\taid new users. These are output to `stderr` by default as they are\n -+\tintended to help human readers. Tools that execute Git as a subprocess\n -+\tcan disable these messages by setting `GIT_ACVICE=0` in the environment.\n ++\tthat you have understood the issue and no longer need a specific\n ++\thelp message by setting the corresponding variable to `false`.\n ++\n -+When left unconfigured, Git will give the message alongside instructions on how\n -+to squelch it. You can tell Git that you do not need the help message by\n -+setting these to `false`:\n ++As they are intended to help human users, these messages are output to\n ++the standard error. When tools that run Git as a subprocess find them\n ++disruptive, they can set `GIT_ADVICE=0` in the environment to squelch\n ++all advice messages.\n +\n --\n \taddEmbeddedRepo::\n\n\n Documentation/config/advice.txt | 8 +++++++-\n Documentation/git.txt | 11 +++++++++++\n 2 files changed, 18 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/config/advice.txt b/Documentation/config/advice.txt\nindex 0ba89898207..257db589181 100644\n--- a/Documentation/config/advice.txt\n+++ b/Documentation/config/advice.txt\n@@ -2,7 +2,13 @@ advice.*::\n \tThese variables control various optional help messages designed to\n \taid new users. When left unconfigured, Git will give the message\n \talongside instructions on how to squelch it. You can tell Git\n-\tthat you do not need the help message by setting these to `false`:\n+\tthat you have understood the issue and no longer need a specific\n+\thelp message by setting the corresponding variable to `false`.\n++\n+As they are intended to help human users, these messages are output to\n+the standard error. When tools that run Git as a subprocess find them\n+disruptive, they can set `GIT_ADVICE=0` in the environment to squelch\n+all advice messages.\n +\n --\n \taddEmbeddedRepo::\ndiff --git a/Documentation/git.txt b/Documentation/git.txt\nindex 4489e2297a3..d15a8697625 100644\n--- a/Documentation/git.txt\n+++ b/Documentation/git.txt\n@@ -1027,6 +1027,17 @@ standard output.\n \tadequate and support for it is likely to be removed in the\n \tforeseeable future (along with the variable).\n \n+`GIT_ADVICE`::\n+\tIf set to `0`, then disable all advice messages. These messages are\n+\tintended to provide hints to human users that may help them get out of\n+\tproblematic situations or take advantage of new features. Users can\n+\tdisable individual messages using the `advice.*` config keys. These\n+\tmessages may be disruptive to tools that execute Git processes, so this\n+\tvariable is available to disable the messages. (The `--no-advice`\n+\tglobal option is also available, but old Git versions may fail when\n+\tthis option is not understood. The environment variable will be ignored\n+\tby Git versions that do not understand it.)\n+\n Discussion[[Discussion]]\n ------------------------\n \n\nbase-commit: 2e7b89e038c0c888acf61f1b4ee5a43d4dd5e94c\n-- \ngitgitgadget\n"}]}