apple / apple/swift-argument-parser
Improve help text output by the default help subcommand
- Dominant language
- Swift
- Stars
- 3.8k
- Forks
- 411
- Avg merge
- 7d 14h
- Merged PRs (30d)
- 15
Description
The help text output by the default help subcommand doesn't seem proper to me:
1. The `USAGE` section doesn't show `-h`, `--help`, or `--version` if they are autogenerated
2. The `USAGE` section doesn't indicate that `` is optional, or that it can be followed by additional arguments
3. The `OPTIONS` section lists `--version` before `-h, --help`, but I think they should be sorted alphabetically
4. The `SUBCOMMANDS` section doesn't show `help … Show help information.`, which I think should be inserted alphabetically in the subcommand list
**ArgumentParser version:**
main
**Swift version:** Paste the output of `swift --version` here.
swift-driver version: 1.127.14.1 Apple Swift version 6.2.1 (swiftlang-6.2.1.4.8 clang-1700.4.4.1)
Target: arm64-apple-macosx26.0
### Checklist
- [x] If possible, I've reproduced the issue using the `main` branch of this package
- [x] I've searched for [existing GitHub issues](https://github.com/apple/swift-argument-parser/issues)
### Steps to Reproduce
Run the `help` subcommand of a command that has both a default `help` subcommand and that has `CommandConfiguration.version` set. They needn't exist together, but doing this shows both problems at once.
### Expected behavior
Top-level help output:
```text
OVERVIEW: Command
USAGE: cmd [(-h | --help) [] | --version | *…]
OPTIONS:
-h, --help Show help information.
--version Show the version.
SUBCOMMANDS:
a A
b B
c C
help Show help information.
```
### Actual behavior
Top-level help output:
```text
OVERVIEW: Command
USAGE: cmd
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
a A
b B
c C
```
Contributor guide
Research direction
Start by reproducing the default help subcommand with a command that has autogenerated help, a version, and subcommands a, b, and c. Compare the output with the expected example; done means the USAGE, OPTIONS, and SUBCOMMANDS sections include and order the entries described in the issue.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100