Why does "git submodule add ..." write to stderr rather than stdout?

The message

Cloning into 'sub-mod'...
done.

after a git submodule add... command is written to stderr. I expected the message to be written to stdout since I don't think it indicates something went wrong with the command.

I can reproduce this with the following sequence of commands:

rm   -rf /tmp/repo /tmp/module
mkdir    /tmp/repo /tmp/module

cd /tmp/module

git init  > /dev/null
echo "foo" > foo;
git add foo > /dev/null
git commit . -m "+ foo" > /dev/null


cd /tmp/repo

git init > /dev/null
git submodule add /tmp/module/ sub-mod 1> /dev/null

If I change the redirection in the last command to ... 2> /dev/null, nothing is printed.

Solution 1:

This is not limited to submodules, as noted here:

The registration of the submodule will be reported to stderr, as that is consistent with the rest of progress reporting within Git.

This helps us in a later patch when we want to reuse the init_submodule function in update_clone whose stdout will be piped to shell which reads parameters off stdout in a very specific way.

You can see it also in this recent patch:

Reroute the output of stdout to stderr as it is just informative messages, not to be consumed by machines.

We want to init submodules from the helper for submodule update in a later patch and the stdout output of said helper is consumed by the parts of submodule update which are still written in shell.

So we have to be careful which messages are on stdout.

With Git 2.35 (Q1 2022), coding guideline document has been updated to clarify what goes to standard error in our system.

See commit e258eb4 (02 Dec 2021) by Eric Sunshine (sunshineco).
^{(Merged by Junio C Hamano -- gitster -- in commit 212962d, 15 Dec 2021)}

CodingGuidelines: document which output goes to stdout vs. stderr

^{Signed-off-by: Eric Sunshine
Acked-by: Jeff King}

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.

CodingGuidelines now includes in its man page:

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 ''..." 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.