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       FILES...
102              One or more script files to check, or "-" for standard input.
103

FORMATS

105       tty    Plain text, human readable output.  This is the default.
106
107       gcc    GCC compatible output.  Useful for editors that support  compil‐
108              ing and showing syntax errors.
109
110              For  example,  in  Vim, :set makeprg=shellcheck\ -f\ gcc\ % will
111              allow using :make to check the script, and :cnext to jump to the
112              next error.
113
114                     <file>:<line>:<column>: <type>: <message>
115
116       checkstyle
117              Checkstyle compatible XML output.  Supported directly or through
118              plugins by many IDEs and build monitoring systems.
119
120                     <?xml version='1.0' encoding='UTF-8'?>
121                     <checkstyle version='4.3'>
122                       <file name='file'>
123                         <error
124                           line='line'
125                           column='column'
126                           severity='severity'
127                           message='message'
128                           source='ShellCheck.SC####' />
129                         ...
130                       </file>
131                       ...
132                     </checkstyle>
133
134       diff   Auto-fixes in unified diff format.  Can be piped to git apply or
135              patch -p1 to automatically apply fixes.
136
137                     --- a/test.sh
138                     +++ b/test.sh
139                     @@ -2,6 +2,6 @@
140                      ## Example of a broken script.
141                      for f in $(ls *.m3u)
142                      do
143                     -  grep -qi hq.*mp3 $f \
144                     +  grep -qi hq.*mp3 "$f" \
145                          && echo -e 'Playlist $f contains a HQ file in mp3 format'
146                      done
147
148       json1  Json is a popular serialization format that is more suitable for
149              web applications.  ShellCheck's json is compact and contains on‐
150              ly the bare minimum.  Tabs are counted as 1 character.
151
152                     {
153                       comments: [
154                         {
155                           "file": "filename",
156                           "line": lineNumber,
157                           "column": columnNumber,
158                           "level": "severitylevel",
159                           "code": errorCode,
160                           "message": "warning message"
161                         },
162                         ...
163                       ]
164                     }
165
166       json   This  is a legacy version of the json1 format.  It's a raw array
167              of comments, and all offsets have a tab stop of 8.
168
169       quiet  Suppress all normal output.  Exit with zero  if  no  issues  are
170              found,  otherwise  exit  with  one.   Stops processing after the
171              first issue.
172

DIRECTIVES

174       ShellCheck directives can be specified as comments in the shell script.
175       If they appear before the first command, they are considered file-wide.
176       Otherwise, they apply to the immediately following command or block:
177
178              # shellcheck key=value key=value
179              command-or-structure
180
181       For example, to suppress SC2035 about using ./*.jpg:
182
183              # shellcheck disable=SC2035
184              echo "Files: " *.jpg
185
186       To tell ShellCheck where to look for an  otherwise  dynamically  deter‐
187       mined file:
188
189              # shellcheck source=./lib.sh
190              source "$(find_install_dir)/lib.sh"
191
192       Here  a  shell  brace  group  is used to suppress a warning on multiple
193       lines:
194
195              # shellcheck disable=SC2016
196              {
197                echo 'Modifying $PATH'
198                echo 'PATH=foo:$PATH' >> ~/.bashrc
199              }
200
201       Valid keys are:
202
203       disable
204              Disables a comma separated list of error codes for the following
205              command.   The command can be a simple command like echo foo, or
206              a compound command like a function definition, subshell block or
207              loop.   A  range  can  be  be  specified with a dash, e.g.  dis‐
208              able=SC3000-SC4000 to exclude 3xxx.
209
210       enable Enable an optional check by name, as listed with  --list-option‐
211              al.  Only file-wide enable directives are considered.
212
213       source Overrides  the filename included by a source/.  statement.  This
214              can be used to tell shellcheck where to look for  a  file  whose
215              name is determined at runtime, or to skip a source by telling it
216              to use /dev/null.
217
218       source-path
219              Add a directory to the search path for source/.  statements  (by
220              default,  only ShellCheck's working directory is included).  Ab‐
221              solute paths will also be rooted in these  paths.   The  special
222              path  SCRIPTDIR  can  be  used  to specify the currently checked
223              script's  directory,  as  in  source-path=SCRIPTDIR  or  source-
224              path=SCRIPTDIR/../libs.  Multiple paths accumulate, and -P takes
225              precedence over them.
226
227       shell  Overrides the shell detected from the shebang.  This  is  useful
228              for  files meant to be included (and thus lacking a shebang), or
229              possibly as a more targeted alternative to 'disable=SC2039'.
230

RC FILES

232       Unless --norc is used, ShellCheck will look for a file .shellcheckrc or
233       shellcheckrc  in  the script's directory and each parent directory.  If
234       found, it will read key=value pairs from it and treat them as file-wide
235       directives.
236
237       Here is an example .shellcheckrc:
238
239              # Look for 'source'd files relative to the checked script,
240              # and also look for absolute paths in /mnt/chroot
241              source-path=SCRIPTDIR
242              source-path=/mnt/chroot
243
244              # Turn on warnings for unquoted variables with safe values
245              enable=quote-safe-variables
246
247              # Turn on warnings for unassigned uppercase variables
248              enable=check-unassigned-uppercase
249
250              # Allow [ ! -z foo ] instead of suggesting -n
251              disable=SC2236
252
253       If  no  .shellcheckrc  is  found  in  any  of  the  parent directories,
254       ShellCheck will look in ~/.shellcheckrc followed by the XDG config  di‐
255       rectory   (usually   ~/.config/shellcheckrc)   on   Unix,   or  %APPDA‐
256       TA%/shellcheckrc on Windows.  Only the first file found will be used.
257
258       Note for Snap users: the Snap sandbox disallows access to hidden files.
259       Use shellcheckrc without the dot instead.
260
261       Note  for  Docker users: ShellCheck will only be able to look for files
262       that are mounted in the container, so ~/.shellcheckrc will not be read.
263

ENVIRONMENT VARIABLES

265       The environment variable SHELLCHECK_OPTS can be set with default flags:
266
267              export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'
268
269       Its value will be split on spaces and prepended to the command line  on
270       each invocation.
271

RETURN VALUES

273       ShellCheck uses the following exit codes:
274
275       • 0: All files successfully scanned with no issues.
276
277       • 1: All files successfully scanned with some issues.
278
279       • 2: Some files could not be processed (e.g.  file not found).
280
281       • 3: ShellCheck was invoked with bad syntax (e.g.  unknown flag).
282
283       • 4: ShellCheck was invoked with bad options (e.g.  unknown formatter).
284

LOCALE

286       This version of ShellCheck is only available in English.  All files are
287       leniently decoded as UTF-8, with a fallback of ISO-8859-1  for  invalid
288       sequences.  LC_CTYPE is respected for output, and defaults to UTF-8 for
289       locales where encoding is unspecified (such as the C locale).
290
291       Windows users seeing commitBuffer: invalid argument (invalid character)
292       should set their terminal to use UTF-8 with chcp 65001.
293

AUTHORS

295       ShellCheck  is developed and maintained by Vidar Holen, with assistance
296       from a long list of wonderful contributors.
297

REPORTING BUGS

299       Bugs and issues can be reported on GitHub:
300
301       https://github.com/koalaman/shellcheck/issues
302
304       Copyright 2012-2019, Vidar Holen and contributors.  Licensed under  the
305       GNU  General Public License version 3 or later, see https://gnu.org/li
306       censes/gpl.html
307

SEE ALSO

309       sh(1) bash(1)
310
311
312
313Shell script analysis tool                                       SHELLCHECK(1)
Impressum