Skip to content


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

A branch name in brackets and cyan


Display labels in parenthesis and/or gray

A label name in parenthesis and gray


Display repository names in bold where appropriate

A repository name in bold


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>]
Edit this page on GitHub
1 contributorampinsk
Last edited by ampinsk on August 7, 2020