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:

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

Edit this page on GitHub

2 contributors

Last edited by colebemis on October 5, 2020