NAME

SYNOPSIS

DESCRIPTION

ShellCheck gives shell specific advice. Consider this line:

(( area = 3.14*r*r ))

    

•

For scripts starting with #!/bin/sh (or when using -s sh), ShellCheck will warn that (( .. )) is not POSIX compliant (similar to checkbashisms).

•

For scripts starting with #!/bin/bash (or using -s bash), ShellCheck will warn that decimals are not supported.

•

For scripts starting with #!/bin/ksh (or using -s ksh), ShellCheck will not warn at all, as ksh supports decimals in arithmetic contexts.

OPTIONS

-a, --check-sourced

Emit warnings in sourced files. Normally, shellcheck will only warn about issues in the specified files. With this option, any issues in sourced files will also be reported.

-C[WHEN], --color[=WHEN]

For TTY output, enable colors always, never or auto. The default is auto. --color without an argument is equivalent to --color=always.

-i CODE1[,CODE2...], --include=CODE1[,CODE2...]

Explicitly include only the specified codes in the report. Subsequent -i options are cumulative, but all the codes can be specified at once, comma-separated as a single argument. Include options override any provided exclude options.

-e CODE1[,CODE2...], --exclude=CODE1[,CODE2...]

Explicitly exclude the specified codes from the report. Subsequent -e options are cumulative, but all the codes can be specified at once, comma-separated as a single argument.

-f FORMAT, --format=FORMAT

Specify the output format of shellcheck, which prints its results in the standard output. Subsequent -f options are ignored, see FORMATS below for more information.

--list-optional

Output a list of known optional checks. These can be enabled with -o flags or enable directives.

--norc

Don't try to look for .shellcheckrc configuration files.

-o NAME1[,NAME2...], --enable=NAME1[,NAME2...]

Enable optional checks. The special name all enables all of them. Subsequent -o options accumulate. This is equivalent to specifying enable directives.

-P SOURCEPATH, --source-path=SOURCEPATH

Specify paths to search for sourced files, separated by : on Unix and ; on Windows. This is equivalent to specifying search-path directives.

-s shell, --shell=shell

Specify Bourne shell dialect. Valid values are sh, bash, dash and ksh. The default is to deduce the shell from the file's shell directive, shebang, or .bash/.bats/.dash/.ksh extension, in that order. sh refers to POSIX sh (not the system's), and will warn of portability issues.

-S SEVERITY, --severity=severity

Specify minimum severity of errors to consider. Valid values in order of severity are error, warning, info and style. The default is style.

-V, --version

Print version information and exit.

-W NUM, --wiki-link-count=NUM

For TTY output, show NUM wiki links to more information about mentioned warnings. Set to 0 to disable them entirely.

-x, --external-sources

Follow source statements even when the file is not specified as input. By default, shellcheck will only follow files specified on the command line (plus /dev/null). This option allows following any file the script may source.

FILES...

One or more script files to check, or "-" for standard input.

FORMATS

tty

Plain text, human readable output. This is the default.

gcc

GCC compatible output. Useful for editors that support compiling and showing syntax errors.

checkstyle

Checkstyle compatible XML output. Supported directly or through plugins by many IDEs and build monitoring systems.

diff

Auto-fixes in unified diff format. Can be piped to git apply or patch -p1 to automatically apply fixes.

json1

Json is a popular serialization format that is more suitable for web applications. ShellCheck's json is compact and contains only the bare minimum. Tabs are counted as 1 character.

json

This is a legacy version of the json1 format. It's a raw array of comments, and all offsets have a tab stop of 8.

quiet

Suppress all normal output. Exit with zero if no issues are found, otherwise exit with one. Stops processing after the first issue.

DIRECTIVES

# 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:

disable

Disables a comma separated list of error codes for the following command. The command can be a simple command like echo foo, or a compound command like a function definition, subshell block or loop. A range can be be specified with a dash, e.g. disable=SC3000-SC4000 to exclude 3xxx. All warnings can be disabled with disable=all.

enable

Enable an optional check by name, as listed with --list-optional. Only file-wide enable directives are considered.

external-sources

Set to true in .shellcheckrc to always allow ShellCheck to open arbitrary files from 'source' statements (the way most tools do).

source

Overrides the filename included by a source/. statement. This can be used to tell shellcheck where to look for a file whose name is determined at runtime, or to skip a source by telling it to use /dev/null.

source-path

Add a directory to the search path for source/. statements (by default, only ShellCheck's working directory is included). Absolute paths will also be rooted in these paths. The special path SCRIPTDIR can be used to specify the currently checked script's directory, as in source-path=SCRIPTDIR or source-path=SCRIPTDIR/../libs. Multiple paths accumulate, and -P takes precedence over them.

shell

Overrides the shell detected from the shebang. This is useful for files meant to be included (and thus lacking a shebang), or possibly as a more targeted alternative to 'disable=SC2039'.

RC FILES

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
# 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.

ENVIRONMENT VARIABLES

export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'

    

Its value will be split on spaces and prepended to the command line on each invocation.

RETURN VALUES

•

0: All files successfully scanned with no issues.

•

1: All files successfully scanned with some issues.

•

2: Some files could not be processed (e.g. file not found).

•

3: ShellCheck was invoked with bad syntax (e.g. unknown flag).

•

4: ShellCheck was invoked with bad options (e.g. unknown formatter).

LOCALE

Windows users seeing commitBuffer: invalid argument (invalid character) should set their terminal to use UTF-8 with chcp 65001.

KNOWN INCOMPATIBILITIES

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.

REPORTING BUGS

https://github.com/koalaman/shellcheck/issues

AUTHORS

COPYRIGHT

SEE ALSO