View | Details | Raw Unified | Return to bug 228674
Collapse All | Expand All

(-)Makefile (+5 lines)
Lines 19-23 Link Here
19
19
20
EXECUTABLE=	shellcheck
20
EXECUTABLE=	shellcheck
21
21
22
PLIST_FILES+=	man/man1/shellcheck.1.gz
23
24
post-stage:
25
		${INSTALL_MAN} ${FILESDIR}/shellcheck.1 ${STAGEDIR}${MANPREFIX}/man/man1/
26
22
.include "${.CURDIR}/../../lang/ghc/bsd.cabal.mk"
27
.include "${.CURDIR}/../../lang/ghc/bsd.cabal.mk"
23
.include <bsd.port.mk>
28
.include <bsd.port.mk>
(-)files/shellcheck.1 (+277 lines)
Line 0 Link Here
1
.Dd May 15, 2018
2
.Dt SHELLCHECK 1
3
.Os
4
.Sh NAME
5
.Nm shellcheck
6
.Nd Shell script analysis tool
7
.Sh SYNOPSIS
8
.Nm
9
.Op Fl avx,
10
.Op Fl C Ar when
11
.Op Fl e Ar code1,code2
12
.Op Fl f Ar format
13
.Op Fl s Ar shell
14
.Sh DESCRIPTION
15
.Nm
16
is a static analysis and linting tool for sh/bash scripts.
17
It is mainly focused on handling typical beginner and intermediate
18
level syntax errors and pitfalls where the shell just gives a cryptic
19
error message or strange behavior, but it also reports on a few more
20
advanced issues where corner cases can cause delayed failures.
21
.Pp
22
.Nm
23
gives shell specific advice.
24
Consider this line:
25
.Bd -literal -offset indent
26
(( area = 3.14*r*r ))
27
.Ed
28
.Pp
29
For scripts starting with
30
.Li #!/bin/sh
31
(or when using
32
.Fl s Cm sh ) ,
33
.Nm
34
will warn that
35
.Li ((\ ..\ ))
36
is not POSIX compliant (similar to
37
.Li checkbashisms ) .
38
.Pp
39
For scripts starting with
40
.Li #!/bin/bash
41
(or using
42
.Fl s Cm bash ) ,
43
.Nm
44
will warn that decimals are not supported.
45
.Pp
46
For scripts starting with
47
.Li #!/bin/ksh
48
(or using
49
.Fl s Cm ksh ) ,
50
.nm
51
will not warn at all, as
52
.Li ksh
53
supports decimals in arithmetic contexts.
54
.Sh OPTIONS
55
The following options are available:
56
.Bl -tag -width indent
57
.It Fl a , -check-sourced
58
Emit warnings in sourced files.
59
Normally,
60
.Nm
61
will only warn about issues in the specified files.
62
With this option, any issues in sourced files will also be reported.
63
.It Fl C  Ar when , Fl -color Ns = Ns Ar when
64
For TTY output, enable colors with when one of
65
.Li always ,
66
.Li never ,
67
or
68
.Li auto .
69
The default is
70
.Li auto .
71
.Ar -color
72
without an argument is equivalent to
73
.Ar -color=always .
74
.It Fl e Ar code1,code2 , Fl -exclude Ns = Ns Ar code1,code2
75
Explicitly exclude the specified codes from the report.
76
Subsequent
77
.Fl e
78
options are cumulative, but all the codes can be
79
specified at once, comma\-separated as a single argument.
80
.It Fl f Ar format , Fl -format Ns = Ns Ar format
81
Specify the output format of
82
.Nm ,
83
which prints its results in the
84
standard output.
85
Subsequent
86
.Fl f
87
options are ignored, see
88
.Rx FORMATS
89
below for more information.
90
.It Fl s Ar shell , Fl -shell Ns = Ns Ar shell
91
Specify Bourne shell dialect.
92
Valid values are
93
.Ar sh , bash , dash ,
94
and
95
.Ar ksh .
96
The default is to use the file's shebang, or
97
.Ar bash
98
if the target shell cannot be determined.
99
.It Fl V , Fl -version
100
Print version information and exit.
101
.It Fl x , Fl -external-sources
102
Follow
103
.Li source
104
statements even when the file is not specified as input.
105
By default,
106
.Nm
107
will only follow files specified on the command line (plus
108
.Pa /dev/null ) .
109
This option allows following any file the script may
110
.Li source .
111
.El
112
.Sh FORMATS
113
.Bl -tag -width indent
114
.It tty
115
Plain text, human readable output.
116
This is the default.
117
.It gcc
118
GCC compatible output.
119
Useful for editors that support compiling and showing syntax errors.
120
.Pp
121
For example, in
122
.Li vim ,
123
.Li :set makeprg=shellcheck -f gcc %
124
will allow using
125
.Li :make
126
to check the script, and
127
.Li :cnext
128
to jump to the next error.
129
.Bd -literal -offset indent
130
<file>:<line>:<column>:\ <type>:\ <message>
131
.Ed
132
.It checkstyle
133
Checkstyle compatible XML output.
134
Supported directly or through plugins by many IDEs and build monitoring
135
systems.
136
.Bd -literal -offset indent
137
<?xml\ version="1.0" encoding="UTF-8?">
138
<checkstyle\ version="4.3"\>
139
  <file name="file">
