Because accuracy matters. The reverse case applies with `getopts --help` vs. `getopt --help` as well as with `dir --help` vs. `dirs --help`.
Cheers, Wiley On Sun, Aug 10, 2025, 17:38 Lawrence Velázquez <v...@larryv.me> wrote: > On Sun, Aug 10, 2025, at 7:47 PM, Wiley Young wrote: > > Well, by common convention, I suppose. A great many system commands do > > offer a '--help' option. In comparison very few system commands have > shell > > builtins with the same name. Most of the time, whenever anyone types in > > `[CMD] --help` interactively, they're looking for the help file from a > > binary command. That's why. > > No. They're looking for help for the same command that would run > if they ran CMD with any other arguments, regardless of whether > it's built-in or external. That's why bash's built-ins recognize > a "--help" argument in the first place. > > > > "See also: /bin/kill --help" might be a worthwhile addition to the output > > of `help kill`, in my opinion. > > Firstly, there might be multiple external implementations available, > not just /bin/kill (if that's even the right location on the user's > system). How would bash know which one is the "best" one to draw > attention to? > > Secondly, why point users to the documentation of an implementation > they don't intend to use? So they can get confused when they try > doing something with plain "kill" and it disagrees with what that > other documentation says? > > > > The '--timeout' option for /bin/kill is particularly useful. > > GNU kill is not the only external implementation. > > > > Since people > > learn how, in part, to use commands from the outputs of `[CMD] --help`, > > obfuscating that info seems counterproductive. > > It's not obfuscation. "Other implementations may work differently" > is something you could say about literally any command, anywhere. > Should they all waste text pointing this out? Should the bash > documentation go out of its way to mention that dash, ksh, and zsh > work differently, as well? > > > > Besides, '--help' isn't a listed option for builtin kill (or printf). > > > > $ builtin kill ps; echo $? > > bash: kill: ps: arguments must be process or job IDs > > 1 > > > > The string '--help' is obviously neither (process ID nor job ID), but > > there's no formal error message. > > GNU kill doesn't mention "--help" in this scenario either. > > In any case, this would be trivial to change, if desired. > > > > Rather the help file for builtin kill is > > printed, when it isn't positively known either way which help message any > > user at the CLI might want to see. > > This is like arguing that when the user runs > > kill > > "it isn't positively known either way which [implementation] any > user at the CLI might want to [use]." Strictly speaking, true. > In practice, not a useful thing to think about. > > The shell cannot read the user's mind. The only sane thing to do > is follow the established command lookup procedure. The presence > of a "--help" argument doesn't change that. > > > > In `man bash` the only mention of '--help' is in the OPTIONS section near > > the top, where it's intended to refer to `bash --help`. That > command/option > > combo prints a help file for the bash binary. In the last 10 lines > thereof, > > there are some pointers about how to get some more information on shell > > builtins. > > > > Perhaps (builtin) `kill --help` should print the same output as `bash > > --help`? In that case, at least any help file printed from a '--help' > > option would consistently refer to the optargs of a binary. > > Responding to the user's request for help with one command (kill) > by printing information for a different command (bash) would not > be helpful. > > > -- > vq >
