Detect if --help was likely intended for binary being run

[pnkfelix]

Describe the problem you are trying to solve

When I invoke cargo run --bin program --help, sometimes I intended for the --help to be passed to the program I am invoking, rather than cargo itself.

Right now, the above invocation spits out the same information that you get when you do cargo run --help.

The information emitted does include the command syntax: cargo run [OPTIONS] [--] [args]...

But it doesn't provide guidance specifically saying that I might have intended to feed in the --help as part of the [args]...

Describe the solution you'd like

In an ideal world, cargo would read my mind and figure out whether the --help is intended for cargo itself, or for the program I'm running, and only pass it to whichever I intended. Of course its not realistic, but it does spell out one ambitious option:

1. cargo run --help could include both the --help for cargo run itself, and also run the binary passing --help to it

The main problem with that option is that running the binary may have side-effects that one would never intend from invoking cargo run --help. For that, I'd suggest running the binary in a sandbox: no file-writes, no network traffic.

---

Still, that approach may be a lot of work for an approach that still might be a minefield.

So here is a more conservative option:

2. cargo run --help could explicitly point out how to adjust the command line to pass --help to the underlying binary.

So, cargo run --help would also include a line suggesting that one might do cargo run -- --help

Likewise, cargo run --bin program --help would include a line suggesting cargo run --bin program -- --help.

[weihanglo]

This is a tricky problem. Not only --help suffers in this situation, other flags in cargo run as well. I may lean towards the second option. The first one is a bit too verbose, since cargo run has already way too many options. cargo test has got the same hint at the bottom, so we may follow that.

However, Cargo never knows if a binary has --help option or not, not to mention --help may trigger side effect as you said. That might be a false positive if we provide that.

Given clap has been improving the built-in help a lot — It moves arguments section to the very front of the help text, I'd suggest adding a help message to args, such as

 Run a binary or example of the local package

 Usage: cargod run [OPTIONS] [args]...

 Arguments:
-  [args]...
+  [args]...  Arguments for the binary to run

 Options:
   ...

Whereas for the old one (1.53.0) ARGS is at the bottom:

Run a binary or example of the local package

USAGE:
    cargo run [OPTIONS] [--] [args]...

OPTIONS:
    -q, --quiet                      No output printed to stdout
        --bin <NAME>...              Name of the bin target to run
        --example <NAME>...          Name of the example target to run
    ...
    ...
    -Z <FLAG>...                     Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
    -h, --help                       Prints help information

ARGS:
    <args>...    

This one line change should be sufficient. Other approach is not ideal and may lead to wrong suggestion/side effect.

[weihanglo]

See #11740 (comment) and #11740 (comment)