Skip to content

Language

Language is the most important tool at our disposal for creating a clear, understandable product. Having clear language helps us create memorable commands that are clear in what they will do.

We generally follow this structure:

gh<command><subcommand>[value][flags][value]
ghissueview234--web-
ghprcreate---title“Title”
ghrepoforkcli/cli--clonefalse
ghprstatus---
ghissuelist---stateclosed
ghprreview234--approve-

Command: The object you want to interact with

Subcommand: The action you want to take on that object. Most gh commands contain a command and subcommand. These may take arguments, such as issue/PR numbers, URLs, file names, OWNER/REPO, etc.

Flag: A way to modify the command, also may be called “options”. You can use multiple flags. Flags can take values, but don’t always. Flags always have a long version with two dashes (--state) but often also have a shortcut with one dash and one letter (-s). It’s possible to chain shorthand flags: -sfv is the same as -s -f -v

Values: Are passed to the commands or flags

  • The most common command values are:
    • Issue or PR number
    • The “owner/repo” pair
    • URLs
    • Branch names
    • File names
  • The possible flag values depend on the flag:
    • --state takes {closed | open | merged}
    • --clone is a boolean flag
    • --title takes a string
    • --limit takes an integer

Tip: To get a better sense of what feels right, try writing out the commands in the CLI a few different ways.

Do

Use a flag for modifiers of actions

Don't

Avoid making modifiers their own commands

When designing your command’s language system:

  • Use GitHub language
  • Use unambiguous language that can’t be confused for something else
  • Use shorter phrases if possible and appropriate
Do

Use language that can't be misconstrued

Don't

Avoid language that can be interpreted in multiple ways ("open in browser" or "open a pull request" here)

Do

Use understood shorthands to save characters to type

Don't

Avoid long words in commands if there's a reasonable alternative