apple / apple/swift-argument-parser
Proposal: Surface clearer help documentation around the default subcommand
- Dominant language
- Swift
- Stars
- 3.8k
- Forks
- 411
- Avg merge
- 7d 14h
- Merged PRs (30d)
- 15
Description
Commands with default subcommands do not have discoverable usage information without digging into the subcommand itself. Below, I'll outline the structure of a simple project as well as two proposals for updating the help information for commands that have a default subcommand.
Simply put, a command with a default subcommand likely doesn't have any information it runs itself and, as such, should specify the information that is available by running the default subcommand.
## Structure
For ease of clarity, repeating the structure of my project here:
Command: `zinc`
Subcommands: `lint`, `sync`
Default Subcommand: `sync`
## Proposal 1 - Highlighting the Default Subcommand
### Problem Statement
The output of `zinc --help` is such that the default subcommand is not made clear.
This is what prints:
```
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync Syncs local files with remote files as defined by a Zincfile.
```
### Proposed Solution
I'm proposing we highlight the default subcommand somehow:
```
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync (default) Syncs local files with remote files as defined by a Zincfile.
```
## Proposal 2 - Prefer Default Subcommand Usage
### Problem Statement
If I specify a default subcommand in my project, while I would allow someone to run `zinc sync `, specifying a default subcommand likely implies that I'm happy with `zinc `. As such, I think that the output of ` --help` should be refined.
Right now, here's what prints out when I run `zinc --help`:
```
OVERVIEW: Zinc is a command-line tool for keeping local files in sync with files hosted outside of your folder or
repository.
USAGE: zinc
OPTIONS:
-h, --help Show help information.
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync Syncs local files with remote files as defined by a Zincfile.
```
Here is the output of `zinc sync --help`:
```
OVERVIEW: Syncs local files with remote files as defined by a Zincfile.
USAGE: zinc sync [--file ] [--verbose]
OPTIONS:
-f, --file The Zincfile to parse and use for syncing. (default: Zincfile)
--verbose Logs additional debug messages if enabled.
-h, --help Show help information.
```
### Proposed Solution
I'm not sure what the right answer is here, but I imagine we should see an example of the default command being run, along with additional subcommands still.
I'm not sold on this, but here's an example:
```
OVERVIEW: Zinc is a command-line tool for keeping local files in sync with files hosted outside of your folder or
repository.
USAGE:
zinc --file
zinc
OPTIONS:
-f, --file The Zincfile to parse and use for syncing. (default: Zincfile)
--verbose Logs additional debug messages if enabled.
-h, --help Show help information.
SUBCOMMANDS:
lint Performs basic linting against a Zincfile to identify issues and errors.
sync (default) Syncs local files with remote files as defined by a Zincfile.
```
## Additional Notes
I'd like some additional feedback on the proposed solutions. I'm poking around at a variety of commands that I use day-to-day in my Swift projects as well as some outside of the Swift ecosystem and there's a variety of answers, but almost all at least provide some help documentation for a default subcommand within the help documentation of the command itself if requested.
Contributor guide
Research direction
Start by reviewing the issue's `zinc --help` and `zinc sync --help` examples and the two proposed approaches. Determine which default-subcommand behavior the project wants, then verify that help output exposes the default command's usage and still documents other subcommands.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- cli
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100