shellcheck(1)

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 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       -e CODE1[,CODE2...], --exclude=CODE1[,CODE2...]
45              Explicitly exclude the specified codes from the report.   Subse‐
46              quent -e options are cumulative, but all the codes can be speci‐
47              fied at once, comma-separated as a single argument.
48
49       -f FORMAT, --format=FORMAT
50              Specify the output format of shellcheck, which  prints  its  re‐
51              sults  in  the  standard  output.  Subsequent -f options are ig‐
52              nored, see FORMATS below for more information.
53
54       -S SEVERITY, --severity=severity
55              Specify minimum severity of errors to  consider.   Valid  values
56              are error, warning, info and style.  The default is style.
57
58       -s shell, --shell=shell
59              Specify  Bourne  shell dialect.  Valid values are sh, bash, dash
60              and ksh.  The default is to use the file's shebang, or  bash  if
61              the target shell can't be determined.
62
63       -V, --version
64              Print version information and exit.
65
66       -W NUM, --wiki-link-count=NUM
67              For  TTY  output,  show NUM wiki links to more information about
68              mentioned warnings.  Set to 0 to disable them entirely.
69
70       -x, --external-sources
71              Follow 'source' statements even when the file is  not  specified
72              as  input.  By default, shellcheck will only follow files speci‐
73              fied on the command line (plus /dev/null).  This  option  allows
74              following any file the script may source.
75

FORMATS

77       tty    Plain text, human readable output.  This is the default.
78
79       gcc    GCC  compatible output.  Useful for editors that support compil‐
80              ing and showing syntax errors.
81
82              For example, in  Vim,  :set makeprg=shellcheck\ -f\ gcc\ %  will
83              allow using :make to check the script, and :cnext to jump to the
84              next error.
85
86                     <file>:<line>:<column>: <type>: <message>
87
88       checkstyle
89              Checkstyle compatible XML output.  Supported directly or through
90              plugins by many IDEs and build monitoring systems.
91
92                     <?xml version='1.0' encoding='UTF-8'?>
93                     <checkstyle version='4.3'>
94                       <file name='file'>
95                         <error
96                           line='line'
97                           column='column'
98                           severity='severity'
99                           message='message'
100                           source='ShellCheck.SC####' />
101                         ...
102                       </file>
103                       ...
104                     </checkstyle>
105
106       json   Json is a popular serialization format that is more suitable for
107              web applications.  ShellCheck's json is compact and contains on‐
108              ly the bare minimum.
109
110                     [
111                       {
112                         "file": "filename",
113                         "line": lineNumber,
114                         "column": columnNumber,
115                         "level": "severitylevel",
116                         "code": errorCode,
117                         "message": "warning message"
118                       },
119                       ...
120                     ]
121

DIRECTIVES

123       ShellCheck  directives can be specified as comments in the shell script
124       before a command or block:
125
126              # shellcheck key=value key=value
127              command-or-structure
128
129       For example, to suppress SC2035 about using ./*.jpg:
130
131              # shellcheck disable=SC2035
132              echo "Files: " *.jpg
133
134       To tell ShellCheck where to look for an  otherwise  dynamically  deter‐
135       mined file:
136
137              # shellcheck source=./lib.sh
138              source "$(find_install_dir)/lib.sh"
139
140       Here  a  shell  brace  group  is used to suppress a warning on multiple
141       lines:
142
143              # shellcheck disable=SC2016
144              {
145                echo 'Modifying $PATH'
146                echo 'PATH=foo:$PATH' >> ~/.bashrc
147              }
148
149       Valid keys are:
150
151       disable
152              Disables a comma separated list of error codes for the following
153              command.   The command can be a simple command like echo foo, or
154              a compound command like a function definition, subshell block or
155              loop.
156
157       source Overrides  the filename included by a source/.  statement.  This
158              can be used to tell shellcheck where to look for  a  file  whose
159              name is determined at runtime, or to skip a source by telling it
160              to use /dev/null.
161
162       shell  Overrides the shell detected from the shebang.  This  is  useful
163              for  files meant to be included (and thus lacking a shebang), or
164              possibly as a more targeted alternative to 'disable=2039'.
165

ENVIRONMENT VARIABLES

167       The environment variable SHELLCHECK_OPTS can be set with default flags:
168
169              export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'
170
171       Its value will be split on spaces and prepended to the command line  on
172       each invocation.
173

RETURN VALUES

175       ShellCheck uses the follow exit codes:
176
177       · 0: All files successfully scanned with no issues.
178
179       · 1: All files successfully scanned with some issues.
180
181       · 2: Some files could not be processed (e.g.  file not found).
182
183       · 3: ShellCheck was invoked with bad syntax (e.g.  unknown flag).
184
185       · 4: ShellCheck was invoked with bad options (e.g.  unknown formatter).
186

LOCALE

188       This version of ShellCheck is only available in English.  All files are
189       leniently decoded as UTF-8, with a fallback of ISO-8859-1  for  invalid
190       sequences.  LC_CTYPE is respected for output, and defaults to UTF-8 for
191       locales where encoding is unspecified (such as the C locale).
192
193       Windows users seeing commitBuffer: invalid argument (invalid character)
194       should set their terminal to use UTF-8 with chcp 65001.
195

AUTHOR

197       ShellCheck is written and maintained by Vidar Holen.
198

REPORTING BUGS

200       Bugs and issues can be reported on GitHub:
201
202       https://github.com/koalaman/shellcheck/issues
203

COPYRIGHT

205       Copyright  2012-2015, Vidar Holen.  Licensed under the GNU General Pub‐
206       lic License version 3 or later, see https://gnu.org/licenses/gpl.html
207