cargo help logout suggests running itself

[SimonSapin]

Problem

The output of cargo help logout ends with “Run cargo help logout for more detailed information.”, but that was already what I was running. Running it again gives the same information again, not more detailed.

Steps

Run cargo +nightly help logout. Output:

Remove an API token from the registry locally

Usage: cargo logout [OPTIONS]

Options:
  -q, --quiet                Do not print cargo log messages
      --registry <REGISTRY>  Registry to use
  -v, --verbose...           Use verbose output (-vv very verbose/build.rs output)
      --color <WHEN>         Coloring: auto, always, never
      --frozen               Require Cargo.lock and cache are up to date
      --locked               Require Cargo.lock is up to date
      --offline              Run without accessing the network
      --config <KEY=VALUE>   Override a configuration value
  -Z <FLAG>                  Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for details
  -h, --help                 Print help

Run `cargo help logout` for more detailed information.

Possible Solution(s)

For logout in particular, make cargo help logout actually print more information. The information I was looking for in particular is: does logout remove $CARGO_HOME/credentials.toml, does it revoke the token server-side, or both?

In general, in case this does or could happen for other (or future new) commands: when no detailed help page is available, having cargo help $COMMAND default to printing the same as cargo $COMMAND --help instead is fine. But in that case neither command should suggest running cargo help $COMMAND for more information that isn’t there.

Notes

No response

Version

cargo 1.70.0-nightly (15d090969 2023-03-21)
release: 1.70.0-nightly
commit-hash: 15d090969743630bff549a1b068bcaa8174e5ee3
commit-date: 2023-03-21
host: aarch64-unknown-linux-gnu
libgit2: 1.5.0 (sys:0.16.0 vendored)
libcurl: 8.0.1-DEV (sys:0.4.61+curl-8.0.1 vendored ssl:OpenSSL/1.1.1q)
os: Ubuntu 22.04 (jammy) [64-bit]

[epage]

#11473 added the --help fallback when there isn't a man page.

The challenge is actually having a way to remove the suggestion since we are spawning a new process with --help. We could add an internal env variable. Just unsure how much it is worth it vs just filling in the holes of man pages.

[jofas]

I'd be happy to write the man page for the cargo logout command.

[ehuss]

The man page was intentionally not added because the command is nightly-only, and there is no mechanism to "hide" it from the website or man installation. I suppose it might be ok to add it if there is some way to not include it in the documentation, but I'm reluctant to add complexity for something that I suspect almost nobody uses. Another option is to comment out the after_help call, but we would somehow need to remember to put it back during stabilization, and I'm concerned that would be something that is forgotten (I suppose we could add that to the tracking issue).

[ehuss]

Since I don't think there are any real blockers, I went ahead and proposed to stabilize the command in #11910. If that passes, we can just add the docs while stabilizing.

[jofas]

@ehuss #11910 has passed the final comment period. Do you want me to write the man page for the logout command? I was also thinking of adding a paragraph or note to the documentation here where cargo logout is shortly described.

[ehuss]

@jofas The stabilization PR is up at #11950, if you would like to review and provide feedback there it would be appreciated.