1SHELLCHECK(1) SHELLCHECK(1)
2
6 shellcheck - Shell script analysis tool
7
9 shellcheck [OPTIONS...] FILES...
10
12 ShellCheck is a static analysis and linting tool for sh/bash scripts.
13 It's mainly focused on handling typical beginner and intermediate level
14 syntax errors and pitfalls where the shell just gives a cryptic error
15 message or strange behavior, but it also reports on a few more advanced
16 issues where corner cases can cause delayed failures.
17 ShellCheck gives shell specific advice. Consider this line:
19 (( area = 3.14*r*r ))
21 • For scripts starting with #!/bin/sh (or when using -s sh), ShellCheck
23 will warn that (( .. )) is not POSIX compliant (similar to check‐
24 bashisms).
25 • For scripts starting with #!/bin/bash (or using -s bash), ShellCheck
27 will warn that decimals are not supported.
28 • For scripts starting with #!/bin/ksh (or using -s ksh), ShellCheck
30 will not warn at all, as ksh supports decimals in arithmetic con‐
31 texts.
32
34 -a, --check-sourced
35 Emit warnings in sourced files. Normally, shellcheck will only
36 warn about issues in the specified files. With this option, any
37 issues in sourced files will also be reported.
38 -C[WHEN], --color[=WHEN]
40 For TTY output, enable colors always, never or auto. The de‐
41 fault is auto. --color without an argument is equivalent to
42 --color=always.
43 -i CODE1[,CODE2...], --include=CODE1[,CODE2...]
45 Explicitly include only the specified codes in the report. Sub‐
46 sequent -i options are cumulative, but all the codes can be
47 specified at once, comma-separated as a single argument. In‐
48 clude options override any provided exclude options.
49 -e CODE1[,CODE2...], --exclude=CODE1[,CODE2...]
51 Explicitly exclude the specified codes from the report. Subse‐
52 quent -e options are cumulative, but all the codes can be speci‐
53 fied at once, comma-separated as a single argument.
54 -f FORMAT, --format=FORMAT
56 Specify the output format of shellcheck, which prints its re‐
57 sults in the standard output. Subsequent -f options are ig‐
58 nored, see FORMATS below for more information.
59 --list-optional
61 Output a list of known optional checks. These can be enabled
62 with -o flags or enable directives.
63 --norc Don't try to look for .shellcheckrc configuration files.
65 -o NAME1[,NAME2...], --enable=NAME1[,NAME2...]
67 Enable optional checks. The special name all enables all of
68 them. Subsequent -o options accumulate. This is equivalent to
69 specifying enable directives.
70 -P SOURCEPATH, --source-path=SOURCEPATH
72 Specify paths to search for sourced files, separated by : on
73 Unix and ; on Windows. This is equivalent to specifying search-
74 path directives.
75 -s shell, --shell=shell
77 Specify Bourne shell dialect. Valid values are sh, bash, dash
78 and ksh. The default is to deduce the shell from the file's
79 shell directive, shebang, or .bash/.bats/.dash/.ksh extension,
80 in that order. sh refers to POSIX sh (not the system's), and
81 will warn of portability issues.
82 -S SEVERITY, --severity=severity
84 Specify minimum severity of errors to consider. Valid values in
85 order of severity are error, warning, info and style. The de‐
86 fault is style.
87 -V, --version
89 Print version information and exit.
90 -W NUM, --wiki-link-count=NUM
92 For TTY output, show NUM wiki links to more information about
93 mentioned warnings. Set to 0 to disable them entirely.
94 -x, --external-sources
96 Follow source statements even when the file is not specified as
97 input. By default, shellcheck will only follow files specified
98 on the command line (plus /dev/null). This option allows fol‐
99 lowing any file the script may source.
100 This option may also be enabled using external-sources=true in
102 .shellcheckrc. This flag takes precedence.
103 FILES...
105 One or more script files to check, or "-" for standard input.
106
108 tty Plain text, human readable output. This is the default.
109 gcc GCC compatible output. Useful for editors that support compil‐
111 ing and showing syntax errors.
112 For example, in Vim, :set makeprg=shellcheck\ -f\ gcc\ % will
114 allow using :make to check the script, and :cnext to jump to the
115 next error.
116 <file>:<line>:<column>: <type>: <message>
118 checkstyle
120 Checkstyle compatible XML output. Supported directly or through
121 plugins by many IDEs and build monitoring systems.
122 <?xml version='1.0' encoding='UTF-8'?>
124 <checkstyle version='4.3'>
125 <file name='file'>
126 <error
127 line='line'
128 column='column'
129 severity='severity'
130 message='message'
131 source='ShellCheck.SC####' />
132 ...
133 </file>
134 ...
135 </checkstyle>
136 diff Auto-fixes in unified diff format. Can be piped to git apply or
138 patch -p1 to automatically apply fixes.
139 --- a/test.sh
141 +++ b/test.sh
142 @@ -2,6 +2,6 @@
143 ## Example of a broken script.
144 for f in $(ls *.m3u)
145 do
146 - grep -qi hq.*mp3 $f \
147 + grep -qi hq.*mp3 "$f" \
148 && echo -e 'Playlist $f contains a HQ file in mp3 format'
149 done
150 json1 Json is a popular serialization format that is more suitable for
152 web applications. ShellCheck's json is compact and contains on‐
153 ly the bare minimum. Tabs are counted as 1 character.
154 {
156 comments: [
157 {
158 "file": "filename",
159 "line": lineNumber,
160 "column": columnNumber,
161 "level": "severitylevel",
162 "code": errorCode,
163 "message": "warning message"
164 },
165 ...
166 ]
167 }
168 json This is a legacy version of the json1 format. It's a raw array
170 of comments, and all offsets have a tab stop of 8.
171 quiet Suppress all normal output. Exit with zero if no issues are
173 found, otherwise exit with one. Stops processing after the
174 first issue.
175
177 ShellCheck directives can be specified as comments in the shell script.
178 If they appear before the first command, they are considered file-wide.
179 Otherwise, they apply to the immediately following command or block:
180 # shellcheck key=value key=value
182 command-or-structure
183 For example, to suppress SC2035 about using ./*.jpg:
185 # shellcheck disable=SC2035
187 echo "Files: " *.jpg
188 To tell ShellCheck where to look for an otherwise dynamically deter‐
190 mined file:
191 # shellcheck source=./lib.sh
193 source "$(find_install_dir)/lib.sh"
194 Here a shell brace group is used to suppress a warning on multiple
196 lines:
197 # shellcheck disable=SC2016
199 {
200 echo 'Modifying $PATH'
201 echo 'PATH=foo:$PATH' >> ~/.bashrc
202 }
203 Valid keys are:
205 disable
207 Disables a comma separated list of error codes for the following
208 command. The command can be a simple command like echo foo, or
209 a compound command like a function definition, subshell block or
210 loop. A range can be be specified with a dash, e.g. dis‐
211 able=SC3000-SC4000 to exclude 3xxx. All warnings can be dis‐
212 abled with disable=all.
213 enable Enable an optional check by name, as listed with --list-option‐
215 al. Only file-wide enable directives are considered.
216 external-sources
218 Set to true in .shellcheckrc to always allow ShellCheck to open
219 arbitrary files from 'source' statements (the way most tools
220 do).
221 This option defaults to false only due to ShellCheck's origin as
223 a remote service for checking untrusted scripts. It can safely
224 be enabled for normal development.
225 source Overrides the filename included by a source/. statement. This
227 can be used to tell shellcheck where to look for a file whose
228 name is determined at runtime, or to skip a source by telling it
229 to use /dev/null.
230 source-path
232 Add a directory to the search path for source/. statements (by
233 default, only ShellCheck's working directory is included). Ab‐
234 solute paths will also be rooted in these paths. The special
235 path SCRIPTDIR can be used to specify the currently checked
236 script's directory, as in source-path=SCRIPTDIR or source-
237 path=SCRIPTDIR/../libs. Multiple paths accumulate, and -P takes
238 precedence over them.
239 shell Overrides the shell detected from the shebang. This is useful
241 for files meant to be included (and thus lacking a shebang), or
242 possibly as a more targeted alternative to 'disable=SC2039'.
243
245 Unless --norc is used, ShellCheck will look for a file .shellcheckrc or
246 shellcheckrc in the script's directory and each parent directory. If
247 found, it will read key=value pairs from it and treat them as file-wide
248 directives.
249 Here is an example .shellcheckrc:
251 # Look for 'source'd files relative to the checked script,
253 # and also look for absolute paths in /mnt/chroot
254 source-path=SCRIPTDIR
255 source-path=/mnt/chroot
256 # Allow opening any 'source'd file, even if not specified as input
258 external-sources=true
259 # Turn on warnings for unquoted variables with safe values
261 enable=quote-safe-variables
262 # Turn on warnings for unassigned uppercase variables
264 enable=check-unassigned-uppercase
265 # Allow [ ! -z foo ] instead of suggesting -n
267 disable=SC2236
268 If no .shellcheckrc is found in any of the parent directories,
270 ShellCheck will look in ~/.shellcheckrc followed by the XDG config di‐
271 rectory (usually ~/.config/shellcheckrc) on Unix, or %APPDA‐
272 TA%/shellcheckrc on Windows. Only the first file found will be used.
273 Note for Snap users: the Snap sandbox disallows access to hidden files.
275 Use shellcheckrc without the dot instead.
276 Note for Docker users: ShellCheck will only be able to look for files
278 that are mounted in the container, so ~/.shellcheckrc will not be read.
279
281 The environment variable SHELLCHECK_OPTS can be set with default flags:
282 export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'
284 Its value will be split on spaces and prepended to the command line on
286 each invocation.
287
289 ShellCheck uses the following exit codes:
290 • 0: All files successfully scanned with no issues.
292 • 1: All files successfully scanned with some issues.
294 • 2: Some files could not be processed (e.g. file not found).
296 • 3: ShellCheck was invoked with bad syntax (e.g. unknown flag).
298 • 4: ShellCheck was invoked with bad options (e.g. unknown formatter).
300
302 This version of ShellCheck is only available in English. All files are
303 leniently decoded as UTF-8, with a fallback of ISO-8859-1 for invalid
304 sequences. LC_CTYPE is respected for output, and defaults to UTF-8 for
305 locales where encoding is unspecified (such as the C locale).
306 Windows users seeing commitBuffer: invalid argument (invalid character)
308 should set their terminal to use UTF-8 with chcp 65001.
309
311 (If nothing in this section makes sense, you are unlikely to be affect‐
312 ed by it)
313 To avoid confusing and misguided suggestions, ShellCheck requires func‐
315 tion bodies to be either { brace groups; } or ( subshells ), and func‐
316 tion names containing []*=! are only recognized after a function key‐
317 word.
318 The following unconventional function definitions are identical in
320 Bash, but ShellCheck only recognizes the latter.
321 [x!=y] () [[ $1 ]]
323 function [x!=y] () { [[ $1 ]]; }
324 Shells without the function keyword do not allow these characters in
326 function names to begin with. Function names containing {} are not
327 supported at all.
328 Further, if ShellCheck sees [x!=y] it will assume this is an invalid
330 comparison. To invoke the above function, quote the command as in
331 '[x!=y]', or to retain the same globbing behavior, use command [x!=y].
332 ShellCheck imposes additional restrictions on the [ command to help di‐
334 agnose common invalid uses. While [ $x= 1 ] is defined in POSIX,
335 ShellCheck will assume it was intended as the much more likely compari‐
336 son [ "$x" = 1 ] and fail accordingly. For unconventional or dynamic
337 uses of the [ command, use test or \[ instead.
338
340 Bugs and issues can be reported on GitHub:
341 https://github.com/koalaman/shellcheck/issues
343
345 ShellCheck is developed and maintained by Vidar Holen, with assistance
346 from a long list of wonderful contributors.
347
349 Copyright 2012-2021, Vidar Holen and contributors. Licensed under the
350 GNU General Public License version 3 or later, see https://gnu.org/li‐
351 censes/gpl.html
352
354 sh(1) bash(1)
355Shell script analysis tool SHELLCHECK(1)