From: Eric Sunshine <sunshine@sunshineco.com>
Date: Wed, 01 Dec 2021 13:50:47 GMT
Subject: Re: [PATCH] CodingGuidelines: document which output goes to stdout vs. stderr
Message-ID: <CAPig+cRFqO5wcZTPrpTuiBP72+6enJs+---mjT2AFAQq5ztt_w@mail.gmail.com>
In-Reply-To: <20211201083301.ozrhi2brjk4zx5ll@fs>

On Wed, Dec 1, 2021 at 3:33 AM Fabian Stelzer <fs@gigacodes.de> wrote:
> On 01.12.2021 00:32, Eric Sunshine wrote:
> >+ 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.

Yep, I tried to be clear about that by repeatedly stating that
_command_ output should follow this guideline, where "command" means
"Git command". I strongly considered writing "Git command" to be
perfectly clear, but figured reviewers would insist that it was
redundant to mention "Git".

However, I can certainly change these to say "Git command" if you
think it would make the intent clearer, and can update the final point
to say:

    Error messages from Git commands should always
    be sent to the stderr stream.