Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr

[Philip Oakley <philipoakley@iee.email>]

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@sunshineco.com>
> ---
>  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