apple / apple/swift-argument-parser
Problems with auto-created `--help` flag, `-h` flag, & `help` subcommand in generated completion scripts & help output
- Dominant language
- Swift
- Stars
- 3.8k
- Forks
- 411
- Avg merge
- 7d 14h
- Merged PRs (30d)
- 15
Description
The following problems from an SAP-1.5.0-generated zsh completion script for the auto-created `--help` flag, the auto-created `-h` flag, & the auto-created `help` subcommand might occur for SAP-generated bash and/or fish scripts, too, but I'll just detail the problems seen in zsh.
I'm writing a command-line app that has subcommands (let's call it `command`).
SAP automatically created a `help` subcommand for `command`.
SAP also automatically created synonymous `--help` & `-h` top-level flags that output the same usage info as the `help` subcommand.
### `command --help|-h|help` output
The auto-created `help` subcommand is not included in the subcommand list output by `command --help`, `command -h`, or `command help`. It should be inserted alphabetically into the list for each of the 3 commands.
### `command help ` completion
When I tab complete after a space after `command help`, the completion list is empty. If I manually type in `command help subcommand`, I get the help for `subcommand`.
The completion list after `command help` should thus include the list of subcommands.
### `command --help|-h ` completion
When I tab complete after a space after `command --help` or `command -h`, the completion list contains all the subcommands (including `help`).
All arguments after `command --help` or `command -h`, however, are ignored by SAP when the command is run; the command just outputs the top-level help, i.e. the list of subcommands along with top-level options.
The completion list after `command --help` or `command -h` should thus be empty.
I'd imagine that other top-level flags / options are ignored even if they're before `--help` or `-h`; if so, then the presence of any other flag / option / whatever should move `--help` & `-h` from any subsequent completion lists for the command / subcommand.
### `command subcommand --help|-h ` completion
SAP also auto-created `--help` & `-h` flags for each of my subcommands. The behavior of the top-level-command `--help` & `-h` flags should be replicated for the same two flags for each subcommand.
Contributor guide
Research direction
Start by reproducing the reported cases in the SAP-generated zsh completion script for a command with subcommands, checking --help, -h, and help output and completion lists. Done means the help subcommand appears alphabetically in all three help outputs, help completion lists subcommands, and --help/-h completion lists are empty at the top level and for subcommands.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift, zsh
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100