Skip to content

Provide long help via rv help, remove per-command help subcommands#717

Open
carl wants to merge 1 commit into
spinel-coop:mainfrom
carl:help-long-and-consistent
Open

Provide long help via rv help, remove per-command help subcommands#717
carl wants to merge 1 commit into
spinel-coop:mainfrom
carl:help-long-and-consistent

Conversation

@carl

@carl carl commented Jun 8, 2026

Copy link
Copy Markdown

Fixes #431.

What this does

Help is now requested in two consistent ways:

  • rv … -h / rv … --help show short help (unchanged)
  • rv help [NAME] shows long help for the targeted command

The per-command rv NAME help forms (e.g. rv ruby help pin) are removed by disabling the auto-generated help subcommand on each command group (ruby, tool, cache, self, shell), so there is a single way to ask for full help. The top-level help subcommand is preserved, so rv help ruby pin still works.

This addresses the two open checkboxes in #431:

  • rv help [NAME] shows long help
  • rv NAME help removed

Before / after

Invocation Before After
rv … -h / --help short short (unchanged)
rv help [NAME] long long (now covered by a regression test)
rv ruby help pin printed help removed → errors
rv ruby -h command list listed help no longer lists help
rv help ruby pin (top level) worked still works

Implementation

Five one-line additions of #[command(disable_help_subcommand = true)] to the command-group arg structs. clap's help subcommand renders long help (write_long_help) while -h/--help are mapped to HelpShort, so the long-vs-short routing already follows from keeping the top-level help subcommand and removing the nested ones.

Tests

crates/rv/tests/integration_tests/main.rs:

  • test_help_subcommand_shows_long_helprv help expands enum descriptions; rv -h does not
  • test_help_subcommand_shows_nested_command_helprv help ruby pin still prints the command's help
  • test_help_subcommand_removed_from_command_groupsrv {ruby,tool,cache,self} helpunrecognized subcommand 'help'
  • test_help_subcommand_removed_from_shellrv shell help fails
  • test_help_not_advertised_as_command_group_subcommandhelp no longer appears in the -h command listing for ruby/tool/cache/self

Each behavior-changing test was confirmed to fail against the pre-change source. Full suite (cargo nextest run -p rv), cargo fmt --all -- --check, and cargo clippy -p rv --all-targets all pass.

Notes for reviewers (out of scope / open question)

  1. Leaf positional swallows help. On commands whose leaf takes a positional, help is consumed as a value rather than rejected: rv ruby pin help pins the version to the literal "help", and rv shell help errors as invalid value 'help' for '[SHELL]' rather than unrecognized subcommand 'help'. These aren't help subcommands, so they're untouched by this change. Happy to address separately if you'd like them to error explicitly.
  2. No long_about prose authored. This PR makes rv help [NAME] route to long help, but long help only differs visibly where an arg carries rich metadata (e.g. --color's enum descriptions). If you want genuinely richer per-command long help, that's a larger, separate effort I left out here. Let me know if it should be part of this issue.

Help is now requested in two consistent ways:

- `rv ... -h` / `rv ... --help` show short help (unchanged)
- `rv help [NAME]` shows long help for the targeted command

The per-command `rv NAME help` forms (e.g. `rv ruby help pin`) are removed
by disabling the auto-generated `help` subcommand on each command group, so
there is a single way to ask for full help. The top-level `help` subcommand
is preserved, so `rv help ruby pin` still works.

Fixes spinel-coop#431
@carl carl marked this pull request as ready for review June 8, 2026 20:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add back long help (in a more consistent way)

1 participant