-
Notifications
You must be signed in to change notification settings - Fork 614
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Display short help menu when --help
is used
#4772
Conversation
ab911ba
to
c1b0b82
Compare
0022fc8
to
bdfa318
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM.
One other idea for "short" help information is to put the flag name and the help description on the same line, and then align the columns. For example, a selection from rg -h
output:
-i, --ignore-case Case insensitive search.
-v, --invert-match Invert matching.
-x, --line-regexp Show matches surrounded by line boundaries.
-m, --max-count=NUM Limit the number of matching lines.
--mmap Search with memory maps when possible.
-U, --multiline Enable searching across multiple lines.
--multiline-dotall Make '.' match line terminators.
--no-unicode Disable Unicode mode.
--null-data Use NUL as a line terminator.
-P, --pcre2 Enable PCRE2 matching.
--regex-size-limit=NUM The size limit of the compiled regex.
-S, --smart-case Smart case search.
--stop-on-nonmatch Stop searching after a non-match.
This makes for very dense information display that is easy to read IMO.
The main drawback, I think, is that your descriptions have to be very short. But constraint inspires creativity. :-) And if there's a very long flag name, it can make the column alignment non-ideal. But if we can pull it off, I really like it personally.
(I am also a fan of the -h
/--help
distinction, but I in a sub-command architecture like we have with uv
, I think command help ...
is a very strong convention I've seen in many other places. So I think that's a great idea.)
That'd be a nice format to explore — it'd require moving even further away from the clap defaults but I agree it'd be ideal for the short help display. |
I feel like I'm always drowning in the help output from
uv
because we have so many options.I basically agree with the commentary in clap-rs/clap#4687 that having different behaviors for
-h
and--help
is surprising. I think--help
is more obvious for users and I want to optimize for that experience.This roughly matches the help menus in Cargo and pip.
The
uv help
command can be used for long help. In #4906 and #4909 we improve that command.Extends #4904 which adds test cases for the existing behavior.