Hacker News Reader

Comment by dredmorbius | Hacker News Reader

There's a case where this might be valid, which is where a command-line invocation is incorrect and a utility provides help as part of an error message. In that case, writing to stderr is justifiable.

(Of course, an alternative argument is that commands should fail silently but emit a nonzero return value.)

When invoked directly, as with '-h' '--help', etc., help output should write to stdout, and not stderr.

StackOverflow has tackled this question, 2nd response follows the course I suggest:

<https://stackoverflow.com/questions/1068020/app-help-should-...>

And in this case, the first response:

<https://stackoverflow.com/questions/2199624/should-the-comma...>

I'm looking for any specific guidance from, e.g., GNU but am not finding any.

View on HN

> In that case, writing to stderr is justifiable.

More than justifiable, I'd say it's the correct thing to do in that case. Otherwise, the caller (which can be another script) may end up working with the help message thinking it was the output it expected.

The whole rule should be something like "Print to stdout if it's part of what's asked by the caller. Print to stderr if it wasn't asked but the user should know about it." So outputting it to stdout should happen when it's asked via --help, and outputting it to stderr should happen when it's part of an error.

The traditional Unix command "philosophy" is that commands succeed quietly, using their termination status to indicate all is well. Failing quietly was never a part of it.

Chatter on success reads like a cheesy sci fi script.

  > copy * dir
  34 files copied, captain!

  > mount plasma_cannon /dev/sdc
  plasma_cannon mounted, ready to fire, captain!

A message like "incorrect arguments, use --help" can itself go to stderr. Not --help itself though.

Some GNU guidance is in the GNU Coding Standards:

https://www.gnu.org/prep/standards/standards.html#Command_00...

That does say that --help and --version should go to standard output.

The document also gives a list of common options; i.e. don't invent your own name for an option, if something matches in this list.

Fair point on succeed quietly.

ESR's a somewhat less reliable narrator on many topics these days, but his TAOUP remains useful, and indeed suggests "Rule of Repair: Repair what you can — but when you must fail, fail noisily and as soon as possible."

<https://www.catb.org/~esr/writings/taoup/html/ch01s06.html>

Meta-rule of Postel's Law:

Postel's Law does not count among "repair what you can". Do not try to repair Postel's Law as ESR is doing here; it's broken beyond repair and can only be replaced.

- Rarely repair a bad input; it is optional at your discretion. Just fail.

- If you repair a bad input, do it only in order to try to diagnose more of that input; more things could be wrong, or the first failure encountered could even have a root cause in those other things.

- Remember to fail if you repaired the bad input, even if there are no more errors after the repair.

> Failing quietly was never a part of it.

Not part of it, but not against it. It's useful to stay quiet when the program is meant for conditions and failure is normal. For example: `test`/`[`, `false`, `grep` (when no matches are found), etc. Also when the program is meant as a sort of wrapper to other programs, like `ssh localhost false`, `script -qec false /dev/null`, `true | xargs false`, etc.

> A message like "incorrect arguments, use --help" can itself go to stderr. Not --help itself though.

I don't agree that it's incorrect to save the user the step of calling --help, when it's obvious they need to see that info from an incorrect call. Once decided that including the --help message in an error is right, I don't think it's correct to include it in stdout when it's not expected.

This isn't an odd behavior either, including the --help message (or at least just the synopsis) in stderr on incorrect options is the behavior I'm seeing in utilities like GNU's `bash`, `grep`, and OpenBSD's `netcat`, for example.

If that bad command is in in a script where it is run 1000 times in a loop you don't want 1000 copies of the help text.

The user doesn't always need help; maybe they just made a typo.

Spewing help on every error gets old, fast. Much faster than a Unix graybeard gets old.

Take grep as an example.

If it doesn't find a match for the specified regex, it fails silently (and exits with a return value of 1).

If the file isn't found, then grep reports that error, e.g.,

  $ grep foo /doesnotexist
  grep: /doesnotexist: No such file or directory

Mind that it's quite possible that that error might result from an improperly quoted or escaped multi-term regex (containing whitespace), e.g.,

  $ grep foo bar baz /etc/bashrc
  grep: bar: No such file or directory
  grep: baz: No such file or directory

In a well-designed bash script, you'd test the file and quote the regex, e.g.,

  test -f somefile && grep 'foo bar baz' somefile

Grep is verbose on error where that's useful, but not overly so.

A tool which returns a (brief) usage note is "magick" (from the ImageMagick suite):

  $ magick --asdf
  Error: Invalid argument or not enough arguments
  
  Usage: magick tool [ {option} | {image} ... ] {output_image}
  Usage: magick [ {option} | {image} ... ] {output_image}
         magick [ {option} | {image} ... ] -script {filename} [ {script_args} ...]
         magick -help | -version | -usage | -list {option}

