| SHELLCHECK(1) | SHELLCHECK(1) |
shellcheck - Shell script analysis tool
shellcheck [OPTIONS...] FILES...
ShellCheck is a static analysis and linting tool for sh/bash scripts. It's mainly focused on handling typical beginner and intermediate level syntax errors and pitfalls where the shell just gives a cryptic error message or strange behavior, but it also reports on a few more advanced issues where corner cases can cause delayed failures.
ShellCheck gives shell specific advice. Consider this line:
(( area = 3.14*r*r ))
This option may also be enabled using external-sources=true in .shellcheckrc. This flag takes precedence.
For example, in Vim, :set makeprg=shellcheck\ -f\ gcc\ % will allow using :make to check the script, and :cnext to jump to the next error.
<file>:<line>:<column>: <type>: <message>
<?xml version='1.0' encoding='UTF-8'?> <checkstyle version='4.3'>
<file name='file'>
<error
line='line'
column='column'
severity='severity'
message='message'
source='ShellCheck.SC####' />
...
</file>
... </checkstyle>
--- a/test.sh +++ b/test.sh @@ -2,6 +2,6 @@
## Example of a broken script.
for f in $(ls *.m3u)
do - grep -qi hq.*mp3 $f \ + grep -qi hq.*mp3 "$f" \
&& echo -e 'Playlist $f contains a HQ file in mp3 format'
done
{
comments: [
{
"file": "filename",
"line": lineNumber,
"column": columnNumber,
"level": "severitylevel",
"code": errorCode,
"message": "warning message"
},
...
]
}
ShellCheck directives can be specified as comments in the shell script. If they appear before the first command, they are considered file-wide. Otherwise, they apply to the immediately following command or block:
# shellcheck key=value key=value
command-or-structure
For example, to suppress SC2035 about using ./*.jpg:
# shellcheck disable=SC2035
echo "Files: " *.jpg
To tell ShellCheck where to look for an otherwise dynamically determined file:
# shellcheck source=./lib.sh
source "$(find_install_dir)/lib.sh"
Here a shell brace group is used to suppress a warning on multiple lines:
# shellcheck disable=SC2016
{
echo 'Modifying $PATH'
echo 'PATH=foo:$PATH' >> ~/.bashrc
}
Valid keys are:
This option defaults to false only due to ShellCheck's origin as a remote service for checking untrusted scripts. It can safely be enabled for normal development.
Unless --norc is used, ShellCheck will look for a file .shellcheckrc or shellcheckrc in the script's directory and each parent directory. If found, it will read key=value pairs from it and treat them as file-wide directives.
Here is an example .shellcheckrc:
# Look for 'source'd files relative to the checked script,
# and also look for absolute paths in /mnt/chroot
source-path=SCRIPTDIR
source-path=/mnt/chroot
# Since 0.9.0, values can be quoted with '' or "" to allow spaces
source-path="My Documents/scripts"
# Allow opening any 'source'd file, even if not specified as input
external-sources=true
# Turn on warnings for unquoted variables with safe values
enable=quote-safe-variables
# Turn on warnings for unassigned uppercase variables
enable=check-unassigned-uppercase
# Allow [ ! -z foo ] instead of suggesting -n
disable=SC2236
If no .shellcheckrc is found in any of the parent directories, ShellCheck will look in ~/.shellcheckrc followed by the XDG config directory (usually ~/.config/shellcheckrc) on Unix, or %APPDATA%/shellcheckrc on Windows. Only the first file found will be used.
Note for Snap users: the Snap sandbox disallows access to hidden files. Use shellcheckrc without the dot instead.
Note for Docker users: ShellCheck will only be able to look for files that are mounted in the container, so ~/.shellcheckrc will not be read.
The environment variable SHELLCHECK_OPTS can be set with default flags:
export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'
Its value will be split on spaces and prepended to the command line on each invocation.
ShellCheck uses the following exit codes:
This version of ShellCheck is only available in English. All files are leniently decoded as UTF-8, with a fallback of ISO-8859-1 for invalid sequences. LC_CTYPE is respected for output, and defaults to UTF-8 for locales where encoding is unspecified (such as the C locale).
Windows users seeing commitBuffer: invalid argument (invalid character) should set their terminal to use UTF-8 with chcp 65001.
(If nothing in this section makes sense, you are unlikely to be affected by it)
To avoid confusing and misguided suggestions, ShellCheck requires function bodies to be either { brace groups; } or ( subshells ), and function names containing []*=! are only recognized after a function keyword.
The following unconventional function definitions are identical in Bash, but ShellCheck only recognizes the latter.
[x!=y] () [[ $1 ]]
function [x!=y] () { [[ $1 ]]; }
Shells without the function keyword do not allow these characters in function names to begin with. Function names containing {} are not supported at all.
Further, if ShellCheck sees [x!=y] it will assume this is an invalid comparison. To invoke the above function, quote the command as in '[x!=y]', or to retain the same globbing behavior, use command [x!=y].
ShellCheck imposes additional restrictions on the [ command to help diagnose common invalid uses. While [ $x= 1 ] is defined in POSIX, ShellCheck will assume it was intended as the much more likely comparison [ "$x" = 1 ] and fail accordingly. For unconventional or dynamic uses of the [ command, use test or \[ instead.
Bugs and issues can be reported on GitHub:
https://github.com/koalaman/shellcheck/issues
ShellCheck is developed and maintained by Vidar Holen, with assistance from a long list of wonderful contributors.
Copyright 2012-2022, Vidar Holen and contributors. Licensed under the GNU General Public License version 3 or later, see https://gnu.org/licenses/gpl.html
| Shell script analysis tool |