{"thread":{"id":"57008","subject":"[PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","startedAt":"2021-12-01T05:33:24Z","lastAt":"2021-12-02T23:58:48Z","messageCount":12,"participants":["Eric Sunshine","Fabian Stelzer","Jeff King","Junio C Hamano","Philip Oakley"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"442742","messageId":"20211201053214.2902-1-sunshine@sunshineco.com","threadId":"57008","inReplyTo":null,"subject":"[PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-01T05:32:14Z","receivedAt":"2021-12-01T05:33:24Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"It has long been practice in this project for a command to emit its\nprimary output to stdout so that it can be captured to a file or sent\ndown a pipe, and to emit \"chatty\" messages (such as those reporting\nprogress) to stderr so that they don't interfere with the primary\noutput. However, this idiomatic Unix practice is not necessarily\nuniversally understood and may be at odds with other schools of thought,\nsuch as the somewhat common one that only error messages should go to\nstderr, and all other messages to stdout. Let's help newcomers by\ndocumenting how stdout and stderr are used on this project.\n\nSigned-off-by: Eric Sunshine \n---\n Documentation/CodingGuidelines | 26 ++++++++++++++++++++++++++\n 1 file changed, 26 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 711cb9171e..44dd178dc9 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -499,6 +499,32 @@ For Python scripts:\n - Where required libraries do not restrict us to Python 2, we try to\n also be compatible with Python 3.1 and later.\n \n+\n+Program Output\n+\n+ We make a distinction between a command's primary output and output\n+ which is merely chatty feedback (for instance, status messages,\n+ running transcript, or progress display), as well as error messages.\n+ Roughly speaking, a command's primary output is that which one might\n+ want to capture to a file or send down a pipe; its chatty output\n+ should not interfere with those use-cases.\n+\n+ As such, primary output should be sent to the standard output stream\n+ (stdout), and chatty output should be sent to the standard error\n+ stream (stderr). Examples of commands which produce primary output\n+ include `git log`, `git show`, and `git branch --list` which generate\n+ output on the stdout stream.\n+\n+ Not all commands have primary output; this is often true of commands\n+ whose main function is to perform an action. Some action commands are\n+ silent, whereas others are chatty. An example of a chatty action\n+ commands is `git clone` with its \"Cloning into ''...\" and\n+ \"Checking connectivity...\" status messages which it sends to the\n+ stderr stream.\n+\n+ Error messages are always sent to the stderr stream.\n+\n+\n Error Messages\n \n - Do not end error messages with a full stop.\n-- \n2.34.1.75.gabe6bb3905\n\n"},{"id":"442756","messageId":"20211201083301.ozrhi2brjk4zx5ll@fs","threadId":"57008","inReplyTo":"20211201053214.2902-1-sunshine@sunshineco.com","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Fabian Stelzer","fromEmail":"fs@gigacodes.de","sentAt":"2021-12-01T08:33:01Z","receivedAt":"2021-12-01T08:33:08Z","isPatch":true,"sender":{"key":"fs@gigacodes.de","avatar":"https://avatars.githubusercontent.com/u/564858?v=4"},"body":"On 01.12.2021 00:32, Eric Sunshine wrote:\n>It has long been practice in this project for a command to emit its\n>primary output to stdout so that it can be captured to a file or sent\n>down a pipe, and to emit \"chatty\" messages (such as those reporting\n>progress) to stderr so that they don't interfere with the primary\n>output. However, this idiomatic Unix practice is not necessarily\n>universally understood and may be at odds with other schools of thought,\n>such as the somewhat common one that only error messages should go to\n>stderr, and all other messages to stdout. Let's help newcomers by\n>documenting how stdout and stderr are used on this project.\n>\n>Signed-off-by: Eric Sunshine \n>---\n> Documentation/CodingGuidelines | 26 ++++++++++++++++++++++++++\n> 1 file changed, 26 insertions(+)\n>\n>diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n>index 711cb9171e..44dd178dc9 100644\n>--- a/Documentation/CodingGuidelines\n>+++ b/Documentation/CodingGuidelines\n>@@ -499,6 +499,32 @@ For Python scripts:\n> - Where required libraries do not restrict us to Python 2, we try to\n> also be compatible with Python 3.1 and later.\n>\n>+\n>+Program Output\n>+\n>+ We make a distinction between a command's primary output and output\n>+ which is merely chatty feedback (for instance, status messages,\n>+ running transcript, or progress display), as well as error messages.\n>+ Roughly speaking, a command's primary output is that which one might\n>+ want to capture to a file or send down a pipe; its chatty output\n>+ should not interfere with those use-cases.\n>+\n>+ As such, primary output should be sent to the standard output stream\n>+ (stdout), and chatty output should be sent to the standard error\n>+ stream (stderr). Examples of commands which produce primary output\n>+ include `git log`, `git show`, and `git branch --list` which generate\n>+ output on the stdout stream.\n>+\n>+ Not all commands have primary output; this is often true of commands\n>+ whose main function is to perform an action. Some action commands are\n>+ silent, whereas others are chatty. An example of a chatty action\n>+ commands is `git clone` with its \"Cloning into ''...\" and\n>+ \"Checking connectivity...\" status messages which it sends to the\n>+ stderr stream.\n>+\n>+ Error messages are always sent to the stderr stream.\n>+\n\nThis is not necessarily true in the context of the tests.\nWe just spoke about this in: \nhttps://lore.kernel.org/git/211130.86wnkpd6ou.gmgdl@evledraar.gmail.com/T/#u\n\nI don't think it necessary to bloat this explanation with the test details. \nBut mentioning it as an exception would be good.\n"},{"id":"442772","messageId":"CAPig+cRFqO5wcZTPrpTuiBP72+6enJs+---mjT2AFAQq5ztt_w@mail.gmail.com","threadId":"57008","inReplyTo":"20211201083301.ozrhi2brjk4zx5ll@fs","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-01T13:50:47Z","receivedAt":"2021-12-01T13:54:15Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Dec 1, 2021 at 3:33 AM Fabian Stelzer wrote:\n> On 01.12.2021 00:32, Eric Sunshine wrote:\n> >+ We make a distinction between a command's primary output and output\n> >+ which is merely chatty feedback (for instance, status messages,\n> >+ running transcript, or progress display), as well as error messages.\n> >+ Roughly speaking, a command's primary output is that which one might\n> >+ want to capture to a file or send down a pipe; its chatty output\n> >+ should not interfere with those use-cases.\n> >+\n> >+ As such, primary output should be sent to the standard output stream\n> >+ (stdout), and chatty output should be sent to the standard error\n> >+ stream (stderr). Examples of commands which produce primary output\n> >+ include `git log`, `git show`, and `git branch --list` which generate\n> >+ output on the stdout stream.\n> >+\n> >+ Not all commands have primary output; this is often true of commands\n> >+ whose main function is to perform an action. Some action commands are\n> >+ silent, whereas others are chatty. An example of a chatty action\n> >+ commands is `git clone` with its \"Cloning into ''...\" and\n> >+ \"Checking connectivity...\" status messages which it sends to the\n> >+ stderr stream.\n> >+\n> >+ Error messages are always sent to the stderr stream.\n>\n> This is not necessarily true in the context of the tests.\n> We just spoke about this in:\n> https://lore.kernel.org/git/211130.86wnkpd6ou.gmgdl@evledraar.gmail.com/T/#u\n>\n> I don't think it necessary to bloat this explanation with the test details.\n> But mentioning it as an exception would be good.\n\nYep, I tried to be clear about that by repeatedly stating that\n_command_ output should follow this guideline, where \"command\" means\n\"Git command\". I strongly considered writing \"Git command\" to be\nperfectly clear, but figured reviewers would insist that it was\nredundant to mention \"Git\".\n\nHowever, I can certainly change these to say \"Git command\" if you\nthink it would make the intent clearer, and can update the final point\nto say:\n\n Error messages from Git commands should always\n be sent to the stderr stream.\n"},{"id":"442779","messageId":"20211201151427.6z3stwrodxbjwzf5@fs","threadId":"57008","inReplyTo":"CAPig+cRFqO5wcZTPrpTuiBP72+6enJs+---mjT2AFAQq5ztt_w@mail.gmail.com","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Fabian Stelzer","fromEmail":"fs@gigacodes.de","sentAt":"2021-12-01T15:14:27Z","receivedAt":"2021-12-01T15:15:16Z","isPatch":true,"sender":{"key":"fs@gigacodes.de","avatar":"https://avatars.githubusercontent.com/u/564858?v=4"},"body":"On 01.12.2021 08:50, Eric Sunshine wrote:\n>On Wed, Dec 1, 2021 at 3:33 AM Fabian Stelzer wrote:\n>> On 01.12.2021 00:32, Eric Sunshine wrote:\n>> >+ We make a distinction between a command's primary output and output\n>> >+ which is merely chatty feedback (for instance, status messages,\n>> >+ running transcript, or progress display), as well as error messages.\n>> >+ Roughly speaking, a command's primary output is that which one might\n>> >+ want to capture to a file or send down a pipe; its chatty output\n>> >+ should not interfere with those use-cases.\n>> >+\n>> >+ As such, primary output should be sent to the standard output stream\n>> >+ (stdout), and chatty output should be sent to the standard error\n>> >+ stream (stderr). Examples of commands which produce primary output\n>> >+ include `git log`, `git show`, and `git branch --list` which generate\n>> >+ output on the stdout stream.\n>> >+\n>> >+ Not all commands have primary output; this is often true of commands\n>> >+ whose main function is to perform an action. Some action commands are\n>> >+ silent, whereas others are chatty. An example of a chatty action\n>> >+ commands is `git clone` with its \"Cloning into ''...\" and\n>> >+ \"Checking connectivity...\" status messages which it sends to the\n>> >+ stderr stream.\n>> >+\n>> >+ Error messages are always sent to the stderr stream.\n>>\n>> This is not necessarily true in the context of the tests.\n>> We just spoke about this in:\n>> https://lore.kernel.org/git/211130.86wnkpd6ou.gmgdl@evledraar.gmail.com/T/#u\n>>\n>> I don't think it necessary to bloat this explanation with the test details.\n>> But mentioning it as an exception would be good.\n>\n>Yep, I tried to be clear about that by repeatedly stating that\n>_command_ output should follow this guideline, where \"command\" means\n>\"Git command\". I strongly considered writing \"Git command\" to be\n>perfectly clear, but figured reviewers would insist that it was\n>redundant to mention \"Git\".\n>\n>However, I can certainly change these to say \"Git command\" if you\n>think it would make the intent clearer, and can update the final point\n>to say:\n>\n> Error messages from Git commands should always\n> be sent to the stderr stream.\n\nMaybe it was just because i was working on test-lib stuff earlier that i did \nnot connect `a commands output` to a `git command` but basically understood \nit as all output in git code.\nStill, I think your addition to the last sentence is a good idea and won't \nhurt.\n\nThanks\n"},{"id":"442793","messageId":"YafQMTsU2+vLNalY@coredump.intra.peff.net","threadId":"57008","inReplyTo":"20211201053214.2902-1-sunshine@sunshineco.com","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-12-01T19:42:41Z","receivedAt":"2021-12-01T19:42:45Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Dec 01, 2021 at 12:32:14AM -0500, Eric Sunshine wrote:\n\n> It has long been practice in this project for a command to emit its\n> primary output to stdout so that it can be captured to a file or sent\n> down a pipe, and to emit \"chatty\" messages (such as those reporting\n> progress) to stderr so that they don't interfere with the primary\n> output. However, this idiomatic Unix practice is not necessarily\n> universally understood and may be at odds with other schools of thought,\n> such as the somewhat common one that only error messages should go to\n> stderr, and all other messages to stdout. Let's help newcomers by\n> documenting how stdout and stderr are used on this project.\n\nI agree with everything you wrote here and below, which I think captures\nwhat we want to communicate to folks adding new messages or commands.\n\nI am not quite sure _everyone_ would agree with \"this idiomatic Unix\npractice\" above. It does seem to be a matter of taste (it is just that\nwhat you wrote very much agrees with my taste :) ). And \"idiomatic Unix\npractice\" is probably not to be chatty at all, but I think that has been\nchanging over the years.\n\nSo I'm not sure if your commit message is being nicely assertive about\nits taste, or is being uncharitable to people who may have different\ntastes (but again, IMHO we should pick a direction and this seems like\nthe best one to me). :)\n\n-Peff\n"},{"id":"442799","messageId":"CAPig+cS3Ymnfeob0UREvpvR0w7uKA7WnVqMn+ZNYOjx35x1p-Q@mail.gmail.com","threadId":"57008","inReplyTo":"YafQMTsU2+vLNalY@coredump.intra.peff.net","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-01T20:30:12Z","receivedAt":"2021-12-01T20:30:29Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Dec 1, 2021 at 2:42 PM Jeff King wrote:\n> On Wed, Dec 01, 2021 at 12:32:14AM -0500, Eric Sunshine wrote:\n> > It has long been practice in this project for a command to emit its\n> > primary output to stdout so that it can be captured to a file or sent\n> > down a pipe, and to emit \"chatty\" messages (such as those reporting\n> > progress) to stderr so that they don't interfere with the primary\n> > output. However, this idiomatic Unix practice is not necessarily\n> > universally understood and may be at odds with other schools of thought,\n> > such as the somewhat common one that only error messages should go to\n> > stderr, and all other messages to stdout. Let's help newcomers by\n> > documenting how stdout and stderr are used on this project.\n>\n> I agree with everything you wrote here and below, which I think captures\n> what we want to communicate to folks adding new messages or commands.\n>\n> I am not quite sure _everyone_ would agree with \"this idiomatic Unix\n> practice\" above. It does seem to be a matter of taste (it is just that\n> what you wrote very much agrees with my taste :) ). And \"idiomatic Unix\n> practice\" is probably not to be chatty at all, but I think that has been\n> changing over the years.\n>\n> So I'm not sure if your commit message is being nicely assertive about\n> its taste, or is being uncharitable to people who may have different\n> tastes (but again, IMHO we should pick a direction and this seems like\n> the best one to me). :)\n\nThanks for the feedback. I'll tone down the commit message when I\nreroll to make the patch text spell out \"Git command\" explicitly so\nthat it's less likely to mislead the reader (as it misled Fabian) into\nthinking the new guideline applies to all output, including test\noutput.\n"},{"id":"442808","messageId":"xmqqtufsypmu.fsf@gitster.g","threadId":"57008","inReplyTo":"CAPig+cRFqO5wcZTPrpTuiBP72+6enJs+---mjT2AFAQq5ztt_w@mail.gmail.com","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-12-01T21:35:53Z","receivedAt":"2021-12-01T21:36:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Sunshine writes:\n\n> However, I can certainly change these to say \"Git command\" if you\n> think it would make the intent clearer, and can update the final point\n> to say:\n>\n> Error messages from Git commands should always\n> be sent to the stderr stream.\n\nIn an earlier round, I think there was a version without \"should\" in\nthere, but I am sure we have bugs that do not follow the guideline.\nThe proposed phrasing sounds good to me.\n\nThanks.\n"},{"id":"442809","messageId":"CAPig+cTAg7CwYZBEMVyub05GrGkHjLSuZ_YJ-PdAQ7M_C3aMqg@mail.gmail.com","threadId":"57008","inReplyTo":"xmqqtufsypmu.fsf@gitster.g","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-01T21:57:01Z","receivedAt":"2021-12-01T21:57:15Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Dec 1, 2021 at 4:36 PM Junio C Hamano wrote:\n> Eric Sunshine writes:\n> > However, I can certainly change these to say \"Git command\" if you\n> > think it would make the intent clearer, and can update the final point\n> > to say:\n> >\n> > Error messages from Git commands should always\n> > be sent to the stderr stream.\n>\n> In an earlier round, I think there was a version without \"should\" in\n> there, but I am sure we have bugs that do not follow the guideline.\n> The proposed phrasing sounds good to me.\n\nYes, the addition of \"should\" was intentional, though not for any\nconcrete reason (it just felt appropriate). I don't feel strongly\neither way.\n"},{"id":"442828","messageId":"1f0cc771-b661-42ae-e928-75c27f1dab07@iee.email","threadId":"57008","inReplyTo":"20211201053214.2902-1-sunshine@sunshineco.com","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-12-01T23:27:20Z","receivedAt":"2021-12-01T23:27:26Z","isPatch":true,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 01/12/2021 05:32, Eric Sunshine wrote:\n> It has long been practice in this project for a command to emit its\n> primary output to stdout so that it can be captured to a file or sent\n> down a pipe, and to emit \"chatty\" messages (such as those reporting\n> progress) to stderr so that they don't interfere with the primary\n> output. However, this idiomatic Unix practice is not necessarily\n> universally understood and may be at odds with other schools of thought,\n> such as the somewhat common one that only error messages should go to\n> stderr, and all other messages to stdout. Let's help newcomers by\n> documenting how stdout and stderr are used on this project.\n>\n> Signed-off-by: Eric Sunshine \n> ---\n> Documentation/CodingGuidelines | 26 ++++++++++++++++++++++++++\n> 1 file changed, 26 insertions(+)\n>\n> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\n> index 711cb9171e..44dd178dc9 100644\n> --- a/Documentation/CodingGuidelines\n> +++ b/Documentation/CodingGuidelines\n> @@ -499,6 +499,32 @@ For Python scripts:\n> - Where required libraries do not restrict us to Python 2, we try to\n> also be compatible with Python 3.1 and later.\n> \n> +\n> +Program Output\n> +\n> + We make a distinction between a command's primary output and output\n> + which is merely chatty feedback (for instance, status messages,\n> + running transcript, or progress display), as well as error messages.\n> + Roughly speaking, a command's primary output is that which one might\n> + want to capture to a file or send down a pipe; its chatty output\n> + should not interfere with those use-cases.\n\nIs there a case for commenting on whether chatty output may be\nsuppressed if not feeding a terminal, or is that mentioned elsewhere? I\noften see comments about the isatty() detection.\n\n> +\n> + As such, primary output should be sent to the standard output stream\n> + (stdout), and chatty output should be sent to the standard error\n> + stream (stderr). Examples of commands which produce primary output\n> + include `git log`, `git show`, and `git branch --list` which generate\n> + output on the stdout stream.\n> +\n> + Not all commands have primary output; this is often true of commands\n> + whose main function is to perform an action. Some action commands are\n> + silent, whereas others are chatty. An example of a chatty action\n> + commands is `git clone` with its \"Cloning into ''...\" and\n> + \"Checking connectivity...\" status messages which it sends to the\n> + stderr stream.\n> +\n> + Error messages are always sent to the stderr stream.\n> +\n> +\n> Error Messages\n> \n> - Do not end error messages with a full stop.\nPhilip\n"},{"id":"442831","messageId":"CAPig+cTAzmaHJa3tGniO5AsL+tQO9+bZuO-AUqU+WisDEgp4UQ@mail.gmail.com","threadId":"57008","inReplyTo":"1f0cc771-b661-42ae-e928-75c27f1dab07@iee.email","subject":"Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-01T23:56:15Z","receivedAt":"2021-12-01T23:56:28Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"On Wed, Dec 1, 2021 at 6:27 PM Philip Oakley wrote:\n> On 01/12/2021 05:32, Eric Sunshine wrote:\n> > +Program Output\n> > +\n> > + We make a distinction between a command's primary output and output\n> > + which is merely chatty feedback (for instance, status messages,\n> > + running transcript, or progress display), as well as error messages.\n> > + Roughly speaking, a command's primary output is that which one might\n> > + want to capture to a file or send down a pipe; its chatty output\n> > + should not interfere with those use-cases.\n>\n> Is there a case for commenting on whether chatty output may be\n> suppressed if not feeding a terminal, or is that mentioned elsewhere? I\n> often see comments about the isatty() detection.\n\nI don't think I saw any such mention when reading through\nCodingGuidelines before composing the new text. That's certainly a\ntopic which could be addressed, but I don't plan on adding it to this\npatch since I don't have any specific idea in mind for how it would be\ndiscussed. However, the new \"Program Output\" section added by this\npatch seems a good place to add that discussion if someone wants to\nhave a go at it as a separate patch atop this one.\n"},{"id":"442916","messageId":"20211202223110.22062-1-sunshine@sunshineco.com","threadId":"57008","inReplyTo":"20211201053214.2902-1-sunshine@sunshineco.com","subject":"[PATCH v2] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Eric Sunshine","fromEmail":"sunshine@sunshineco.com","sentAt":"2021-12-02T22:31:10Z","receivedAt":"2021-12-02T22:32:08Z","isPatch":true,"sender":{"key":"sunshine@sunshineco.com","avatar":"https://avatars.githubusercontent.com/u/163641?v=4"},"body":"It has long been practice on this project for a command to emit its\nprimary output to stdout so that it can be captured to a file or sent\ndown a pipe, and to emit \"chatty\" messages (such as those reporting\nprogress) to stderr so that they don't interfere with the primary\noutput. However, this practice is not necessarily universal; another\ncommon practice is to send only error messages to stderr, and all other\nmessages to stdout. Therefore, help newcomers out by documenting how\nstdout and stderr are used on this project.\n\nSigned-off-by: Eric Sunshine \n---\n\nChanges since v1[*]:\n\n* tone down the commit message (peff)\n\n* replace \"command\" in the patch body with \"Git command\" in a few places\n to make it more clear that the new \"Program Output\" section is\n providing guidelines for how Git commands should behave, as opposed\n to, say, how stdout/stderr should be used in test scripts (fabian)\n\nNo interdiff/range-diff since they are too noisy in this case, and the\npatch is short enough to easily re-read in its entirety.\n\n[*]: https://lore.kernel.org/git/20211201053214.2902-1-sunshine@sunshineco.com/\n\n Documentation/CodingGuidelines | 27 +++++++++++++++++++++++++++\n 1 file changed, 27 insertions(+)\n\ndiff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines\nindex 711cb9171e..0e27b5395d 100644\n--- a/Documentation/CodingGuidelines\n+++ b/Documentation/CodingGuidelines\n@@ -499,6 +499,33 @@ For Python scripts:\n - Where required libraries do not restrict us to Python 2, we try to\n also be compatible with Python 3.1 and later.\n \n+\n+Program Output\n+\n+ We make a distinction between a Git command's primary output and\n+ output which is merely chatty feedback (for instance, status\n+ messages, running transcript, or progress display), as well as error\n+ messages. Roughly speaking, a Git command's primary output is that\n+ which one might want to capture to a file or send down a pipe; its\n+ chatty output should not interfere with these use-cases.\n+\n+ As such, primary output should be sent to the standard output stream\n+ (stdout), and chatty output should be sent to the standard error\n+ stream (stderr). Examples of commands which produce primary output\n+ include `git log`, `git show`, and `git branch --list` which generate\n+ output on the stdout stream.\n+\n+ Not all Git commands have primary output; this is often true of\n+ commands whose main function is to perform an action. Some action\n+ commands are silent, whereas others are chatty. An example of a\n+ chatty action commands is `git clone` with its \"Cloning into\n+ ''...\" and \"Checking connectivity...\" status messages which it\n+ sends to the stderr stream.\n+\n+ Error messages from Git commands should always be sent to the stderr\n+ stream.\n+\n+\n Error Messages\n \n - Do not end error messages with a full stop.\n-- \n2.34.1.173.g76aa8bc2d0\n\n"},{"id":"442923","messageId":"YaldtR9udlozfx9Z@coredump.intra.peff.net","threadId":"57008","inReplyTo":"20211202223110.22062-1-sunshine@sunshineco.com","subject":"Re: [PATCH v2] CodingGuidelines: document which output goes to stdout vs. stderr","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2021-12-02T23:58:45Z","receivedAt":"2021-12-02T23:58:48Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Dec 02, 2021 at 05:31:10PM -0500, Eric Sunshine wrote:\n\n> It has long been practice on this project for a command to emit its\n> primary output to stdout so that it can be captured to a file or sent\n> down a pipe, and to emit \"chatty\" messages (such as those reporting\n> progress) to stderr so that they don't interfere with the primary\n> output. However, this practice is not necessarily universal; another\n> common practice is to send only error messages to stderr, and all other\n> messages to stdout. Therefore, help newcomers out by documenting how\n> stdout and stderr are used on this project.\n> \n> Signed-off-by: Eric Sunshine \n> ---\n> \n> Changes since v1[*]:\n> \n> * tone down the commit message (peff)\n\n:) This looks great to me. Thanks for doing it.\n\n-Peff\n"}]}