1SHELLCHECK(1)                                                    SHELLCHECK(1)
2
3
4

NAME

6       shellcheck - Shell script analysis tool
7

SYNOPSIS

9       shellcheck [OPTIONS...] FILES...
10

DESCRIPTION

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
18       ShellCheck gives shell specific advice.  Consider this line:
19
20              (( area = 3.14*r*r ))
21
22       • 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
26       • For  scripts starting with #!/bin/bash (or using -s bash), ShellCheck
27         will warn that decimals are not supported.
28
29       • 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

OPTIONS

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
39       -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
44       -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
50       -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
55       -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
60       --list-optional
61              Output  a  list  of known optional checks.  These can be enabled
62              with -o flags or enable directives.
63
64       --norc Don't try to look for .shellcheckrc configuration files.
65
66       -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
71       -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
76       -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
83       -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
88       -V, --version
89              Print version information and exit.
90
91       -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
95       -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
101              This option may also be enabled using  external-sources=true  in
102              .shellcheckrc.  This flag takes precedence.
103
104       FILES...
105              One or more script files to check, or "-" for standard input.
106

FORMATS

108       tty    Plain text, human readable output.  This is the default.
109
110       gcc    GCC  compatible output.  Useful for editors that support compil‐
111              ing and showing syntax errors.
112
113              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
117                     <file>:<line>:<column>: <type>: <message>
118
119       checkstyle
120              Checkstyle compatible XML output.  Supported directly or through
121              plugins by many IDEs and build monitoring systems.
122
123                     <?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
137       diff   Auto-fixes in unified diff format.  Can be piped to git apply or
138              patch -p1 to automatically apply fixes.
139
140                     --- 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
151       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
155                     {
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
169       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
172       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

DIRECTIVES

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
181              # shellcheck key=value key=value
182              command-or-structure
183
184       For example, to suppress SC2035 about using ./*.jpg:
185
186              # shellcheck disable=SC2035
187              echo "Files: " *.jpg
188
189       To  tell  ShellCheck  where to look for an otherwise dynamically deter‐
190       mined file:
191
192              # shellcheck source=./lib.sh
193              source "$(find_install_dir)/lib.sh"
194
195       Here a shell brace group is used to  suppress  a  warning  on  multiple
196       lines:
197
198              # shellcheck disable=SC2016
199              {
200                echo 'Modifying $PATH'
201                echo 'PATH=foo:$PATH' >> ~/.bashrc
202              }
203
204       Valid keys are:
205
206       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
214       enable Enable an optional check by name, as listed with  --list-option‐
215              al.  Only file-wide enable directives are considered.
216
217       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
222              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
226       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
231       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
240       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

RC FILES

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
250       Here is an example .shellcheckrc:
251
252              # 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
257              # Allow opening any 'source'd file, even if not specified as input
258              external-sources=true
259
260              # Turn on warnings for unquoted variables with safe values
261              enable=quote-safe-variables
262
263              # Turn on warnings for unassigned uppercase variables
264              enable=check-unassigned-uppercase
265
266              # Allow [ ! -z foo ] instead of suggesting -n
267              disable=SC2236
268
269       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
274       Note for Snap users: the Snap sandbox disallows access to hidden files.
275       Use shellcheckrc without the dot instead.
276
277       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

ENVIRONMENT VARIABLES

281       The environment variable SHELLCHECK_OPTS can be set with default flags:
282
283              export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'
284
285       Its value will be split on spaces and prepended to the command line  on
286       each invocation.
287

RETURN VALUES

289       ShellCheck uses the following exit codes:
290
291       • 0: All files successfully scanned with no issues.
292
293       • 1: All files successfully scanned with some issues.
294
295       • 2: Some files could not be processed (e.g.  file not found).
296
297       • 3: ShellCheck was invoked with bad syntax (e.g.  unknown flag).
298
299       • 4: ShellCheck was invoked with bad options (e.g.  unknown formatter).
300

LOCALE

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
307       Windows users seeing commitBuffer: invalid argument (invalid character)
308       should set their terminal to use UTF-8 with chcp 65001.
309

KNOWN INCOMPATIBILITIES

311       (If nothing in this section makes sense, you are unlikely to be affect‐
312       ed by it)
313
314       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
319       The  following  unconventional  function  definitions  are identical in
320       Bash, but ShellCheck only recognizes the latter.
321
322              [x!=y] () [[ $1 ]]
323              function [x!=y] () { [[ $1 ]]; }
324
325       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
329       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
333       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

REPORTING BUGS

340       Bugs and issues can be reported on GitHub:
341
342       https://github.com/koalaman/shellcheck/issues
343

AUTHORS

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

SEE ALSO

354       sh(1) bash(1)
355
356
357
358Shell script analysis tool                                       SHELLCHECK(1)
Impressum