development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-08-25 02:35:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

CodingGuidelines: document which output goes to stdout vs. stderr

Browse source 
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>
This commit is contained in:
Eric Sunshine 2021-12-02 17:31:10 -05:00 committed by Junio C Hamano
parent e9d7761bb9
commit e258eb4800
1 changed files with 27 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

27
Documentation/CodingGuidelines
View file

@ -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.