apple / apple/swift-argument-parser

Problems with auto-created `--help` flag, `-h` flag, & `help` subcommand in generated completion scripts & help output

Open
#671 0 comments 1 reaction 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.