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
74              search-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
97              as input.  By default, shellcheck will only follow files  speci‐
98              fied  on  the command line (plus /dev/null).  This option allows
99              following 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.
208
209       enable Enable  an optional check by name, as listed with --list-option‐
210              al.  Only file-wide enable directives are considered.
211
212       source Overrides the filename included by a source/.  statement.   This
213              can  be  used  to tell shellcheck where to look for a file whose
214              name is determined at runtime, or to skip a source by telling it
215              to use /dev/null.
216
217       source-path
218              Add  a directory to the search path for source/.  statements (by
219              default, only ShellCheck's working directory is included).   Ab‐
220              solute  paths  will  also be rooted in these paths.  The special
221              path SCRIPTDIR can be used  to  specify  the  currently  checked
222              script's    directory,    as    in    source-path=SCRIPTDIR   or
223              source-path=SCRIPTDIR/../libs.  Multiple paths  accumulate,  and
224              -P takes precedence over them.
225
226       shell  Overrides  the  shell detected from the shebang.  This is useful
227              for files meant to be included (and thus lacking a shebang),  or
228              possibly as a more targeted alternative to 'disable=2039'.
229

RC FILES

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

ENVIRONMENT VARIABLES

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

RETURN VALUES

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

LOCALE

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

AUTHORS

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

REPORTING BUGS

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

SEE ALSO

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