apple / apple/swift-argument-parser

Improve help text output by the default help subcommand

Open
#833 2 comments 0 reactions 0 assignees View on GitHub
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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.