Command-line terminology: gcloud command-line tool and Linux

This topic discusses what to call the command-line elements that are used in the gcloud command-line tool and in Linux commands.

General guidance

When discussing commands and their constituent parts, follow this guidance:

  • Avoid mapping nomenclature of the gcloud tool's commands to Linux commands.
  • Linux commands can be complicated. It's wise to describe what the entire command does rather than what its individual elements are called.
  • For Linux commands or commands in the gcloud tool, ask yourself if the reader must know the name of the command-line element or if explaining the command is sufficient.

gcloud commands

gcloud GROUP | COMMAND [--account=ACCOUNT] [--configuration=CONFIGURATION] \
    [--flatten=[KEY,...]][--format=FORMAT] [--help] [--project=PROJECT_ID] \
    [--quiet, -q][--verbosity=VERBOSITY; default="warning"] [--version, -v] \
    [-h] [--log-http][--trace-token=TRACE_TOKEN] [--no-user-output-enabled]

For the sake of accurate classification, the gcloud tool's syntax distinguishes between a command and a command group. In docs, however, command-line contents are generally referred to as commands.

You can use commands (and groups) alone or with one or more flags. A flag is a Google Cloud Platform–specific term for any element other than the command or group name itself. A command or flag might also take an argument, for example, a region value.

Example command:

gcloud init

Example command with a flag:

gcloud init --skip-diagnostics

Example command with multiple elements:

gcloud ml-engine jobs submit training ${JOB_NAME} \
    --package-path trainer \
    --module-name trainer.task \
    --staging-bucket gs://${BUCKET} \
    --job-dir gs://${BUCKET}/${JOB_NAME} \
    --runtime-version 1.2 \
    --region us-central1 \
    --config config/config.yaml \
    -- \
    --data_dir gs://${BUCKET}/data \
    --output_dir gs://${BUCKET}/${JOB_NAME} \
    --train_steps 10000

Where:

  • ml-engine is a gcloud command group.
  • jobs is an ml-engine command group.
  • submit is a jobs command group.
  • training is a submit command.
  • ${JOB_NAME} is an argument that refers to a variable called JOB_NAME that was set earlier.
  • --package-path is a flag.

In addition to the term flag, option is often used as a catchall term when you don't want to mire the reader in specialized nomenclature.

For more details, see the Cloud SDK: gcloud topic.

Linux commands

Where the gcloud command-line tool uses the catchall terms flag and option, Linux commands use options, parameters, arguments, and a host of specialized syntax elements. Here's an example:

find /usr/src/linux -follow -type f -name '*.[ch]' | xargs grep -iHn pcnet

Where:

  • find is the command name.
  • /usr/src/linux is an argument that specifies the path to look in. Easier to refer to as just a path.
  • -follow is an option. The - (dash) is part of the option.
  • -type is an option with a value of f.
  • -name is an option with a value of '*.[ch]', where the asterisk (*) is a metacharacter signifying a wildcard. Metacharacters are used in Linux shell commands for globbing, or filename expansion. In addition to the asterisk, metacharacters include the question mark (?) and caret (^).

The results of the first command are redirected using a pipe (|) to the xargs grep -iHn pcnet command. Other redirection symbols include >, <, >>, and <<. Redirection means capturing output from a file, command, program, script, or even code block within a script and sending it as input to another file, command, program, or script.

Linux signals

Linux signals, or sigactions, require vocabulary choices that are generally discouraged elsewhere in documentation. We recommend using the terms discussed here only in the context of process control.

Signal Description
SIGKILL Signal sent to kill a specified process, all members of a specified process group, or all processes on the system. SIGKILL cannot be caught, blocked, or ignored. Do not substitute cancel, end, exit, quit, stop, or terminate.
SIGTERM Signal sent as a request to terminate a process. Although similar to SIGKILL, this signal gives the process a chance to clean up any child processes that might be running. Do not substitute cancel, end, exit, quit, or stop.
SIGQUIT Signal sent from a keyboard to quit a process. Some processes can catch, block, or ignore a quit signal. Do not substitute cancel, end, exit, quit, or stop.
SIGINT Signal sent to interrupt a process immediately. The default action of this signal is to terminate a process gracefully. It can be handled, ignored, or caught. It can be sent from a terminal—for example, when a user presses Control+C. Do not substitute suspend, end, exit, pause, or terminate.
SIGPAUSE Signal that tells a process to pause, or sleep, until any signal is delivered that either terminates the process or invokes a signal-catching function. Do not substitute cancel or interrupt.
SIGSUSPEND Signal sent to temporarily suspend execution of a process. Used to prevent delivery of a particular signal during the execution of a critical code section. Do not substitute pause or exit.
SIGSTOP Signal sent to stop execution of a process for later continuation (upon receiving a SIGCONT signal). SIGSTOP cannot be caught, blocked, or ignored. Do not substitute cancel, end, exit, interrupt, quit, or terminate.

Envoyer des commentaires concernant…

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide