Coding Standard for Bash Scripts

The Header section contains the shebang line, directives, license info, and indication of how to get documentation for the script.

This section declares global variables. Creating the shell environment for the script also starts in this section.

Each script should define a subset of these standard local functions:

Most scripts will use SDP libraries. Each library is sourced using the $SDPCommonLib variable.

See the script template for an example of the Command Line Processing block.

See the script template for an example of the Command Line Verification block.

See the script template for an example of the Main Program block. Among other things, this section is responsible for starting any log file processing that is to be done.

Sourced .lib files must NOT use the regular, executable form of the block above. A library file is sourced into its caller’s own shell process, so a declare VersionID=/declare Version= (etc.) in the library would silently overwrite the *calling script’s own same-named variables — confirmed behavior, since sourced code shares the caller’s variable scope. A script that reads $Version after sourcing a library that also declared $Version would silently display the library’s version instead of its own.

Instead, library files use a comment-only marker — never a declare, so nothing is ever actually assigned:

This is sufficient because nothing needs to evaluate a library’s own $Version at runtime — show_versions() (see below) reads the VersionID= text directly out of the file with grep, whether it’s inside a # comment or a real declare statement, and derives the same Version string via the same text processing the executable form’s own derivation lines perform. The derivation lines themselves (VersionStream=, VersionCL=, Version=) are omitted from the library form since they’d never be evaluated anyway.

utils.lib provides a show_versions() function; any script that supports -V/--version and sources one or more .lib files should also source utils.lib in the same block (even if it doesn’t otherwise need utils.lib), and wire its -V/--version option to call show_versions(). It prints the calling script’s own version, plus the version of every .lib file the script actually sources — auto-detected by grepping the running script’s own source/. lines, not by a manually-maintained list, so it can’t drift out of sync as a script’s sourcing changes.

Some scripts are exempt from requiring a Version ID Block:

Supported SDP scripts provided by Perforce appear in /p4/common/bin.

Custom scripts (inherently unsupported) are expected to appear somewhere under the /p4/common/site directory, such as /p4/common/site/bin or /p4/common/site/hms.

Log files are written to the $LOGS directory, which is set by p4_vars to /p4/<instance>/logs. Each script run produces a time-stamped log file:

For example:

If two invocations start within the same second (e.g., a cron job and a manual run), an incrementing integer suffix is appended to guarantee uniqueness:

Log files are created atomically using the bash noclobber option (set -C), ensuring that concurrent invocations never claim the same filename.

In addition to the time-stamped log file, each script maintains a stable symlink in the same directory:

This LogLink symlink always points to the most recently started log, providing a predictable name for operators running tail -f, monitoring tools, and any integrations that need to locate the latest log without knowing the exact timestamp.

If a regular file already exists at the LogLink path (e.g., from an older SDP version that did not use symlinks), it is automatically renamed to a time-stamped filename before the symlink is created.

After the log file and symlink are established, both stdout and stderr are redirected to the log via exec.

When running interactively (terminal attached, color mode active), a tee process substitution is used so that output appears on both the terminal and in the log simultaneously. ANSI color codes are stripped from the log copy so that log files remain clean when viewed with standard text tools.

In silent mode (-si), all output goes to the log only — nothing appears on the terminal. This is the intended mode for crontab invocations, where any terminal output would trigger an email from the cron daemon.

Two command-line options govern logging behavior:

Every script and library file must pass bash -n <file> with no errors before being considered complete. This is a fast, mechanical syntax check, independent of and complementary to ShellCheck’s more thorough static analysis below — run it first.

The ShellCheck utility is a static code analysis tool for bash shell scripts. See: https://www.shellcheck.net

All SDP scripts and library files must pass a ShellCheck scan with ShellCheck version 0.10.0 or later.

Where appropriate, #shellcheck disable=SC<NNNN> directives may be used, as may .shellcheckrc files, to suppress warnings deemed not of concern. See Appendix A, ShellCheck Notes for cases where ShellCheck guidance conflicts with SDP style.

SDP scripts sometimes need to compare two version-like strings lexicographically (e.g. comparing P4D version strings such as 2025.1 against 2026.1) rather than numerically, since these values aren’t valid integers to bash. The idiom used is:

ShellCheck’s SC2072 warns that </> inside [[ ]] might be a mistake for the numeric comparison operators -lt/-gt, since that confusion is a common error. Here the string comparison is intentional, so the warning is suppressed with an explicit # shellcheck disable=SC2072 comment immediately above the line — both to silence the warning and to signal to a future reader that the string comparison is deliberate, not a mistake.