From: Fabian Stelzer <fs@gigacodes.de>
To: Eric Sunshine <sunshine@sunshineco.com>
Cc: git@vger.kernel.org, "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 09:33:01 +0100 [thread overview]
Message-ID: <20211201083301.ozrhi2brjk4zx5ll@fs> (raw)
In-Reply-To: <20211201053214.2902-1-sunshine@sunshineco.com>
On 01.12.2021 00: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.
>+
>+ 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.
>+
This is not necessarily true in the context of the tests.
We just spoke about this in:
https://lore.kernel.org/git/211130.86wnkpd6ou.gmgdl@evledraar.gmail.com/T/#u
I don't think it necessary to bloat this explanation with the test details.
But mentioning it as an exception would be good.
next prev parent reply other threads:[~2021-12-01 8:33 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 [this message]
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
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=20211201083301.ozrhi2brjk4zx5ll@fs \
--to=fs@gigacodes.de \
--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).