There are others I've encountered which return a much longer help set. I believe opkg from OpenWRT is amongst those, which prints over 80 lines worth of options to stderr when given an invalid argument.

Yeah, but if it's run interactively a quick hint (and not the full help message) can be useful.

You can't tell that in the program itself. Whether standard input is a TTY isn't a reliable indicator in either way. Though if you insist on spewing help text along side diagnostics, at least refraining from doing that to a non-TTY device might not be a bad idea.

interactive and non-interactive use should diverge as little as possible.

Personal, I like it, when a program directs me to its help-command, when I give it a bad option, like

    > openssl blabla
    Invalid command 'blabla'; type "help" for a list.

Specific guidance from GNU:

https://www.gnu.org/prep/standards/html_node/_002d_002dhelp....

> The standard --help option should output brief documentation for how to invoke the program, on standard output, then exit successfully.

I think you missed the point. The guidance you quote doesn't cover the case described.

Can you be explicit with what they are missing, I’m clearly missing it as well?

OP says please have —help post to stdout, GNU guidance posted above says exact same thing?

> Can you be explicit with what they are missing, I’m clearly missing it as well?

There are two cases when a CLI program can print its usage

1. when the `--help` option, or often also the short-option `-h`, is passed to the program

2. When the user passes a wrong option to the program, where first the error is printed and then often also the general usage.

For 1. the output always should be on stdout, but for 2. the error should be on stderr, and it might be warranted that in that case the usage might be printed on stderr too, so that all is on the same stream.

Doing 2. is not a must though, one can also go for an output like:

  > error message
  > Try 'program-name --help' for more information

This avoids "hiding" the actual error in the often rather big amount of usage-text while still hinting how to get information about what options the program expects and/or accepts.

3. With no input when input is required.

This is a special case of 2, but is distinctly different since no context can be inferred.

In my opinion the program should fail successfully (as in non zero return) since no command was given. I'm highly annoyed when kubectl starts spuwing help text when I forget the command somewhere in a script.

Can we also find a "special place" for programs who always output the help text to stderr no matter what and have pages of options? I don't want to be redirecting before beging able to grep...

Yes, the OP is explicitly talking about case 1, and the quoted GNU docs are as well?

IMO it does.

I remember when they have realized that this is a bug for the GNU false utility and changed it. I thought it was funny.

The original "task failed successfully".

Thanks, that would be what I was looking for.

This is exactly how I write my Bash functions. I didn't even realize it was a standard, it just made the most sense to me. Being given help via a --help argument is intentional and thus appropriate for STDOUT (and a return code of 0); being given help after an argument error makes sense to go to STDERR (and a return code of 2, "USAGE").

Since you can nest functions in Bash (did you know?), I usually have a help function within the main function that is called from both logic branches and just outputs to the right file descriptor.

> (did you know?)

Yes, but they are not scoped to the parent:

  $ foo()
  > {
  >    bar()
  >    {
  >       echo 42
  >    }
  > }
  $ foo
  $ bar # bar can be called though we are not in foo!
  42

Probably the most profitable use for this is for individual functions to override some callback.

But without even dynamic scope, you have no nice way of restoring the previous one, which could be one that some intermediate caller installed for itself.

It could be used to delay the definition of functions. Say that for whatever reason, we put a large number of functions into a file and don't need them all to be defined at once. There can be functions which, when invoked, define sets of functions.

A module could be written in which certain functions are intended to be clobbered by the user with its own implementation. A function which defines those functions to their original state would be useful to recover from a bad redefinition, without reloading that module.

That is unfortunate and true.

I wish I could use Elixir as a shell scripting language without incurring the VM startup cost and losing the ability to export shell variables or create shell functions... Maybe it would make sense for someone to hack its REPL to dupe most of what one would need on a commandline

Are you sure? I would be astonished if Erlang didn't have a way to export environment variables for child processes.

In a language that provides nothing beyond a function that lets you run system commands, you can control the child's environment via the env utility:

   system("env FOO=bar command arg ...");

The context here is that I may want to run an Elixir script from a Bash command line which results in some environment variables being changed. I don't think that's possible unless that script itself sends that env command to STDOUT, and I then capture it and eval it on the Bash side. Which seems... inelegant.

Hm, and not with `local bar` either, bit of a shame. I think at the point that mattered I wouldn't want to be using bash though! It's nice just as a grouping, 'this is related to that' sort of thing.

> 2nd response (…) And in this case, the first response

There’s a “Share” link under each answer that you can use to link directly to them. In this case it’s impossible to know which answer you mean because we don’t know what’s your “Sorted by” option. But even then, the order changes over time.

Reply on news.ycombinator.com