search

serpent-os / moss

The safe, fast and sane package manager for Linux
https://serpentos.com
71 stars 9 forks source link

-h and --help often show different information #168

Open joebonrichie opened 3 months ago

joebonrichie commented 3 months ago

e.g.

$ ~/sos/moss/target/release/boulder profile add -h
Add a new profile

Usage: boulder profile add [OPTIONS] --repo <REPOS> <NAME>

Arguments:
  <NAME>  profile name

Options:
      --cache-dir <CACHE_DIR>    
  -r, --repo <REPOS>             repository to add to profile, can be passed multiple times
      --config-dir <CONFIG_DIR>  
      --data-dir <DATA_DIR>      
      --moss-root <MOSS_ROOT>    
  -h, --help                     Print help (see more with '--help')

vs

$ ~/sos/moss/target/release/boulder profile add --help
Add a new profile

Usage: boulder profile add [OPTIONS] --repo <REPOS> <NAME>

Arguments:
  <NAME>
          profile name

Options:
      --cache-dir <CACHE_DIR>

  -r, --repo <REPOS>
          repository to add to profile

          Example: --repo name=volatile,uri=https://dev.serpentos.com/volatile/x86_64/stone.index,priority=100

      --config-dir <CONFIG_DIR>

      --data-dir <DATA_DIR>

      --moss-root <MOSS_ROOT>

  -h, --help
          Print help (see a summary with '-h')

Can see that --help provides an example for options but -h does not, is this expected behaviour?

livingsilver94 commented 3 months ago

I agree with you that -h and --help should just be the short and the long forms of the same flag, but it looks like it's wanted: https://github.com/serpent-os/moss/blob/main/boulder/src/cli/profile.rs#L36

joebonrichie commented 3 months ago

Alright i'll close for now then.

tarkah commented 3 months ago

I agree with you that -h and --help should just be the short and the long forms of the same flag, but it looks like it's wanted: https://github.com/serpent-os/moss/blob/main/boulder/src/cli/profile.rs#L36

I don't think there's been a discussion yet around this, so it's a very valid point! This is the behavior provided by clap that I opted into, but we can definitely omit long_help and just use help if we want the same messages everywhere.

I agree it's a little confusing since users won't know they're getting a condensed vs full help. I think we just show them the whole thing, that's more sane I think.

@joebonrichie feel free to reopen so we can track. Would be good to get the opinion of our resident UX expert @ermo

ermo commented 2 months ago

Show the whole thing on -h/--help IMO.

If <tool> is invoked with no options, show the short help output.