Write explicit -help output to stdout (#17308)

* Write explicit -help output to stdout

Per the consensus of most programs, and mirroring the GNU Coding
Standards for CLI design, when users request -help explicitly via the
CLI, this should be written to stdout to allow paging of output. stderr
is fine when an invalid usage triggers the help text however.

In our case, mitchellh/cli helpfully adds a HelpWriter that we
previously set to stderr explicitly. This writer is only called to print
user-requested help text; it is not called on error cases (e.g., bad
usage triggering additional help text to the user).

Thus it should safely be settable to stdout, enabling pagers without
additional redirects.

Notably, we do have to set ErrorWriter as it defaults to initializing to
the value of HelpWriter, which we want to set to stdout now, which is
less useful.

See also: https://www.gnu.org/prep/standards/html_node/_002d_002dhelp.html
Resolves: #17004

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add changelog

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Alexander Scheel 2022-09-26 12:15:48 -04:00 committed by GitHub
parent 5bcd0c31cb
commit 3eaa4b0d75
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 5 additions and 1 deletions

3
changelog/17308.txt Normal file
View File

@ -0,0 +1,3 @@
```release-note:improvement:
cli: User-requested -help text now appears on stdout for paging rather than stderr
```

View File

@ -228,7 +228,8 @@ func RunCustom(args []string, runOpts *RunOptions) int {
HelpFunc: groupedHelpFunc( HelpFunc: groupedHelpFunc(
cli.BasicHelpFunc("vault"), cli.BasicHelpFunc("vault"),
), ),
HelpWriter: runOpts.Stderr, HelpWriter: runOpts.Stdout,
ErrorWriter: runOpts.Stderr,
HiddenCommands: hiddenCommands, HiddenCommands: hiddenCommands,
Autocomplete: true, Autocomplete: true,
AutocompleteNoDefaultFlags: true, AutocompleteNoDefaultFlags: true,