shellcheck/shellcheck.1.md

% SHELLCHECK(1) Shell script analysis tool

# NAME

shellcheck - Shell script analysis tool

# SYNOPSIS

**shellcheck** [*OPTIONS*...] *FILES*...

# DESCRIPTION

ShellCheck is a static analysis and linting tool for sh/bash scripts. It'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.

ShellCheck gives shell specific advice. Consider this line:

    (( area = 3.14*r*r ))

+ For scripts starting with `#!/bin/sh` (or when using `-s sh`), ShellCheck
will warn that `(( .. ))` is not POSIX compliant (similar to checkbashisms).

+ For scripts starting with `#!/bin/bash` (or using `-s bash`), ShellCheck
will warn that decimals are not supported.

+ For scripts starting with `#!/bin/ksh` (or using `-s ksh`), ShellCheck will
not warn at all, as `ksh` supports decimals in arithmetic contexts.

# OPTIONS

**-a**,\ **--check-sourced**

:   Emit warnings in sourced files. Normally, `shellcheck` will only warn
    about issues in the specified files. With this option, any issues in
    sourced files will also be reported.

**-C**[*WHEN*],\ **--color**[=*WHEN*]

:   For TTY output, enable colors *always*, *never* or *auto*. The default
    is *auto*. **--color** without an argument is equivalent to
    **--color=always**.

**-i**\ *CODE1*[,*CODE2*...],\ **--include=***CODE1*[,*CODE2*...]

:   Explicitly include only the specified codes in the report. Subsequent **-i**
    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.

**-e**\ *CODE1*[,*CODE2*...],\ **--exclude=***CODE1*[,*CODE2*...]

:   Explicitly exclude the specified codes from the report. Subsequent **-e**
    options are cumulative, but all the codes can be specified at once,
    comma-separated as a single argument.

**-f** *FORMAT*, **--format=***FORMAT*

:   Specify the output format of shellcheck, which prints its results in the
    standard output. Subsequent **-f** options are ignored, see **FORMATS**
    below for more information.

**--list-optional**

:   Output a list of known optional checks. These can be enabled with **-o**
    flags or **enable** directives.

**--norc**

:   Don't try to look for .shellcheckrc configuration files.

**-o**\ *NAME1*[,*NAME2*...],\ **--enable=***NAME1*[,*NAME2*...]

:   Enable optional checks. The special name *all* enables all of them.
    Subsequent **-o** options accumulate. This is equivalent to specifying
    **enable** directives.

**-P**\ *SOURCEPATH*,\ **--source-path=***SOURCEPATH*

:   Specify paths to search for sourced files, separated by `:` on Unix and
    `;` on Windows. This is equivalent to specifying `search-path`
    directives.

**-s**\ *shell*,\ **--shell=***shell*

