From: Philip Oakley <philipoakley@iee.email>
To: Eric Sunshine <sunshine@sunshineco.com>, git@vger.kernel.org
Cc: "Jeff King" <peff@peff.net>, "Junio C Hamano" <gitster@pobox.com>,
"Ævar Arnfjörð Bjarmason" <avarab@gmail.com>,
"Randall Becker" <rsbecker@nexbridge.com>,
"Baruch Burstein" <bmburstein@gmail.com>
Subject: Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr
Date: Wed, 1 Dec 2021 23:27:20 +0000 [thread overview]
Message-ID: <1f0cc771-b661-42ae-e928-75c27f1dab07@iee.email> (raw)
In-Reply-To: <20211201053214.2902-1-sunshine@sunshineco.com>
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
next prev parent reply other threads:[~2021-12-01 23:27 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-01 5:32 [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr Eric Sunshine
2021-12-01 8:33 ` Fabian Stelzer
2021-12-01 13:50 ` Eric Sunshine
2021-12-01 15:14 ` Fabian Stelzer
2021-12-01 21:35 ` Junio C Hamano
2021-12-01 21:57 ` Eric Sunshine
2021-12-01 19:42 ` Jeff King
2021-12-01 20:30 ` Eric Sunshine
2021-12-01 23:27 ` Philip Oakley [this message]
2021-12-01 23:56 ` Eric Sunshine
2021-12-02 22:31 ` [PATCH v2] " Eric Sunshine
2021-12-02 23:58 ` Jeff King
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1f0cc771-b661-42ae-e928-75c27f1dab07@iee.email \
--to=philipoakley@iee.email \
--cc=avarab@gmail.com \
--cc=bmburstein@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=peff@peff.net \
--cc=rsbecker@nexbridge.com \
--cc=sunshine@sunshineco.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).