[dec0dedab0de]

Please don't ever make the short version of a cli flag be different than the long version.

The short version is for typing on the fly, and the long version is for scripts, they should have identical output.

The full thorough documentation should be in man, and/or info.

[joshka]

My perspective on the rationale for splitting short/long help is that optimizing for the reader's time is a reasonable thing to do. Often I just need a refresher of what options are available. But sometimes I need a deeper understanding of what each option controls and how. (Yes I understand that this should be in man pages). There needs to be a reasonable way to control the verbosity of the help output from the command line however.

I agree with your point that most flags should generally treat short versions as exact aliases to long flags, but I just think that a convention that treats -h and --help as concise vs long is 100% reasonable. The distinction is often breadth vs depth.

[dec0dedab0de]

That would be a perfectly reasonable convention, except it's already a convention that they do the same thing.

Having them be different could cause someone to look at -h, and not even know about --help. Or if someone writes a script parsing the output of -h for some reason, someone else might come along and change it to --help expecting it to be the same thing.

[joshka]

The rust crate clap which is one of the more well known crates for command line parsing gets about 2M downloads a day and has this convention built in.

This convention existed before clap came into being, but I don't recall when I first saw it. I have been using the command line for just shy of 40 years across various operating systems.

[forsalebypwner]

100% agree, not sure where this idea came from but I'm not a fan.

You can just make a `--help-all` (or whatever word you want to use), imo the `--help-all` command doesn't need a short equivalent because it's not something you'd frequently use.