Shellcheck Disable Builder

ShellCheck and the disable directive

ShellCheck is the de-facto static analyser for shell scripts, written in Haskell by Vidar Holen and released in 2012 under GPL. It parses sh, bash, dash and ksh source code and flags hundreds of pitfalls — from word-splitting bugs to subtle quoting traps that crash scripts only in edge cases. Each finding has a stable code in the SC1000-SC2999 range with a dedicated wiki page explaining the why and how to fix it.

The most common findings include SC2086 (quote variables to prevent globbing/word-splitting — $var instead of "$var"), SC2034 (assigned variable never used), SC2155 (declare and assign separately to surface the exit status), SC2046 (quote command substitutions), SC2068 (use "$@" not $@), SC2002 (useless cat), SC2129 (group multiple redirects with { } > file) and SC2154 (variable referenced but not assigned).

Disable syntax

When a finding is intentional, silence it with a directive on the line immediately above the offending statement:

# shellcheck disable=SC2086
rm $files   # purposeful word-splitting here

# shellcheck disable=SC2086,SC2154
echo $maybe_unset

# shellcheck disable=all
# (file-wide: place at the very top, before any code)

Scope follows position: a directive at the top of the file applies to the whole file; on the line above a statement, only to that statement; inside a function, scoped to the function. Always pair the code with a short justification comment — future maintainers (and you in six months) will thank you.

Integrations and CI

ShellCheck plugs into virtually every editor: VS Code via timonwong.shellcheck, Vim via ALE, Emacs via Flymake, Sublime via SublimeLinter. In CI, run it on every *.sh / *.bash file inside a PR and fail the build on warnings: GitHub Actions has ludeeus/action-shellcheck, GitLab CI uses the upstream Docker image. The pre-commit framework offers a hook that runs locally before each commit. Alternatives in adjacent niches: bashate (OpenStack-flavoured style), shfmt (formatter, not a linter) and shellharden (auto-fixes quoting issues).

Severities and shell dialects

Findings come in four severities: error, warning, info and style. By default ShellCheck assumes bash; for strict POSIX scripts add # shellcheck shell=sh at the top so it flags bashisms. To handle an undefined variable explicitly, prefer ${var:-default} over silencing SC2154.

FAQ

Does ShellCheck work on zsh? Only partially. It recognises common syntax but does not understand zsh-specific extensions (associative arrays with typeset -A, glob qualifiers, parameter expansion flags). For pure zsh, rely on zsh -n syntax checks and zshlint instead.

Can I run it on Fish scripts? No — fish is a distinct shell with a non-POSIX grammar. Use fish --no-execute for syntax validation.

Can I add custom rules? No. ShellCheck is deliberately prescriptive — the rule set is fixed by the maintainers. If a rule does not fit your project, disable it per-file or per-line; do not fork the tool.

Where do I find the explanation for an SC code? Every code has a wiki page at github.com/koalaman/shellcheck/wiki/SC<code> with a problematic snippet, a corrected snippet and exceptions worth knowing.