diff options
Diffstat (limited to 'development/ShellCheck-bin/shellcheck.1')
| -rw-r--r-- | development/ShellCheck-bin/shellcheck.1 | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/development/ShellCheck-bin/shellcheck.1 b/development/ShellCheck-bin/shellcheck.1 new file mode 100644 index 0000000000..b98de14a65 --- /dev/null +++ b/development/ShellCheck-bin/shellcheck.1 @@ -0,0 +1,400 @@ +.\" Automatically generated by Pandoc 2.5 +.\" +.TH "SHELLCHECK" "1" "" "Shell script analysis tool" "" +.hy +.SH NAME +.PP +shellcheck \- Shell script analysis tool +.SH SYNOPSIS +.PP +\f[B]shellcheck\f[R] [\f[I]OPTIONS\f[R]\&...] \f[I]FILES\f[R]\&... +.SH DESCRIPTION +.PP +ShellCheck is a static analysis and linting tool for sh/bash scripts. +It\[cq]s mainly focused on handling typical beginner and intermediate +level syntax errors and pitfalls where the shell just gives a cryptic +error message or strange behavior, but it also reports on a few more +advanced issues where corner cases can cause delayed failures. +.PP +ShellCheck gives shell specific advice. +Consider this line: +.IP +.nf +\f[C] +(( area = 3.14*r*r )) +\f[R] +.fi +.IP \[bu] 2 +For scripts starting with \f[C]#!/bin/sh\f[R] (or when using +\f[C]\-s sh\f[R]), ShellCheck will warn that \f[C](( .. ))\f[R] is not +POSIX compliant (similar to checkbashisms). +.IP \[bu] 2 +For scripts starting with \f[C]#!/bin/bash\f[R] (or using +\f[C]\-s bash\f[R]), ShellCheck will warn that decimals are not +supported. +.IP \[bu] 2 +For scripts starting with \f[C]#!/bin/ksh\f[R] (or using +\f[C]\-s ksh\f[R]), ShellCheck will not warn at all, as \f[C]ksh\f[R] +supports decimals in arithmetic contexts. +.SH OPTIONS +.TP +.B \f[B]\-a\f[R],\ \f[B]\[en]check\-sourced\f[R] +Emit warnings in sourced files. +Normally, \f[C]shellcheck\f[R] will only warn about issues in the +specified files. +With this option, any issues in sourced files will also be reported. +.TP +.B \f[B]\-C\f[R][\f[I]WHEN\f[R]],\ \f[B]\[en]color\f[R][=\f[I]WHEN\f[R]] +For TTY output, enable colors \f[I]always\f[R], \f[I]never\f[R] or +\f[I]auto\f[R]. +The default is \f[I]auto\f[R]. +\f[B]\[en]color\f[R] without an argument is equivalent to +\f[B]\[en]color=always\f[R]. +.TP +.B \f[B]\-i\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]\&...],\ \f[B]\[en]include=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]\&...] +Explicitly include only the specified codes in the report. +Subsequent \f[B]\-i\f[R] options are cumulative, but all the codes can +be specified at once, comma\-separated as a single argument. +Include options override any provided exclude options. +.TP +.B \f[B]\-e\f[R]\ \f[I]CODE1\f[R][,\f[I]CODE2\f[R]\&...],\ \f[B]\[en]exclude=\f[R]\f[I]CODE1\f[R][,\f[I]CODE2\f[R]\&...] +Explicitly exclude the specified codes from the report. +Subsequent \f[B]\-e\f[R] options are cumulative, but all the codes can +be specified at once, comma\-separated as a single argument. +.TP +.B \f[B]\-f\f[R] \f[I]FORMAT\f[R], \f[B]\[en]format=\f[R]\f[I]FORMAT\f[R] +Specify the output format of shellcheck, which prints its results in the +standard output. +Subsequent \f[B]\-f\f[R] options are ignored, see \f[B]FORMATS\f[R] +below for more information. +.TP +.B \f[B]\[en]list\-optional\f[R] +Output a list of known optional checks. +These can be enabled with \f[B]\-o\f[R] flags or \f[B]enable\f[R] +directives. +.TP +.B \f[B]\[en]norc\f[R] +Don\[cq]t try to look for .shellcheckrc configuration files. +.TP +.B \f[B]\-o\f[R]\ \f[I]NAME1\f[R][,\f[I]NAME2\f[R]\&...],\ \f[B]\[en]enable=\f[R]\f[I]NAME1\f[R][,\f[I]NAME2\f[R]\&...] +Enable optional checks. +The special name \f[I]all\f[R] enables all of them. +Subsequent \f[B]\-o\f[R] options accumulate. +This is equivalent to specifying \f[B]enable\f[R] directives. +.TP +.B \f[B]\-P\f[R]\ \f[I]SOURCEPATH\f[R],\ \f[B]\[en]source\-path=\f[R]\f[I]SOURCEPATH\f[R] +Specify paths to search for sourced files, separated by \f[C]:\f[R] on +Unix and \f[C];\f[R] on Windows. +This is equivalent to specifying \f[C]search\-path\f[R] directives. +.TP +.B \f[B]\-s\f[R]\ \f[I]shell\f[R],\ \f[B]\[en]shell=\f[R]\f[I]shell\f[R] +Specify Bourne shell dialect. +Valid values are \f[I]sh\f[R], \f[I]bash\f[R], \f[I]dash\f[R] and +\f[I]ksh\f[R]. +The default is to deduce the shell from the file\[cq]s \f[C]shell\f[R] +directive, shebang, or \f[C].bash/.bats/.dash/.ksh\f[R] extension, in +that order. +\f[I]sh\f[R] refers to POSIX \f[C]sh\f[R] (not the system\[cq]s), and +will warn of portability issues. +.TP +.B \f[B]\-S\f[R]\ \f[I]SEVERITY\f[R],\ \f[B]\[en]severity=\f[R]\f[I]severity\f[R] +Specify minimum severity of errors to consider. +Valid values in order of severity are \f[I]error\f[R], +\f[I]warning\f[R], \f[I]info\f[R] and \f[I]style\f[R]. +The default is \f[I]style\f[R]. +.TP +.B \f[B]\-V\f[R],\ \f[B]\[en]version\f[R] +Print version information and exit. +.TP +.B \f[B]\-W\f[R] \f[I]NUM\f[R],\ \f[B]\[en]wiki\-link\-count=NUM\f[R] +For TTY output, show \f[I]NUM\f[R] wiki links to more information about +mentioned warnings. +Set to 0 to disable them entirely. +.TP +.B \f[B]\-x\f[R],\ \f[B]\[en]external\-sources\f[R] +Follow \f[C]source\f[R] statements even when the file is not specified +as input. +By default, \f[C]shellcheck\f[R] will only follow files specified on the +command line (plus \f[C]/dev/null\f[R]). +This option allows following any file the script may \f[C]source\f[R]. +.TP +.B \f[B]FILES\&...\f[R] +One or more script files to check, or \[lq]\-\[rq] for standard input. +.SH FORMATS +.TP +.B \f[B]tty\f[R] +Plain text, human readable output. +This is the default. +.TP +.B \f[B]gcc\f[R] +GCC compatible output. +Useful for editors that support compiling and showing syntax errors. +.RS +.PP +For example, in Vim, +\f[C]:set makeprg=shellcheck\[rs] \-f\[rs] gcc\[rs] %\f[R] will allow +using \f[C]:make\f[R] to check the script, and \f[C]:cnext\f[R] to jump +to the next error. +.IP +.nf +\f[C] +<file>:<line>:<column>: <type>: <message> +\f[R] +.fi +.RE +.TP +.B \f[B]checkstyle\f[R] +Checkstyle compatible XML output. +Supported directly or through plugins by many IDEs and build monitoring +systems. +.RS +.IP +.nf +\f[C] +<?xml version=\[aq]1.0\[aq] encoding=\[aq]UTF\-8\[aq]?> +<checkstyle version=\[aq]4.3\[aq]> + <file name=\[aq]file\[aq]> + <error + line=\[aq]line\[aq] + column=\[aq]column\[aq] + severity=\[aq]severity\[aq] + message=\[aq]message\[aq] + source=\[aq]ShellCheck.SC####\[aq] /> + ... + </file> + ... +</checkstyle> +\f[R] +.fi +.RE +.TP +.B \f[B]diff\f[R] +Auto\-fixes in unified diff format. +Can be piped to \f[C]git apply\f[R] or \f[C]patch \-p1\f[R] to +automatically apply fixes. +.RS +.IP +.nf +\f[C] +\-\-\- a/test.sh ++++ b/test.sh +\[at]\[at] \-2,6 +2,6 \[at]\[at] + ## Example of a broken script. + for f in $(ls *.m3u) + do +\- grep \-qi hq.*mp3 $f \[rs] ++ grep \-qi hq.*mp3 \[dq]$f\[dq] \[rs] + && echo \-e \[aq]Playlist $f contains a HQ file in mp3 format\[aq] + done +\f[R] +.fi +.RE +.TP +.B \f[B]json1\f[R] +Json is a popular serialization format that is more suitable for web +applications. +ShellCheck\[cq]s json is compact and contains only the bare minimum. +Tabs are counted as 1 character. +.RS +.IP +.nf +\f[C] +{ + comments: [ + { + \[dq]file\[dq]: \[dq]filename\[dq], + \[dq]line\[dq]: lineNumber, + \[dq]column\[dq]: columnNumber, + \[dq]level\[dq]: \[dq]severitylevel\[dq], + \[dq]code\[dq]: errorCode, + \[dq]message\[dq]: \[dq]warning message\[dq] + }, + ... + ] +} +\f[R] +.fi +.RE +.TP +.B \f[B]json\f[R] +This is a legacy version of the \f[B]json1\f[R] format. +It\[cq]s a raw array of comments, and all offsets have a tab stop of 8. +.TP +.B \f[B]quiet\f[R] +Suppress all normal output. +Exit with zero if no issues are found, otherwise exit with one. +Stops processing after the first issue. +.SH DIRECTIVES +.PP +ShellCheck directives can be specified as comments in the shell script. +If they appear before the first command, they are considered file\-wide. +Otherwise, they apply to the immediately following command or block: +.IP +.nf +\f[C] +# shellcheck key=value key=value +command\-or\-structure +\f[R] +.fi +.PP +For example, to suppress SC2035 about using \f[C]./*.jpg\f[R]: +.IP +.nf +\f[C] +# shellcheck disable=SC2035 +echo \[dq]Files: \[dq] *.jpg +\f[R] +.fi +.PP +To tell ShellCheck where to look for an otherwise dynamically determined +file: +.IP +.nf +\f[C] +# shellcheck source=./lib.sh +source \[dq]$(find_install_dir)/lib.sh\[dq] +\f[R] +.fi +.PP +Here a shell brace group is used to suppress a warning on multiple +lines: +.IP +.nf +\f[C] +# shellcheck disable=SC2016 +{ + echo \[aq]Modifying $PATH\[aq] + echo \[aq]PATH=foo:$PATH\[aq] >> \[ti]/.bashrc +} +\f[R] +.fi +.PP +Valid keys are: +.TP +.B \f[B]disable\f[R] +Disables a comma separated list of error codes for the following +command. +The command can be a simple command like \f[C]echo foo\f[R], or a +compound command like a function definition, subshell block or loop. +.TP +.B \f[B]enable\f[R] +Enable an optional check by name, as listed with +\f[B]\[en]list\-optional\f[R]. +Only file\-wide \f[C]enable\f[R] directives are considered. +.TP +.B \f[B]source\f[R] +Overrides the filename included by a \f[C]source\f[R]/\f[C].\f[R] +statement. +This can be used to tell shellcheck where to look for a file whose name +is determined at runtime, or to skip a source by telling it to use +\f[C]/dev/null\f[R]. +.TP +.B \f[B]source\-path\f[R] +Add a directory to the search path for \f[C]source\f[R]/\f[C].\f[R] +statements (by default, only ShellCheck\[cq]s working directory is +included). +Absolute paths will also be rooted in these paths. +The special path \f[C]SCRIPTDIR\f[R] can be used to specify the +currently checked script\[cq]s directory, as in +\f[C]source\-path=SCRIPTDIR\f[R] or +\f[C]source\-path=SCRIPTDIR/../libs\f[R]. +Multiple paths accumulate, and \f[C]\-P\f[R] takes precedence over them. +.TP +.B \f[B]shell\f[R] +Overrides the shell detected from the shebang. +This is useful for files meant to be included (and thus lacking a +shebang), or possibly as a more targeted alternative to `disable=2039'. +.SH RC FILES +.PP +Unless \f[C]\-\-norc\f[R] is used, ShellCheck will look for a file +\f[C].shellcheckrc\f[R] or \f[C]shellcheckrc\f[R] in the script\[cq]s +directory and each parent directory. +If found, it will read \f[C]key=value\f[R] pairs from it and treat them +as file\-wide directives. +.PP +Here is an example \f[C].shellcheckrc\f[R]: +.IP +.nf +\f[C] +# Look for \[aq]source\[aq]d files relative to the checked script, +# and also look for absolute paths in /mnt/chroot +source\-path=SCRIPTDIR +source\-path=/mnt/chroot + +# Turn on warnings for unquoted variables with safe values +enable=quote\-safe\-variables + +# Turn on warnings for unassigned uppercase variables +enable=check\-unassigned\-uppercase + +# Allow [ ! \-z foo ] instead of suggesting \-n +disable=SC2236 +\f[R] +.fi +.PP +If no \f[C].shellcheckrc\f[R] is found in any of the parent directories, +ShellCheck will look in \f[C]\[ti]/.shellcheckrc\f[R] followed by the +XDG config directory (usually \f[C]\[ti]/.config/shellcheckrc\f[R]) on +Unix, or \f[C]%APPDATA%/shellcheckrc\f[R] on Windows. +Only the first file found will be used. +.PP +Note for Snap users: the Snap sandbox disallows access to hidden files. +Use \f[C]shellcheckrc\f[R] without the dot instead. +.PP +Note for Docker users: ShellCheck will only be able to look for files +that are mounted in the container, so \f[C]\[ti]/.shellcheckrc\f[R] will +not be read. +.SH ENVIRONMENT VARIABLES +.PP +The environment variable \f[C]SHELLCHECK_OPTS\f[R] can be set with +default flags: +.IP +.nf +\f[C] +export SHELLCHECK_OPTS=\[aq]\-\-shell=bash \-\-exclude=SC2016\[aq] +\f[R] +.fi +.PP +Its value will be split on spaces and prepended to the command line on +each invocation. +.SH RETURN VALUES +.PP +ShellCheck uses the following exit codes: +.IP \[bu] 2 +0: All files successfully scanned with no issues. +.IP \[bu] 2 +1: All files successfully scanned with some issues. +.IP \[bu] 2 +2: Some files could not be processed (e.g.\ file not found). +.IP \[bu] 2 +3: ShellCheck was invoked with bad syntax (e.g.\ unknown flag). +.IP \[bu] 2 +4: ShellCheck was invoked with bad options (e.g.\ unknown formatter). +.SH LOCALE +.PP +This version of ShellCheck is only available in English. +All files are leniently decoded as UTF\-8, with a fallback of +ISO\-8859\-1 for invalid sequences. +\f[C]LC_CTYPE\f[R] is respected for output, and defaults to UTF\-8 for +locales where encoding is unspecified (such as the \f[C]C\f[R] locale). +.PP +Windows users seeing +\f[C]commitBuffer: invalid argument (invalid character)\f[R] should set +their terminal to use UTF\-8 with \f[C]chcp 65001\f[R]. +.SH AUTHORS +.PP +ShellCheck is developed and maintained by Vidar Holen, with assistance +from a long list of wonderful contributors. +.SH REPORTING BUGS +.PP +Bugs and issues can be reported on GitHub: +.PP +https://github.com/koalaman/shellcheck/issues +.SH COPYRIGHT +.PP +Copyright 2012\-2019, Vidar Holen and contributors. +Licensed under the GNU General Public License version 3 or later, see +https://gnu.org/licenses/gpl.html +.SH SEE ALSO +.PP +sh(1) bash(1) |