:   Specify Bourne shell dialect. Valid values are *sh*, *bash*, *dash* and *ksh*.
    The default is to deduce the shell from the file's `shell` directive,
    shebang, or `.bash/.bats/.dash/.ksh/.ebuild/.eclass` extension, in that
    order. *sh* refers to POSIX `sh` (not the system's), and will warn of
    portability issues.

**-S**\ *SEVERITY*,\ **--severity=***severity*

:   Specify minimum severity of errors to consider. Valid values in order of
    severity are *error*, *warning*, *info* and *style*.
    The default is *style*.

**-V**,\ **--version**

:   Print version information and exit.

**-W** *NUM*,\ **--wiki-link-count=NUM**

:   For TTY output, show *NUM* wiki links to more information about mentioned
    warnings. Set to 0 to disable them entirely.

**-x**,\ **--external-sources**

:   Follow `source` statements even when the file is not specified as input.
    By default, `shellcheck` will only follow files specified on the command
    line (plus `/dev/null`). This option allows following any file the script
    may `source`.

    This option may also be enabled using `external-sources=true` in
    `.shellcheckrc`. This flag takes precedence.

**FILES...**

:   One or more script files to check, or "-" for standard input.


# FORMATS

**tty**

:   Plain text, human readable output. This is the default.

**gcc**

:   GCC compatible output. Useful for editors that support compiling and
    showing syntax errors.

    For example, in Vim, `:set makeprg=shellcheck\ -f\ gcc\ %` will allow
    using `:make` to check the script, and `:cnext` to jump to the next error.

        <file>:<line>:<column>: <type>: <message>

**checkstyle**

:   Checkstyle compatible XML output. Supported directly or through plugins
    by many IDEs and build monitoring systems.

        <?xml version='1.0' encoding='UTF-8'?>
        <checkstyle version='4.3'>
          <file name='file'>
            <error
              line='line'
              column='column'
              severity='severity'
              message='message'
              source='ShellCheck.SC####' />
            ...
          </file>
          ...
        </checkstyle>

**diff**

:   Auto-fixes in unified diff format. Can be piped to `git apply` or `patch -p1`
    to automatically apply fixes.

        --- a/test.sh
        +++ b/test.sh
        @@ -2,6 +2,6 @@
         ## Example of a broken script.
         for f in $(ls *.m3u)
         do
        -  grep -qi hq.*mp3 $f \
        +  grep -qi hq.*mp3 "$f" \
             && echo -e 'Playlist $f contains a HQ file in mp3 format'
         done


**json1**

:   Json is a popular serialization format that is more suitable for web
    applications. ShellCheck's json is compact and contains only the bare
    minimum.  Tabs are counted as 1 character.

        {
          comments: [
            {
              "file": "filename",
              "line": lineNumber,
              "column": columnNumber,
              "level": "severitylevel",
              "code": errorCode,
              "message": "warning message"
            },
            ...
          ]
        }

**json**

:   This is a legacy version of the **json1** format. It's a raw array of
    comments, and all offsets have a tab stop of 8.

**quiet**

:   Suppress all normal output. Exit with zero if no issues are found,
    otherwise exit with one. Stops processing after the first issue.


# DIRECTIVES

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:

    # shellcheck key=value key=value
    command-or-structure

For example, to suppress SC2035 about using `./*.jpg`:

    # shellcheck disable=SC2035
    echo "Files: " *.jpg

To tell ShellCheck where to look for an otherwise dynamically determined file:

    # shellcheck source=./lib.sh
    source "$(find_install_dir)/lib.sh"

Here a shell brace group is used to suppress a warning on multiple lines:

    # shellcheck disable=SC2016
    {
      echo 'Modifying $PATH'
      echo 'PATH=foo:$PATH' >> ~/.bashrc
    }

Valid keys are:

**disable**
:   Disables a comma separated list of error codes for the following command.
    The command can be a simple command like `echo foo`, or a compound command
    like a function definition, subshell block or loop. A range can be
    be specified with a dash, e.g. `disable=SC3000-SC4000` to exclude 3xxx.
    All warnings can be disabled with `disable=all`.

**enable**
:   Enable an optional check by name, as listed with **--list-optional**.
    Only file-wide `enable` directives are considered.

**external-sources**
:   Set to `true` in `.shellcheckrc` to always allow ShellCheck to open
    arbitrary files from 'source' statements (the way most tools do).

    This option defaults to `false` only due to ShellCheck's origin as a
    remote service for checking untrusted scripts. It can safely be enabled
    for normal development.

**source**
:   Overrides the filename included by a `source`/`.` 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 `/dev/null`.

**source-path**
:   Add a directory to the search path for `source`/`.` statements (by default,
    only ShellCheck's working directory is included). Absolute paths will also
    be rooted in these paths. The special path `SCRIPTDIR` can be used to
    specify the currently checked script's directory, as in
    `source-path=SCRIPTDIR` or `source-path=SCRIPTDIR/../libs`. Multiple
    paths accumulate, and `-P` takes precedence over them.

**shell**
:   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=SC2039'.

# RC FILES

Unless `--norc` is used, ShellCheck will look for a file `.shellcheckrc` or
`shellcheckrc` in the script's directory and each parent directory. If found,
it will read `key=value` pairs from it and treat them as file-wide directives.

Here is an example `.shellcheckrc`:

    # Look for 'source'd files relative to the checked script,
    # and also look for absolute paths in /mnt/chroot
    source-path=SCRIPTDIR
    source-path=/mnt/chroot

    # Since 0.9.0, values can be quoted with '' or "" to allow spaces
    source-path="My Documents/scripts"

    # Allow opening any 'source'd file, even if not specified as input
    external-sources=true

    # 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

If no `.shellcheckrc` is found in any of the parent directories, ShellCheck
will look in `~/.shellcheckrc` followed by the XDG config directory
(usually `~/.config/shellcheckrc`) on Unix, or `%APPDATA%/shellcheckrc` on
Windows. Only the first file found will be used.

Note for Snap users: the Snap sandbox disallows access to hidden files.
Use `shellcheckrc` without the dot instead.

Note for Docker users: ShellCheck will only be able to look for files that
are mounted in the container, so `~/.shellcheckrc` will not be read.


# ENVIRONMENT VARIABLES

The environment variable `SHELLCHECK_OPTS` can be set with default flags:

    export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016'

Its value will be split on spaces and prepended to the command line on each
invocation.

# RETURN VALUES

ShellCheck uses the following exit codes:

+ 0: All files successfully scanned with no issues.
+ 1: All files successfully scanned with some issues.
+ 2: Some files could not be processed (e.g. file not found).
+ 3: ShellCheck was invoked with bad syntax (e.g. unknown flag).
+ 4: ShellCheck was invoked with bad options (e.g. unknown formatter).

# LOCALE

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. `LC_CTYPE` is respected for output, and defaults to UTF-8 for
locales where encoding is unspecified (such as the `C` locale).

Windows users seeing `commitBuffer: invalid argument (invalid character)`
should set their terminal to use UTF-8 with `chcp 65001`.

# KNOWN INCOMPATIBILITIES

(If nothing in this section makes sense, you are unlikely to be affected by it)

To avoid confusing and misguided suggestions, ShellCheck requires function
bodies to be either `{ brace groups; }` or `( subshells )`, and function names
containing `[]*=!` are only recognized after a `function` keyword.

The following unconventional function definitions are identical in Bash,
but ShellCheck only recognizes the latter.

    [x!=y] () [[ $1 ]]
    function [x!=y] () { [[ $1 ]]; }

Shells without the `function` keyword do not allow these characters in function
names to begin with.  Function names containing `{}` are not supported at all.

Further, if ShellCheck sees `[x!=y]` it will assume this is an invalid
comparison. To invoke the above function, quote the command as in `'[x!=y]'`,
or to retain the same globbing behavior, use `command [x!=y]`.

ShellCheck imposes additional restrictions on the `[` command to help diagnose
common invalid uses. While `[ $x= 1 ]` is defined in POSIX, ShellCheck will
assume it was intended as the much more likely comparison `[ "$x" = 1 ]` and
fail accordingly. For unconventional or dynamic uses of the `[` command, use
`test` or `\[` instead.

# REPORTING BUGS

Bugs and issues can be reported on GitHub:

https://github.com/koalaman/shellcheck/issues

# AUTHORS

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

# COPYRIGHT

Copyright 2012-2022, Vidar Holen and contributors.
Licensed under the GNU General Public License version 3 or later,
see https://gnu.org/licenses/gpl.html

# SEE ALSO

sh(1) bash(1)