Syntax
We show meaning or objects through syntax such as angled brackets, square brackets, curly brackets, parenthesis, and color.
Branches
Display branch names in brackets and/or cyan
Labels
Display labels in parenthesis and/or gray
Repository
Display repository names in bold where appropriate
Help
Use consistent syntax in help pages to explain command usage.
Literal text
Use plain text for parts of the command that cannot be changed
gh help
The argument help is required in this command
Placeholder values
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
Optional arguments
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.
Required mutually exclusive arguments
Place required mutually exclusive arguments inside braces, separate arguments with vertical bars.
gh pr {view | create}
Repeatable arguments
Ellipsis represent arguments that can appear multiple times
gh pr close <pr-number>...
Variable naming
For multi-word variables use dash-case (all lower case with words separated by dashes)
gh pr checkout <issue-number>
Additional examples
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>]
