ShellCheck — A Static Analysis Tool for Shell Scripts That Finds Bugs Before You Ship

What it is

ShellCheck is a static analysis tool for shell scripts that catches bugs before they reach production. It detects unquoted variables, missing error handling, portability issues between bash/sh/dash, and dozens of other common shell scripting mistakes. It provides clear explanations and fix suggestions for every warning.

ShellCheck targets anyone who writes shell scripts: developers, DevOps engineers, SREs, and system administrators. It integrates with CI pipelines, text editors, and pre-commit hooks to catch issues early.

How it saves time or tokens

ShellCheck catches the class of bugs that are invisible during development but cause failures in production. An unquoted variable that works with simple filenames breaks on paths with spaces. A missing set -e lets a failed command go unnoticed. ShellCheck flags these issues instantly, preventing hours of debugging obscure production failures. Its CI integration ensures shell script quality is enforced automatically.

How to use

1. Install ShellCheck:

brew install shellcheck           # macOS
sudo apt install shellcheck       # Debian/Ubuntu
winget install koalaman.shellcheck # Windows

1. Lint a script:

shellcheck deploy.sh

1. Use in CI to enforce quality:

# Exit non-zero on any warning
shellcheck -S warning deploy.sh scripts/*.sh

Example

ShellCheck catching common bugs:

#!/bin/bash
# deploy.sh - ShellCheck will flag several issues:

cd /app/deploy       # SC2164: Use 'cd ... || exit' in case cd fails
rm -rf $BUILD_DIR/*  # SC2086: Double quote to prevent globbing and word splitting
if [ $STATUS = 0 ]; then  # SC2086: Double quote $STATUS
  echo 'Deploy success'
fi

# Fixed version:
cd /app/deploy || exit 1
rm -rf "${BUILD_DIR:?}"/*
if [ "$STATUS" = 0 ]; then
  echo 'Deploy success'
fi

Each warning includes a code (SC2164, SC2086) with a link to a detailed explanation.

Related on TokRepo

• AI Tools for DevOps — DevOps tools for deployment scripts and infrastructure
• AI Tools for Testing — Testing and linting tools for code quality enforcement

Common pitfalls

• ShellCheck defaults to the shell declared in the shebang line. Missing shebangs cause incorrect dialect detection. Always include #!/bin/bash or #!/bin/sh.
• Some warnings are intentional (e.g., SC2034 for variables used by sourced scripts). Use # shellcheck disable=SC2034 inline to suppress specific warnings.
• ShellCheck does not execute your script. It cannot catch runtime errors like missing binaries or incorrect paths. It only analyzes syntax and patterns.
• Always check the official documentation for the latest version-specific changes and migration guides before upgrading in production environments.