5 ms·

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 tha

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-go-to-stdout-or-stderr https://stackoverflow.com/questions/1068020/app-help-should-...> And in this case, the first response: <https://stackoverflow.com/questions/2199624/should-the-command-line-usage-be-printed-on-stdout-or-stderr https://stackoverflow.com/questions/2199624/should-the-comma...> I'm looking for any specific guidance from, e.g., GNU but am not finding any.

jolmg 3y ago
> 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.
anderskaseorg 3y ago
Specific guidance from GNU: https://www.gnu.org/prep/standards/html_node/_002d_002dhelp.html 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.
- rlpb 3y ago
  I think you missed the point. The guidance you quote doesn't cover the case described.
  - dredmorbius 3y ago
    IMO it does.
  - jakewins 3y ago
    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?
    - tlamponi 3y ago
      > 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.
      - consp 3y ago
        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...
      - jakewins 3y ago
        Yes, the OP is explicitly talking about case 1, and the quoted GNU docs are as well?
- dredmorbius 3y ago
  Thanks, that would be what I was looking for.
- ahoka 3y ago
  I remember when they have realized that this is a bug for the GNU false utility and changed it. I thought it was funny.
  - dredmorbius 3y ago
    The original "task failed successfully".
pmarreck 3y ago
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.
- kazinator 3y ago
  > (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.
  - OJFord 3y ago
    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.
  - pmarreck 3y ago
    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
kazinator 3y ago
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_002dLine-Interfaces 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.
- dredmorbius 3y ago
  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 https://www.catb.org/~esr/writings/taoup/html/ch01s06.html>
  - kazinator 3y ago
    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.
- jolmg 3y ago
  > 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.
latexr 3y ago
> 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.

jolmg 3y ago

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

anderskaseorg 3y ago

Specific guidance from GNU: https://www.gnu.org/prep/standards/html_node/_002d_002dhelp.html 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.

rlpb 3y ago
I think you missed the point. The guidance you quote doesn't cover the case described.
- dredmorbius 3y ago
  IMO it does.
- jakewins 3y ago
  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?
  - tlamponi 3y ago
    > 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.
    - consp 3y ago
      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...
    - jakewins 3y ago
      Yes, the OP is explicitly talking about case 1, and the quoted GNU docs are as well?
dredmorbius 3y ago
Thanks, that would be what I was looking for.
ahoka 3y ago
I remember when they have realized that this is a bug for the GNU false utility and changed it. I thought it was funny.
- dredmorbius 3y ago
  The original "task failed successfully".

pmarreck 3y ago

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.

kazinator 3y ago
> (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.
- OJFord 3y ago
  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.
- pmarreck 3y ago
  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

kazinator 3y ago

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_002dLine-Interfaces 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.

dredmorbius 3y ago
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 https://www.catb.org/~esr/writings/taoup/html/ch01s06.html>
- kazinator 3y ago
  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.
jolmg 3y ago
> 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.

latexr 3y ago

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