CodingGuidelines: document which output goes to stdout vs. stderr
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> Acked-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Eric Sunshine committed
Dec 2, 2021 at 17:31 UTC
e258eb4800e30da2adbdb2df8d8d8c19d9b443e4
1 file changed
+27
Documentation/CodingGuidelines
+27
@@ -499,6 +499,33 @@ For Python scripts:
499
- Where required libraries do not restrict us to Python 2, we try to
500
also be compatible with Python 3.1 and later.
501
502
+
503
+Program Output
504
+
505
+ We make a distinction between a Git command's primary output and
506
+ output which is merely chatty feedback (for instance, status
507
+ messages, running transcript, or progress display), as well as error
508
+ messages. Roughly speaking, a Git command's primary output is that
509
+ which one might want to capture to a file or send down a pipe; its
510
+ chatty output should not interfere with these use-cases.
511
+
512
+ As such, primary output should be sent to the standard output stream
513
+ (stdout), and chatty output should be sent to the standard error
514
+ stream (stderr). Examples of commands which produce primary output
515
+ include `git log`, `git show`, and `git branch --list` which generate
516
+ output on the stdout stream.
517
+
518
+ Not all Git commands have primary output; this is often true of
519
+ commands whose main function is to perform an action. Some action
520
+ commands are silent, whereas others are chatty. An example of a
521
+ chatty action commands is `git clone` with its "Cloning into
522
+ '<path>'..." and "Checking connectivity..." status messages which it
523
+ sends to the stderr stream.
524
+
525
+ Error messages from Git commands should always be sent to the stderr
526
+ stream.
527
+
528
+
529
Error Messages
530
531
- Do not end error messages with a full stop.