docs/primer/components/README.md
Components are consistent, reusable patterns that we use throughout the command line tool.
We show meaning or objects through syntax such as angled brackets, square brackets, curly brackets, parenthesis, and color.
Display branch names in brackets and/or cyan
Display labels in parenthesis and/or gray
Display repository names in bold where appropriate
Use consistent syntax in help pages to explain command usage.
Use plain text for parts of the command that cannot be changed
gh help
The argument help is required in this command.
Use angled brackets to represent a value the user must replace. No other expressions can be contained within the angled brackets.
gh pr view <issue-number>
Replace "issue-number" with an issue number.
Place optional arguments in square brackets. Mutually exclusive arguments can be included inside square brackets if they are separated with vertical bars.
gh pr checkout [--web]
The argument --web is optional.
gh pr view [<number> | <url>]
The "number" and "url" arguments are optional.
Place required mutually exclusive arguments inside braces, separate arguments with vertical bars.
gh pr {view | create}
Ellipsis represent arguments that can appear multiple times
gh pr close <pr-number>...
For multi-word variables use dash-case (all lower case with words separated by dashes)
gh pr checkout <issue-number>
Optional argument with placeholder:
<command> <subcommand> [<arg>]
Required argument with mutually exclusive options:
<command> <subcommand> {<path> | <string> | literal}
Optional argument with mutually exclusive options:
<command> <subcommand> [<path> | <string>]
Generally speaking, prompts are the CLI’s version of forms.
Use for yes/no questions, usually a confirmation. The default (what will happen if you enter nothing and hit enter) is in caps.
Use to enter short strings of text. Enter will accept the auto fill if available
Use to enter large bodies of text. E key will open the user’s preferred editor, and Enter will skip.
Use to select one option
Use to select multiple options
The CLI reflects how GitHub.com displays state through color and iconography.
For processes that might take a while, include a progress indicator with context on what’s happening.
When viewing output that could be unclear, headers can quickly set context for what the user is seeing and where they are.
The header of the gh pr create command reassures the user that they're creating the correct pull request.
The header of the gh pr list command sets context for what list the user is seeing.
Lists use tables to show information.
Single item views show more detail than list views. The body of the item is rendered indented. The item’s URL is shown at the bottom.
Make sure to include empty messages in command outputs when appropriate.
The empty state of gh pr status
The empty state of gh issue list
Help commands can exist at any level:
gh)gh [command])gh [command] [subcommand])Each can be accessed using the --help flag, or using gh help [command].
Each help page includes a combination of different sections.