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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Dec 2, 2021, 22:31 UTC
Message-ID: <20211202223110.22062-1-sunshine@sunshineco.com>
In-Reply-To: <20211201053214.2902-1-sunshine@sunshineco.com>

It has long been practice on 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 practice is not necessarily universal; another common practice is to send only error messages to stderr, and all other messages to stdout. Therefore, help newcomers out by documenting how stdout and stderr are used on this project.

Signed-off-by: Eric Sunshine <sunshine@sunshineco.com>
---

Changes since v1[*]:

* tone down the commit message (peff)

* replace "command" in the patch body with "Git command" in a few places
  to make it more clear that the new "Program Output" section is
  providing guidelines for how Git commands should behave, as opposed
  to, say, how stdout/stderr should be used in test scripts (fabian)

No interdiff/range-diff since they are too noisy in this case, and the patch is short enough to easily re-read in its entirety.

[*]: https://lore.kernel.org/git/20211201053214.2902-1-sunshine@sunshineco.com/

 Documentation/CodingGuidelines | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 711cb9171e..0e27b5395d 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -499,6 +499,33 @@ 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 Git 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 Git 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 these 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 Git 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 from Git commands should always be sent to the stderr
+ stream.
+
+
 Error Messages
 
  - Do not end error messages with a full stop.

-- 
2.34.1.173.g76aa8bc2d0