When, on program foo, a command bar usage includes both a flag (e.g. qux string) and a list of non-flag arguments, (e.g. foo <pid>), run foo help bar
What will happen
The command will display:
foo <pid> -qux string
But running the command that way, e.g. foo 42 -qux meaning will actually pass -qux and meaning as args in addition to 42, instead of interpreting them as flags, so the help is wrong.
Users actually need to run foo -qux meaning 42 instead.
What should have happened
The help should look like:
food -qux string <pid>
Problem cause
Due to the way explain is currently implemented, the only way to have flags be shown correctly in usage is to avoid including the command arguments, which is still wrong.
Suggested solutions
at the application level, programs can work around the issue by overriding their commander (resp. subcommands.DefaultCommander) with a custom ExplainCommand function implementing either of the steps proposed below for the subcommands package itself.
at the subcommands level, three main solutions exist
do not include the flags in explain, leaving it to the user to add them in the cmd.Usage() method
insert the flags after the first word in the usage string
parse the usage string and only do the insert if the flags are not already present in the usage string.
The first solution is more consistent with the existing package documentation, which explains that "Usage returns a long string explaining the command and giving usage information."
The second form requires less changes from existing users, for whom existing code will suddenly display the correct flags usage string.
The third solution would affect existing code the least but is a bit more complex and may lead to false positives when usage includes other references to the flags in the "long string" it returns, so may cause more errors in the end.
How to reproduce
When, on program
foo, a commandbarusage includes both a flag (e.g.qux string) and a list of non-flag arguments, (e.g.foo <pid>), runfoo help barWhat will happen
The command will display:
foo <pid> -qux stringBut running the command that way, e.g.
foo 42 -qux meaningwill actually pass-quxandmeaningas args in addition to42, instead of interpreting them as flags, so the help is wrong.Users actually need to run
foo -qux meaning 42instead.What should have happened
The help should look like:
food -qux string <pid>Problem cause
Due to the way
explainis currently implemented, the only way to have flags be shown correctly in usage is to avoid including the command arguments, which is still wrong.Suggested solutions
subcommands.DefaultCommander) with a customExplainCommandfunction implementing either of the steps proposed below for the subcommands package itself.explain, leaving it to the user to add them in thecmd.Usage()methodThe first solution is more consistent with the existing package documentation, which explains that "Usage returns a long string explaining the command and giving usage information."
The second form requires less changes from existing users, for whom existing code will suddenly display the correct flags usage string.
The third solution would affect existing code the least but is a bit more complex and may lead to false positives when usage includes other references to the flags in the "long string" it returns, so may cause more errors in the end.