Skip to content
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

Help text: Display argv[0] for root command by default #641

Draft
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

dcantah
Copy link
Member

@dcantah dcantah commented May 31, 2024

Fixes: #633 #570 #295

This seems like the "correct" default, although I'm sure there's some crazy edge case I'm failing to take into account. If your root command had the same name as the resulting binary you produce, this was never an issue, however if your root command was named anything else, then the current Usage/help text was kind of odd.

If you don't specify an explicit commandName in CommandConfiguration, we would take the root command name and generate a command name for you out of hyphens. So, RootCommand would become root-command and this is what would be displayed in the usage text for /path/to/cool-binary --help, even though intuitively you'd expect to see USAGE: cool-binary.

The current behavior was also strange for binaries that are classically invoked via symlinks as the same thing would happen. In this case imagine the struct name matched the actual binaries name, but because the symlink is what users actually
invoke you could end up seeing an unfamiliar name in help text regardless. Using argv[0] solves most of these problems.

The downside here is a LOT of tests need to change. I went with foregoing the new approach if the user explicitly provides a command name, so most of the existing tests that check for exact string matches of help text either need to replace the
command name with the first argument of the binary that is running the test (xctest, but it doesn't really matter what it is as I've added a helper to plop in the first argument for all of these tests), or they need to define CommandConfiguration(commandName: "name-we-want"). For any tests that implemented ParsableCommand I mostly went with the latter to make as few changes as possible.

Given this seems like mostly a UX change, I hope this seems sane.

Checklist

  • I've added at least one test that validates that my change is working, if appropriate
  • I've followed the code style of the rest of the project
  • I've read the Contribution Guidelines
  • I've updated the documentation if necessary

Fixes: apple#633 apple#570 apple#295

This seems like the "correct" default. If your root command had the same name
as the resulting binary you produce, this was never an issue, however if
your root command was named anything else, then the current Usage/help text was
kind of odd.

If you don't specify an explicit commandName in CommandConfiguration, we would
take the root command name and generate a command name for you out of hyphens.
So, `RootCommand` would become `root-command` and this is what would be displayed
in the usage text for `/path/to/cool-binary --help`, even though intuitively you'd
expect to see `USAGE: cool-binary`.

The current behavior was also strange for binaries that are classically invoked
via symlinks as the same thing would happen. In this case imagine the struct name
matched the actual binaries name, but because the symlink is what users actually
invoke you could end up seeing an unfamiliar name in help text regardless. Using
argv[0] solves most of these problems.

The downside here is a LOT of tests need to change. I went with foregoing the
new approach if the user explicitly provides a command name, so most of the existing
tests that check for exact string matches of help text either need to replace the
command name with the first argument of the binary that is running the test (xctest,
but it doesn't really matter what it is as I've added a helper to plop in the first
argument for all of these tests), or they need to define
CommandConfiguration(commandName: "name-we-want"). For any tests that implemented
ParsableCommand I mostly went with the latter to make as few changes as possible.

Given this seems like mostly a UX change, I hope this seems sane.

Signed-off-by: Danny Canter <danny@dcantah.dev>
The behavior for displaying the root command name in the help text was
recently changed to default to showing argv[0] by default unless you specify
an explicit `commandName`. Add some simple tests to verify this.

Signed-off-by: Danny Canter <danny@dcantah.dev>
Make it clear the behavior of what will be displayed in help text
if commandName is supplied or not.

Signed-off-by: Danny Canter <danny@dcantah.dev>
@dcantah
Copy link
Member Author

dcantah commented May 31, 2024

I missed #501 from @smvz that already exists.. It seems we went in two directions though, his change is opt-in while this is changing the default behavior of the root command. His likely makes more sense from a back compat standpoint (and has the benefit of not needing all the test changes).

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 ability to infer root command name from CLI args
1 participant