help command incorrectly locates flags in its result
- Dominant language
- Go
- Stars
- 795
- Forks
- 51
- PR merge metrics
- No merged PRs in 30d
Description
## How to reproduce
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 `), run `foo help bar`
## What will happen
The command will display:
`foo -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 `
## 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.
Contributor guide
Assessment
This issue has not been assessed yet.