465 lines
14 KiB
Groff
465 lines
14 KiB
Groff
.\" Automatically generated by Pandoc 2.9.2.1
|
|
.\"
|
|
.TH "SHELLCHECK" "1" "" "Shell script analysis tool" ""
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
shellcheck - Shell script analysis tool
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[B]shellcheck\f[R] [\f[I]OPTIONS\f[R]...] \f[I]FILES\f[R]...
|
|
.SH DESCRIPTION
|
|
.PP
|
|
ShellCheck is a static analysis and linting tool for sh/bash scripts.
|
|
It\[aq]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.
|
|
.PP
|
|
ShellCheck gives shell specific advice.
|
|
Consider this line:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
(( area = 3.14*r*r ))
|
|
\f[R]
|
|
.fi
|
|
.IP \[bu] 2
|
|
For scripts starting with \f[C]#!/bin/sh\f[R] (or when using
|
|
\f[C]-s sh\f[R]), ShellCheck will warn that \f[C](( .. ))\f[R] is not
|
|
POSIX compliant (similar to checkbashisms).
|
|
.IP \[bu] 2
|
|
For scripts starting with \f[C]#!/bin/bash\f[R] (or using
|
|
\f[C]-s bash\f[R]), ShellCheck will warn that decimals are not
|
|
supported.
|
|
.IP \[bu] 2
|
|
For scripts starting with \f[C]#!/bin/ksh\f[R] (or using
|
|
\f[C]-s ksh\f[R]), ShellCheck will not warn at all, as \f[C]ksh\f[R]
|
|
supports decimals in arithmetic contexts.
|
|
.SH OPTIONS
|
|
.TP
|
|
\f[B]-a\f[R],\ \f[B]--check-sourced\f[R]
|
|
Emit warnings in sourced files.
|
|
Normally, \f[C]shellcheck\f[R] will only warn about issues in the
|
|
specified files.
|
|
With this option, any issues in sourced files will also be reported.
|
|
.TP
|
|
\f[B]-C\f[R][\f[I]WHEN\f[R]],\ \f[B]--color\f[R][=\f[I]WHEN\f[R]]
|
|
For TTY output, enable colors \f[I]always\f[R], \f[I]never\f[R] or
|
|
\f[I]auto\f[R].
|
|
The default is \f[I]auto\f[R].
|
|
\f[B]--color\f[R] without an argument is equivalent to
|
|
\f[B]--color=always\f[R].
|
|
.TP
|
|
\f[B]-i\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]...],\ \f[B]--include=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]...]
|
|
Explicitly include only the specified codes in the report.
|
|
Subsequent \f[B]-i\f[R] 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.
|
|
.TP
|
|
\f[B]-e\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]...],\ \f[B]--exclude=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]...]
|
|
Explicitly exclude the specified codes from the report.
|
|
Subsequent \f[B]-e\f[R] options are cumulative, but all the codes can be
|
|
specified at once, comma-separated as a single argument.
|
|
.TP
|
|
\f[B]-f\f[R] \f[I]FORMAT\f[R], \f[B]--format=\f[R]\f[I]FORMAT\f[R]
|
|
Specify the output format of shellcheck, which prints its results in the
|
|
standard output.
|
|
Subsequent \f[B]-f\f[R] options are ignored, see \f[B]FORMATS\f[R] below
|
|
for more information.
|
|
.TP
|
|
\f[B]--list-optional\f[R]
|
|
Output a list of known optional checks.
|
|
These can be enabled with \f[B]-o\f[R] flags or \f[B]enable\f[R]
|
|
directives.
|
|
.TP
|
|
\f[B]--norc\f[R]
|
|
Don\[aq]t try to look for .shellcheckrc configuration files.
|
|
.TP
|
|
\f[B]-o\f[R]\ \f[I]NAME1\f[R][,\f[I]NAME2\f[R]...],\ \f[B]--enable=\f[R]\f[I]NAME1\f[R][,\f[I]NAME2\f[R]...]
|
|
Enable optional checks.
|
|
The special name \f[I]all\f[R] enables all of them.
|
|
Subsequent \f[B]-o\f[R] options accumulate.
|
|
This is equivalent to specifying \f[B]enable\f[R] directives.
|
|
.TP
|
|
\f[B]-P\f[R]\ \f[I]SOURCEPATH\f[R],\ \f[B]--source-path=\f[R]\f[I]SOURCEPATH\f[R]
|
|
Specify paths to search for sourced files, separated by \f[C]:\f[R] on
|
|
Unix and \f[C];\f[R] on Windows.
|
|
This is equivalent to specifying \f[C]search-path\f[R] directives.
|
|
.TP
|
|
\f[B]-s\f[R]\ \f[I]shell\f[R],\ \f[B]--shell=\f[R]\f[I]shell\f[R]
|
|
Specify Bourne shell dialect.
|
|
Valid values are \f[I]sh\f[R], \f[I]bash\f[R], \f[I]dash\f[R] and
|
|
\f[I]ksh\f[R].
|
|
The default is to deduce the shell from the file\[aq]s \f[C]shell\f[R]
|
|
directive, shebang, or \f[C].bash/.bats/.dash/.ksh\f[R] extension, in
|
|
that order.
|
|
\f[I]sh\f[R] refers to POSIX \f[C]sh\f[R] (not the system\[aq]s), and
|
|
will warn of portability issues.
|
|
.TP
|
|
\f[B]-S\f[R]\ \f[I]SEVERITY\f[R],\ \f[B]--severity=\f[R]\f[I]severity\f[R]
|
|
Specify minimum severity of errors to consider.
|
|
Valid values in order of severity are \f[I]error\f[R],
|
|
\f[I]warning\f[R], \f[I]info\f[R] and \f[I]style\f[R].
|
|
The default is \f[I]style\f[R].
|
|
.TP
|
|
\f[B]-V\f[R],\ \f[B]--version\f[R]
|
|
Print version information and exit.
|
|
.TP
|
|
\f[B]-W\f[R] \f[I]NUM\f[R],\ \f[B]--wiki-link-count=NUM\f[R]
|
|
For TTY output, show \f[I]NUM\f[R] wiki links to more information about
|
|
mentioned warnings.
|
|
Set to 0 to disable them entirely.
|
|
.TP
|
|
\f[B]-x\f[R],\ \f[B]--external-sources\f[R]
|
|
Follow \f[C]source\f[R] statements even when the file is not specified
|
|
as input.
|
|
By default, \f[C]shellcheck\f[R] will only follow files specified on the
|
|
command line (plus \f[C]/dev/null\f[R]).
|
|
This option allows following any file the script may \f[C]source\f[R].
|
|
.RS
|
|
.PP
|
|
This option may also be enabled using \f[C]external-sources=true\f[R] in
|
|
\f[C].shellcheckrc\f[R].
|
|
This flag takes precedence.
|
|
.RE
|
|
.TP
|
|
\f[B]FILES...\f[R]
|
|
One or more script files to check, or \[dq]-\[dq] for standard input.
|
|
.SH FORMATS
|
|
.TP
|
|
\f[B]tty\f[R]
|
|
Plain text, human readable output.
|
|
This is the default.
|
|
.TP
|
|
\f[B]gcc\f[R]
|
|
GCC compatible output.
|
|
Useful for editors that support compiling and showing syntax errors.
|
|
.RS
|
|
.PP
|
|
For example, in Vim,
|
|
\f[C]:set makeprg=shellcheck\[rs] -f\[rs] gcc\[rs] %\f[R] will allow
|
|
using \f[C]:make\f[R] to check the script, and \f[C]:cnext\f[R] to jump
|
|
to the next error.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<file>:<line>:<column>: <type>: <message>
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
\f[B]checkstyle\f[R]
|
|
Checkstyle compatible XML output.
|
|
Supported directly or through plugins by many IDEs and build monitoring
|
|
systems.
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
<?xml version=\[aq]1.0\[aq] encoding=\[aq]UTF-8\[aq]?>
|
|
<checkstyle version=\[aq]4.3\[aq]>
|
|
<file name=\[aq]file\[aq]>
|
|
<error
|
|
line=\[aq]line\[aq]
|
|
column=\[aq]column\[aq]
|
|
severity=\[aq]severity\[aq]
|
|
message=\[aq]message\[aq]
|
|
source=\[aq]ShellCheck.SC####\[aq] />
|
|
...
|
|
</file>
|
|
...
|
|
</checkstyle>
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
\f[B]diff\f[R]
|
|
Auto-fixes in unified diff format.
|
|
Can be piped to \f[C]git apply\f[R] or \f[C]patch -p1\f[R] to
|
|
automatically apply fixes.
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
--- a/test.sh
|
|
+++ b/test.sh
|
|
\[at]\[at] -2,6 +2,6 \[at]\[at]
|
|
## Example of a broken script.
|
|
for f in $(ls *.m3u)
|
|
do
|
|
- grep -qi hq.*mp3 $f \[rs]
|
|
+ grep -qi hq.*mp3 \[dq]$f\[dq] \[rs]
|
|
&& echo -e \[aq]Playlist $f contains a HQ file in mp3 format\[aq]
|
|
done
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
\f[B]json1\f[R]
|
|
Json is a popular serialization format that is more suitable for web
|
|
applications.
|
|
ShellCheck\[aq]s json is compact and contains only the bare minimum.
|
|
Tabs are counted as 1 character.
|
|
.RS
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
{
|
|
comments: [
|
|
{
|
|
\[dq]file\[dq]: \[dq]filename\[dq],
|
|
\[dq]line\[dq]: lineNumber,
|
|
\[dq]column\[dq]: columnNumber,
|
|
\[dq]level\[dq]: \[dq]severitylevel\[dq],
|
|
\[dq]code\[dq]: errorCode,
|
|
\[dq]message\[dq]: \[dq]warning message\[dq]
|
|
},
|
|
...
|
|
]
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.TP
|
|
\f[B]json\f[R]
|
|
This is a legacy version of the \f[B]json1\f[R] format.
|
|
It\[aq]s a raw array of comments, and all offsets have a tab stop of 8.
|
|
.TP
|
|
\f[B]quiet\f[R]
|
|
Suppress all normal output.
|
|
Exit with zero if no issues are found, otherwise exit with one.
|
|
Stops processing after the first issue.
|
|
.SH DIRECTIVES
|
|
.PP
|
|
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:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# shellcheck key=value key=value
|
|
command-or-structure
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
For example, to suppress SC2035 about using \f[C]./*.jpg\f[R]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# shellcheck disable=SC2035
|
|
echo \[dq]Files: \[dq] *.jpg
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
To tell ShellCheck where to look for an otherwise dynamically determined
|
|
file:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# shellcheck source=./lib.sh
|
|
source \[dq]$(find_install_dir)/lib.sh\[dq]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Here a shell brace group is used to suppress a warning on multiple
|
|
lines:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# shellcheck disable=SC2016
|
|
{
|
|
echo \[aq]Modifying $PATH\[aq]
|
|
echo \[aq]PATH=foo:$PATH\[aq] >> \[ti]/.bashrc
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Valid keys are:
|
|
.TP
|
|
\f[B]disable\f[R]
|
|
Disables a comma separated list of error codes for the following
|
|
command.
|
|
The command can be a simple command like \f[C]echo foo\f[R], or a
|
|
compound command like a function definition, subshell block or loop.
|
|
A range can be be specified with a dash, e.g.
|
|
\f[C]disable=SC3000-SC4000\f[R] to exclude 3xxx.
|
|
All warnings can be disabled with \f[C]disable=all\f[R].
|
|
.TP
|
|
\f[B]enable\f[R]
|
|
Enable an optional check by name, as listed with
|
|
\f[B]--list-optional\f[R].
|
|
Only file-wide \f[C]enable\f[R] directives are considered.
|
|
.TP
|
|
\f[B]external-sources\f[R]
|
|
Set to \f[C]true\f[R] in \f[C].shellcheckrc\f[R] to always allow
|
|
ShellCheck to open arbitrary files from \[aq]source\[aq] statements (the
|
|
way most tools do).
|
|
.RS
|
|
.PP
|
|
This option defaults to \f[C]false\f[R] only due to ShellCheck\[aq]s
|
|
origin as a remote service for checking untrusted scripts.
|
|
It can safely be enabled for normal development.
|
|
.RE
|
|
.TP
|
|
\f[B]source\f[R]
|
|
Overrides the filename included by a \f[C]source\f[R]/\f[C].\f[R]
|
|
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
|
|
\f[C]/dev/null\f[R].
|
|
.TP
|
|
\f[B]source-path\f[R]
|
|
Add a directory to the search path for \f[C]source\f[R]/\f[C].\f[R]
|
|
statements (by default, only ShellCheck\[aq]s working directory is
|
|
included).
|
|
Absolute paths will also be rooted in these paths.
|
|
The special path \f[C]SCRIPTDIR\f[R] can be used to specify the
|
|
currently checked script\[aq]s directory, as in
|
|
\f[C]source-path=SCRIPTDIR\f[R] or
|
|
\f[C]source-path=SCRIPTDIR/../libs\f[R].
|
|
Multiple paths accumulate, and \f[C]-P\f[R] takes precedence over them.
|
|
.TP
|
|
\f[B]shell\f[R]
|
|
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
|
|
\[aq]disable=SC2039\[aq].
|
|
.SH RC FILES
|
|
.PP
|
|
Unless \f[C]--norc\f[R] is used, ShellCheck will look for a file
|
|
\f[C].shellcheckrc\f[R] or \f[C]shellcheckrc\f[R] in the script\[aq]s
|
|
directory and each parent directory.
|
|
If found, it will read \f[C]key=value\f[R] pairs from it and treat them
|
|
as file-wide directives.
|
|
.PP
|
|
Here is an example \f[C].shellcheckrc\f[R]:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
# Look for \[aq]source\[aq]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 \[aq]source\[aq]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
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
If no \f[C].shellcheckrc\f[R] is found in any of the parent directories,
|
|
ShellCheck will look in \f[C]\[ti]/.shellcheckrc\f[R] followed by the
|
|
XDG config directory (usually \f[C]\[ti]/.config/shellcheckrc\f[R]) on
|
|
Unix, or \f[C]%APPDATA%/shellcheckrc\f[R] on Windows.
|
|
Only the first file found will be used.
|
|
.PP
|
|
Note for Snap users: the Snap sandbox disallows access to hidden files.
|
|
Use \f[C]shellcheckrc\f[R] without the dot instead.
|
|
.PP
|
|
Note for Docker users: ShellCheck will only be able to look for files
|
|
that are mounted in the container, so \f[C]\[ti]/.shellcheckrc\f[R] will
|
|
not be read.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.PP
|
|
The environment variable \f[C]SHELLCHECK_OPTS\f[R] can be set with
|
|
default flags:
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
export SHELLCHECK_OPTS=\[aq]--shell=bash --exclude=SC2016\[aq]
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Its value will be split on spaces and prepended to the command line on
|
|
each invocation.
|
|
.SH RETURN VALUES
|
|
.PP
|
|
ShellCheck uses the following exit codes:
|
|
.IP \[bu] 2
|
|
0: All files successfully scanned with no issues.
|
|
.IP \[bu] 2
|
|
1: All files successfully scanned with some issues.
|
|
.IP \[bu] 2
|
|
2: Some files could not be processed (e.g.
|
|
file not found).
|
|
.IP \[bu] 2
|
|
3: ShellCheck was invoked with bad syntax (e.g.
|
|
unknown flag).
|
|
.IP \[bu] 2
|
|
4: ShellCheck was invoked with bad options (e.g.
|
|
unknown formatter).
|
|
.SH LOCALE
|
|
.PP
|
|
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.
|
|
\f[C]LC_CTYPE\f[R] is respected for output, and defaults to UTF-8 for
|
|
locales where encoding is unspecified (such as the \f[C]C\f[R] locale).
|
|
.PP
|
|
Windows users seeing
|
|
\f[C]commitBuffer: invalid argument (invalid character)\f[R] should set
|
|
their terminal to use UTF-8 with \f[C]chcp 65001\f[R].
|
|
.SH KNOWN INCOMPATIBILITIES
|
|
.PP
|
|
(If nothing in this section makes sense, you are unlikely to be affected
|
|
by it)
|
|
.PP
|
|
To avoid confusing and misguided suggestions, ShellCheck requires
|
|
function bodies to be either \f[C]{ brace groups; }\f[R] or
|
|
\f[C]( subshells )\f[R], and function names containing \f[C][]*=!\f[R]
|
|
are only recognized after a \f[C]function\f[R] keyword.
|
|
.PP
|
|
The following unconventional function definitions are identical in Bash,
|
|
but ShellCheck only recognizes the latter.
|
|
.IP
|
|
.nf
|
|
\f[C]
|
|
[x!=y] () [[ $1 ]]
|
|
function [x!=y] () { [[ $1 ]]; }
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Shells without the \f[C]function\f[R] keyword do not allow these
|
|
characters in function names to begin with.
|
|
Function names containing \f[C]{}\f[R] are not supported at all.
|
|
.PP
|
|
Further, if ShellCheck sees \f[C][x!=y]\f[R] it will assume this is an
|
|
invalid comparison.
|
|
To invoke the above function, quote the command as in
|
|
\f[C]\[aq][x!=y]\[aq]\f[R], or to retain the same globbing behavior, use
|
|
\f[C]command [x!=y]\f[R].
|
|
.PP
|
|
ShellCheck imposes additional restrictions on the \f[C][\f[R] command to
|
|
help diagnose common invalid uses.
|
|
While \f[C][ $x= 1 ]\f[R] is defined in POSIX, ShellCheck will assume it
|
|
was intended as the much more likely comparison
|
|
\f[C][ \[dq]$x\[dq] = 1 ]\f[R] and fail accordingly.
|
|
For unconventional or dynamic uses of the \f[C][\f[R] command, use
|
|
\f[C]test\f[R] or \f[C]\[rs][\f[R] instead.
|
|
.SH REPORTING BUGS
|
|
.PP
|
|
Bugs and issues can be reported on GitHub:
|
|
.PP
|
|
https://github.com/koalaman/shellcheck/issues
|
|
.SH AUTHORS
|
|
.PP
|
|
ShellCheck is developed and maintained by Vidar Holen, with assistance
|
|
from a long list of wonderful contributors.
|
|
.SH COPYRIGHT
|
|
.PP
|
|
Copyright 2012-2021, Vidar Holen and contributors.
|
|
Licensed under the GNU General Public License version 3 or later, see
|
|
https://gnu.org/licenses/gpl.html
|
|
.SH SEE ALSO
|
|
.PP
|
|
sh(1) bash(1)
|