On 01/12/2021 05:32, Eric Sunshine wrote: > It has long been practice in this project for a command to emit its > primary output to stdout so that it can be captured to a file or sent > down a pipe, and to emit "chatty" messages (such as those reporting > progress) to stderr so that they don't interfere with the primary > output. However, this idiomatic Unix practice is not necessarily > universally understood and may be at odds with other schools of thought, > such as the somewhat common one that only error messages should go to > stderr, and all other messages to stdout. Let's help newcomers by > documenting how stdout and stderr are used on this project. > > Signed-off-by: Eric Sunshine <sunshine@xxxxxxxxxxxxxx> > --- > Documentation/CodingGuidelines | 26 ++++++++++++++++++++++++++ > 1 file changed, 26 insertions(+) > > diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines > index 711cb9171e..44dd178dc9 100644 > --- a/Documentation/CodingGuidelines > +++ b/Documentation/CodingGuidelines > @@ -499,6 +499,32 @@ For Python scripts: > - Where required libraries do not restrict us to Python 2, we try to > also be compatible with Python 3.1 and later. > > + > +Program Output > + > + We make a distinction between a command's primary output and output > + which is merely chatty feedback (for instance, status messages, > + running transcript, or progress display), as well as error messages. > + Roughly speaking, a command's primary output is that which one might > + want to capture to a file or send down a pipe; its chatty output > + should not interfere with those use-cases. Is there a case for commenting on whether chatty output may be suppressed if not feeding a terminal, or is that mentioned elsewhere? I often see comments about the isatty() detection. > + > + As such, primary output should be sent to the standard output stream > + (stdout), and chatty output should be sent to the standard error > + stream (stderr). Examples of commands which produce primary output > + include `git log`, `git show`, and `git branch --list` which generate > + output on the stdout stream. > + > + Not all commands have primary output; this is often true of commands > + whose main function is to perform an action. Some action commands are > + silent, whereas others are chatty. An example of a chatty action > + commands is `git clone` with its "Cloning into '<path>'..." and > + "Checking connectivity..." status messages which it sends to the > + stderr stream. > + > + Error messages are always sent to the stderr stream. > + > + > Error Messages > > - Do not end error messages with a full stop. Philip
