Directive

ShellCheck directives

Shellcheck directives allow you to control how shellcheck works, and take the form of comments in files:

hexToAscii() {
  # shellcheck disable=SC2059
  printf "\x$1"
}

or entries in a .shellcheckrc in the project root or user's home directory:

# ~/.shellcheckrc

# Don't suggest [ -n "$VAR" ] over [ ! -z "$VAR" ] 
disable=SC2236

# Suggest ${VAR} in place of $VAR
enable=require-variable-braces

Supported directives

disable

Prevent ShellCheck from processing one or more warnings:

# shellcheck disable=code[,code...]
statement_where_warning_should_be_disabled

A range of errors can also be specified, handy when disabling things for the entire file.

#!/bin/bash
# shellcheck disable=SC1000-SC9999

An alias all is available instead of specifying 0-9999 to disable all checks.

enable

Enables an optional check (since 0.7.0).

#!/bin/bash
# shellcheck enable=require-variable-braces
echo "Hello $USER"  # Will suggest ${USER}

To see a list of optional checks with examples, run shellcheck --list-optional. See here for more information.

external-sources

Set whether or not to follow arbitrary file paths in source statements (since 0.8.0).

Use external-sources=true in .shellcheckrc to let shellcheck access arbitrary files, whether or not they're specified as input. external-sources=false disables this, which is the default.

Individual script files can disable but not enable this option.

source

Tell ShellCheck where to find a sourced file (since 0.4.0):

# shellcheck source=src/examples/config.sh
. "$(locate_config)"

source-path

Give ShellCheck a path in which to search for sourced files (since 0.7.0).

# The script will now look for src/examples/mylib.sh
# shellcheck source-path=src/examples
. mylib.sh

The special value source-path=SCRIPTDIR will search in the current script's directory, and it can be used as a relative path like source-path=SCRIPTDIR/../lib.

To support the common pattern of . "$CONFIGDIR/mylib.sh", ShellCheck strips one leading, dynamic section before trying to locate the rest. That means that ShellCheck will look for config.sh and utils.sh in the same directory as this script when it is being checked:

#!/bin/sh
# shellcheck source-path=SCRIPTDIR
here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
. "$here/config.sh"
. "$here/utils.sh"

shell

Specify the shell for a script (similar to the shebang, if you for any reason don't want to add one) (since 0.4.5):

# shellcheck shell=sh
echo foo &> bar

Directives that replace or are immediately after the shebang apply to the entire script. Otherwise, they are scoped to the command that follows it (including compound commands like function definitions, loops and case statements). A directive may only be applied to a complete command, and can not be used immediately preceding an else block or individual case branch:

# Directive VALID here, applies to whole `case`
case $1 in
  # Directive INVALID, `-v)` is not a complete command
  -v)
    # Directive VALID here, applies to whole `if`
    if [ "$v" ]
    then
       # Directive VALID here, applies to `die ..` command
       die "Only one -v allowed"
    # Directive INVALID here, `else` is not a complete command
    else
      v=1
    fi ;;
 esac

There is no support for scoping a directive to the first structure of the script. In these cases, use a dummy command true or : and then add directives, such as

# This directive applies to the entire script
# shellcheck disable=2086
true

# This directive only applies to this function
# shellcheck disable=2043
f() {
  ...
}

Silencing parser errors is purely cosmetic; any parser error found will still stop ShellCheck at the point of the error.

Documenting directive use

To document why a specific directive was used, it is recommended to add a comment.

The comment can be added on the preceding line. This is the recommended option for long comments.

# this is intentional because of reasons
# that are long and need explaining
# shellcheck disable=SC1234
statement_where_warning_should_be_disabled

The comment can also be added at the end of the directive line. This is the recommended option for short comments.

# shellcheck disable=SC1234 # this is intentional
statement_where_warning_should_be_disabled