Documenting command-line syntax

Placeholder variables

To indicate a placeholder variable, use the <var> element. (To execute the command, the reader replaces the placeholder with an actual value.)

Example

Recommended: gcloud source repos clone default local-directory-name

Command-line syntax

Here's how to document command-line commands and their arguments.

Command prompt

If your command-line instructions show multiple lines of input, then start each line of input with the $ prompt symbol.

Don't show the current directory path before the prompt, even if part of the instruction includes changing directories. However, if the overall context of the command interface changes—such as from the local machine to a remote machine—then add an additional prompt indicator, as appropriate, for the new context.

Examples

Recommended:

Enter the following code into the terminal:

$ adb devices

The following output appears:

List of devices attached
emulator-5554  device
emulator-5556  device

Recommended:

$ adb shell
shell@ $ screencap /sdcard/screen.png
shell@ $ exit
$ adb pull /sdcard/screen.png

When you're showing a one-line command, the command prompt (the $ symbol) is optional. However, if your page includes both multi-line and one-line commands, then we recommend using the command prompt for all of the commands on the page, for consistency.

If your command-line instructions include a combination of input and output lines, we recommend using separate code blocks for input and output.

Example

Recommended:

$ cat ~/.ssh/my-ssh-key.pub

The terminal shows your public key in the following form:

ssh-rsa [KEY-VALUE] [USERNAME]

Required items (commands, arguments, etc.)

Use text without brackets or braces. Depending on the circumstances, this is likely to be in code font.

Examples

Recommended: gcloud compute project-info describe

Recommended: gcloud alpha functions get-logs function-name

In these examples, all words and arguments are required.

Optional arguments

Use square brackets around an optional argument.

If there's more than one optional argument, enclose each item in its own set of square brackets.

Example

Recommended: gcloud dns group [global-flag] [filename]

In this example, group is required but global-flag and filename are optional.

Mutually exclusive arguments

Use braces (also known as curly braces) to indicate that the user must choose one—and only one—of the items inside the braces. Use vertical bars (also known as pipes) to separate the items. There can be more than two mutually exclusive choices, separated from each other by pipes.

Examples

  • Recommended: {file1|file2}

    In this example, choose either file1 or file2.

  • Recommended: {--source cloud-source --source-url source-url | --bucket bucket [--source local-source]}

    In this example, there are also two options:

    • Left side of pipe: If the source code is deployed from a cloud repository, --source cloud-source --source-url source-url is required.
    • Right side of pipe: If the source code is in a local directory:
      • --bucket bucket is required.
      • --source local-source is optional, as specified by the square brackets.

Arguments that can repeat

Use an ellipsis (...) to indicate that the user can specify multiple values for the argument.

Example

Recommended: gcloud dns group [global-flag ...]

In this example, the user can specify multiple instances of the optional parameter global-flag.

发送以下问题的反馈:

此网页
Google Developer Documentation Style Guide
Google Developer Documentation Style Guide