Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2025-03-04 15:27:16 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/examples/pacman.md
Ed Page 83d6add9aa fix(help): Shift focus to subcommands, when present 
In surveying various tools and CLI parsers, I noticed they list the
subcommands first.  This puts an emphasis on them which makes sense
because that is most likely what an end user is supposed to pass in
next.

Listing them last aligns with the usage order but it probably doesn't
outweigh the value of getting a user moving forward.
2022-08-26 10:59:40 -05:00

1.9 KiB
Raw Blame History

pacman defines subcommands via flags.

Here, -S is a short flag subcommand:

$ pacman -S package
Installing package...

Here --sync is a long flag subcommand:

$ pacman --sync package
Installing package...

Now the short flag subcommand (-S) with a long flag:

$ pacman -S --search name
Searching for name...

And the various forms of short flags that work:

$ pacman -S -s name
Searching for name...

$ pacman -Ss name
Searching for name...

(users can "stack" short subcommands with short flags or with other short flag subcommands)

In the help, this looks like:

$ pacman -h
pacman 5.2.1
Pacman Development Team
package manager utility

Usage:
    pacman[EXE] <SUBCOMMAND>

Subcommands:
    query -Q --query    Query the package database.
    sync -S --sync      Synchronize packages.
    help                Print this message or the help of the given subcommand(s)

Options:
    -h, --help       Print help information
    -V, --version    Print version information

$ pacman -S -h
pacman-sync 
Synchronize packages.

Usage:
    pacman[EXE] {sync|--sync|-S} [OPTIONS] [--] [package]...

Arguments:
    <package>...    packages

Options:
    -s, --search <search>...    search remote repositories for matching strings
    -i, --info                  view package information
    -h, --help                  Print help information

And errors:

$ pacman -S -s foo -i bar
? failed
error: The argument '--search <search>...' cannot be used with '--info'

Usage:
    pacman[EXE] {sync|--sync|-S} --search <search>... <package>...

For more information try --help

NOTE: Keep in mind that subcommands, flags, and long flags are case sensitive: -Q and -q are different flags/subcommands. For example, you can have both -Q subcommand and -q flag, and they will be properly disambiguated. Let's make a quick program to illustrate.