Should --help text be consistently written to stdout?

[varungandhi-src]

For src CLI, it looks like help text with --help is output to either stderr or a mix of stdout and stderr.

For example, src --help seems to output everything to stderr. src lsif upload --help seems to output some text to stdout and some to stderr.

In either case, you need an extra 2&>1 if you want to pipe the output to a pager. My understanding is outputting help text to stderr is intentionally the default behavior for the flag package. (https://github.com/golang/go/issues/17284, https://cs.opensource.google/go/go/+/refs/tags/go1.17.5:src/flag/flag.go;l=369;drc=refs%2Ftags%2Fgo1.17.5)

Since src is likely to be used by more non-Go developers compared to Go developers, would it make sense to consistently output the help text to stdout instead?

[chrispine]

@varungandhi-src Could you ask around in Slack to see what behavior people expect with this? Once we have that, we'll prioritize a fix. Thanks!

[varungandhi-src]

Poll in Slack didn't gather a lot of data points:

• +4 for stdout (including my own vote)
• +2 for stderr

[mrnugget]

I think the answers to this SO question are quite good and make sense:

• if the user explicitly asked for --help output by providing --help then the help text is not an error and should be displayed on stdout
• if the user can a command the wrong way and we need to print help output to guide them, it should be printed on stderr
• when in doubt or if it's hard to implement: use stdout for everything