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@xxxxxxxxxxxxxx>
---
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.
+
+
Error Messages
- Do not end error messages with a full stop.
--
2.34.1.75.gabe6bb3905
