shellcheck
Static analyzer for shell scripts — finds mistakes with quoting, conditions and portability
shellcheck reads a script without running it and points out typical mistakes: unquoted variables, cd without a check, looping over ls output, bash constructs in #!/bin/sh. Every warning has an SCxxxx code — shellcheck.net/wiki has a detailed explanation for it with an example fix.
Syntax
shellcheck [options] script…
The dialect is taken from the shebang (#!/bin/bash, #!/bin/sh) or from the -s option. Exit code: 0 — no findings, 1 — there are findings, 2 — a file couldn't be read, 3 and 4 — an error in the options.
Options
| Option | What it does |
|---|---|
-s bash / -s sh / -s dash / -s ksh | dialect, if the file has no shebang |
-S error / warning / info / style | show only findings of this severity and above |
-e SC2086,SC2034 | exclude the given codes |
-i SC2086 | show only the given codes |
-o all / -o name | enable optional checks (off by default) |
--list-optional | list optional checks with examples |
-x | follow files included via source / . |
-P path | where to look for included files (SCRIPTDIR — the script's directory) |
-a | also show findings for included files |
-f tty | the default format: code line, arrow, explanation, "Did you mean" |
-f gcc | one line per finding: file:line:column: severity: text [SCxxxx] |
-f diff | fixes as a patch (shellcheck -f diff s.sh | patch -p1) |
-f json1 / -f checkstyle | machine-readable output for CI |
-f quiet | print nothing, only the exit code |
--color=never | no colors (with -C the value is attached: -Cnever) |
-W 0 | don't print wiki links at the end |
--norc | don't read .shellcheckrc |
- instead of a file | read the script from stdin |
Severities
| Severity | What it usually means |
|---|---|
error | almost certainly a mistake: syntax, a loop over $(ls), [[ in sh |
warning | a likely bug: cd without a check, a variable unset or unused |
info | worth fixing: quoting, read without -r |
style | style: $(…) instead of backticks, [[ ]] instead of [ ] |
Directives in a script
| Comment | What it does |
|---|---|
# shellcheck disable=SC2086 | disable a code for the next command (or a { … } block, function, loop) |
| the same right after the shebang, before the first command | disable for the whole file |
# shellcheck disable=SC2086,SC2154 | several codes, comma-separated |
# shellcheck source=lib.sh | which file source "$dir/lib.sh" actually includes |
# shellcheck source=/dev/null | don't try to read the included file |
# shellcheck shell=bash | set the dialect inside a file without a shebang |
A .shellcheckrc file in the project directory or in your home directory sets the same directives for all scripts: disable=SC2086, enable=all, shell=bash.
Common codes
| Code | Gist |
|---|---|
SC2086 | an unquoted variable will be split into words and expanded as a glob |
SC2164 | cd without || exit: if the directory doesn't exist, the commands run in the wrong place |
SC2045 | for f in $(ls …) breaks on spaces — use a glob |
SC2154 | a variable is used but never assigned |
SC2034 | a variable is assigned but never used |
SC2162 | read without -r mangles backslashes |
SC2155 | local x=$(cmd) hides cmd's exit code |
SC2148 | no shebang — the dialect is unknown |
SC1091 | an included file wasn't read (needs -x) |
SC3010 and other SC3xxx | a bash construct in POSIX sh |
Examples
# check a script
shellcheck deploy.sh
# compact output — handy for grep and editors
shellcheck -f gcc deploy.sh
# only errors and warnings, no info and style
shellcheck -S warning deploy.sh
# a script without a shebang
shellcheck -s bash script
# check all .sh files in a project
find . -name '*.sh' -exec shellcheck {} +
# view the suggested fixes as a patch
shellcheck -f diff deploy.sh
# in CI: fail if there is at least one finding
shellcheck -f quiet *.sh || exit 1
# check a snippet from stdin
echo 'echo $1' | shellcheck -s bash -
Pitfalls
shellcheckdoesn't run the script. It doesn't know whether files and commands exist and won't find logic errors. Clean output doesn't mean "the script works".- Without a shebang almost all dialect checks are off, and the first finding will be
SC2148. Add#!/bin/bashor pass-s. #!/bin/shis not bash.[[ ]], arrays,&>giveSC3xxx. That's correct: on Ubuntushisdash, and such a script will break.- A directive applies to the next command, not to the line. A comment at the end of a line (
echo $x # shellcheck disable=…) is a parse errorSC1126. And a directive right after the shebang, before the first command, disables the check for the whole file. disablesilences the symptom. Before disablingSC2086, make sure word splitting is really what you want.- Included files aren't read by default: variables from them look unassigned (
SC2154). Add-x.