ShellCheck Reference Guide

# macOS
brew install shellcheck

# Ubuntu/Debian
apt-get install shellcheck

# Fedora
dnf install shellcheck

# From source/binary
# See: https://github.com/koalaman/shellcheck#installing

# Check a script
shellcheck script.sh

# Specify shell dialect
shellcheck -s bash script.sh
shellcheck -s sh script.sh
shellcheck -s ksh script.sh
shellcheck -s zsh script.sh

# Different output formats
shellcheck -f gcc script.sh       # GCC-style (for editors)
shellcheck -f checkstyle script.sh # Checkstyle XML
shellcheck -f json script.sh      # JSON
shellcheck -f tty script.sh       # TTY (default, with colors)

# Check multiple files
shellcheck *.sh

# Exclude specific warnings
shellcheck -e SC2086,SC2046 script.sh

# Set minimum severity
shellcheck -S error script.sh    # Only errors
shellcheck -S warning script.sh  # Warnings and above

# Show only errors
shellcheck -S error script.sh

# Show errors and warnings
shellcheck -S warning script.sh

# Show everything (default)
shellcheck script.sh

# Problematic
cp $file $destination

# Fixed
cp "$file" "$destination"

# Problematic
for file in $(ls *.txt); do

# Fixed
for file in *.txt; do

# Problematic
result=`command`

# Fixed
result=$(command)

# Problematic
local result=$(command)  # Masks return value

# Fixed
local result
result=$(command)

# Problematic
cd /some/directory
rm -rf *

# Fixed
cd /some/directory || exit
rm -rf *

# Problematic
command
if [ $? -eq 0 ]; then

# Fixed
if command; then

# Problematic
command $@

# Fixed
command "$@"

# Problematic
var=$(echo $value)

# Fixed
var=$value

# Problematic
while read line; do

# Fixed
while IFS= read -r line; do

# Problematic
echo "$var" | grep pattern

# Fixed
grep pattern <<< "$var"
# Or
printf '%s\n' "$var" | grep pattern

# In #!/bin/sh script
if [[ condition ]]; then  # Wrong

# Fixed
if [ condition ]; then

# In #!/bin/sh script
array=(one two)  # Wrong

# No direct fix - arrays not in POSIX sh
# Use alternatives like positional parameters

# shellcheck disable=SC2086
variable=$unquoted

# At top of file
# shellcheck disable=SC2086,SC2046

# shellcheck disable=SC2086
variable=$unquoted

# shellcheck disable=SC2086
{
    var1=$unquoted1
    var2=$unquoted2
}
# shellcheck enable=SC2086

# Specify shell dialect (overrides shebang)
# shellcheck shell=bash
# or
# shellcheck shell=sh

# Tell ShellCheck where to find sourced files
# shellcheck source=./lib/common.sh
. ./lib/common.sh

# For dynamically sourced files
# shellcheck source=/dev/null
. "$config_file"

# Disable specific checks globally
disable=SC2086,SC2046,SC2068

# Enable optional checks
enable=all
enable=avoid-nullary-conditions

# Specify shell
shell=bash

- name: Run ShellCheck
  uses: ludeeus/action-shellcheck@master
  with:
    severity: warning

shellcheck:
  script:
    - shellcheck **/*.sh

# .pre-commit-config.yaml
- repo: https://github.com/shellcheck-py/shellcheck-py
  rev: v0.9.0.2
  hooks:
    - id: shellcheck

# Good
while IFS= read -r line; do
    echo "$line"
done < file

if command -v shellcheck >/dev/null 2>&1; then
    echo "Found"
fi

cd /directory || exit 1

# Good (bash)
args=("first arg" "second arg")
command "${args[@]}"

# Instead of
cat file | grep pattern

# Use
grep pattern file
# or
< file grep pattern

# Enable all optional checks
# shellcheck enable=all

# Or specific ones
# shellcheck enable=avoid-nullary-conditions
# shellcheck enable=quote-safe-variables
# shellcheck enable=require-variable-braces

# Change severity of specific check
# shellcheck severity=warning SC2086