Displaying command alias in help/usage
roxspring opened this issue · comments
We have two steps that users perform which are conceptually very different, but technically identical. We define each step as a separate command, and so we've implemented these technically identical steps as a single step1 command with a step2 alias. Technically this works well, but it's a little confusing to ask for help for step2 and get shown help apparently for step1.
Given a subcommand with an alias, is it possible to have that alias used in the help/usage?
@Command(name = "sub", aliases = "alias", mixinStandardHelpOptions = true) class Sub {}
@Command(name = "app", subcommands = {Sub.class}) class App {}
StringWriter out = new StringWriter();
CommandLine app = new CommandLine(new App(), new InnerClassFactory(this));
app.setOut(new PrintWriter(out));
ParseResult result = app.parseArgs("alias", "--help");
CommandLine.printHelpIfRequested(result);
final String expected = format("" +
"Usage: app alias [-hV]%n" +
" -h, --help Show this help message and exit.%n" +
" -V, --version Print version information and exit.%n");
assertEquals(expected, out.toString());If it's already possible, I'd love to understand what I'm missing.
If not, and it's welcome, then I'm happy to take recommendations how to implement it and submit a PR!
Hi @roxspring thank you for raising this!
No you haven't overlooked anything, currently the help is the same regardless of which alias was used to invoke it.
Some thoughts:
Without looking at the code (on my phone now, working from memory) one part of the problem is that the parser doesn't keep track of which alias was actually used to trigger the help being displayed.
maincmd help subcmdAlias1
maincmd help subcmdAlias2
maincmd subcmdAlias1 --help
maincmd subcmdAlias2 -h
It may not be easy to build bookkeeping to keep track of this. Such bookkeeping also needs to handle scenarios like nested sub-subcommands and repeatable subcommands.
Secondly, the display part. Currently help is static: it's not designed to change depending on user input (only the error message is, but that isn't part of the usage help message).
There's no parser state available to the logic that constructs the usage help message. I imagine we would have to use a static variable (or something similar) to store the user-specified command name/alias, to make that alias available to the logic that constructs the usage help message. If you can think of a better solution, ideas are welcome!
Finally, the help is designed to be highly customizable. If applications have tests that assert the exact help message, then these tests may break, that's unavoidable.
But other than that, any changes we introduce here should not impact other applications who have customized their help message, those customizations should continue to work as before.
Reading the description for this ticket again it’s clear the alias is for a subcommand. Apologies, I didn’t read carefully.
I edited my previous comment.
It may not be easy to build bookkeeping to keep track of this. Such bookkeeping also needs to handle scenarios like nested sub-subcommands and repeatable subcommands.
Looking at repeatable subcommands gave me the inspiration for #2105 - arguably a bit hacky so feedback welcome!