140
    <error
141
      line="line"
142
      column="column"
143
      severity="severity"
144
      message="message"
145
      source="ShellCheck.SC####" />
146
    ...
147
  </file>
148
  ...
149
</checkstyle>
150
.Ed
151
.It json
152
Json is a popular serialization format that is more suitable for web
153
applications.
154
.Nm Ns 's
155
json is compact and contains only the bare minimum.
156
.Bd -literal -offset indent
157
[
158
  {
159
    "file": "filename",
160
    "line": lineNumber,
161
    "column": columnNumber,
162
    "level": "severitylevel",
163
    "code": errorCode,
164
    "message": "warning message"
165
  },
166
  ...
167
]
168
.Sh DIRECTIVES
169
.Nm
170
directives can be specified as comments in the shell script
171
before a command or block:
172
.Bd -literal -offset indent
173
# shellcheck key=value key=value
174
command-or-structure
175
.Ed
176
177
For example, to suppress SC2035 about using
178
.Li ./*.jpg :
179
.Bd -literal -offset indent
180
# shellcheck disable=SC2035
181
echo "Files: " *.jpg
182
.Ed
183
184
To tell
185
.Nm
186
where to look for an otherwise dynamically determined
187
file:
188
.Bd .Bd -literal -offset indent
189
# shellcheck\ source=./lib.sh
190
source "$(find_install_dir)/lib.sh"
191
.Ed
192
193
Here a shell brace group is used to suppress a warning on multiple
194
lines:
195
.Bd -literal -offset indent
196
# shellcheck\ disable=SC2016
197
{
198
  echo "Modifying $PATH"
199
  echo "PATH=foo:$PATH" >> ~/.bashrc
200
}
201
.Ed
202
.El
203
Valid keys are:
204
.Bl -tag -width indent
205
.It disable
206
Disables a comma separated list of error codes for the following
207
command.
208
The command can be a simple command like
209
.Li echo ,
210
or a compound command like a function definition, subshell block or loop.
211
.It source
212
Overrides the filename included by a
213
.Li source
214
statement.
215
This can be used to tell
216
.Nm
217
where to look for a file whose name
218
is determined at runtime, or to skip a source by telling it to use
219
.Pa /dev/null .
220
.It shell
221
Overrides the shell detected from the shebang.
222
This is useful for files meant to be included (and thus lacking a
223
shebang), or possibly as a more targeted alternative to
224
.Li "disable=2039" .
225
.Sh ENVIRONMENT VARIABLES
226
The environment variable
227
.Ev SHELLCHECK_OPTS
228
can be set with default flags:
229
.Bd -literal -offset indent
230
export SHELLCHECK_OPTS="--shell=bash --exclude=SC2016"
231
.Ed
232
233
Its value will be split on spaces and prepended to the command line on
234
each invocation.
235
.El
236
.Sh EXIT STATUS
237
.Nm
238
uses the follow exit codes:
239
.Bl -tag -width indent
240
.It 0 :
241
All files successfully scanned with no issues.
242
.It 1 :
243
All files successfully scanned with some issues.
244
.It 2 :
245
Some files could not be processed (e.g., file not found).
246
.It 3 :
247
.Nm
248
was invoked with bad syntax (e.g., unknown flag).
249
.It 4 :
250
.Nm
251
was invoked with bad options (e.g., unknown formatter).
252
.El
253
.Sh LOCALE
254
This version of
255
.Nm
256
is only available in English.
257
All files are leniently decoded as UTF\-8, with a fallback of
258
ISO\-8859\-1 for invalid sequences.
259
.Ev LC_CTYPE
260
is respected for output, and defaults to UTF\-8 for locales where encoding
261
is unspecified (such as the
262
.Li C
263
locale).
264
.Sh AUTHOR
265
.Nm
266
is written and maintained by Vidar Holen.
267
.Sh REPORTING BUGS
268
Bugs and issues can be reported on GitHub:
269
.Pp
270
.Lk https://github.com/koalaman/shellcheck/issues
271
.Sh COPYRIGHT
272
Copyright 2012\-2015, Vidar Holen.
273
Licensed under the GNU General Public License version 3 or later, see
274
http://gnu.org/licenses/gpl.html
275
.Sh SEE ALSO
276
.Xr bash 1 ,
277
.Xr sh 1

Return to bug 228674