Shellcheck

ShellCheck - Shell Script Static Analysis

Auto-routes when user mentions shellcheck, shell linting, bash script analysis, or SC error codes.

Overview

ShellCheck is a GPLv3-licensed static analysis tool that identifies bugs in bash/sh shell scripts. It detects:

• Syntax errors and parsing issues
• Semantic problems causing unexpected behavior
• Quoting issues and word splitting bugs
• POSIX compatibility warnings
• Style and best practice violations

Voice Notification

When executing a workflow, do BOTH:

1. Send voice notification:

   curl -s -X POST http://localhost:8888/notify \
     -H "Content-Type: application/json" \
     -d '{"message": "Running the WORKFLOWNAME workflow from the ShellCheck skill"}' \
     > /dev/null 2>&1 &

2. Output text notification:

   Running the **WorkflowName** workflow from the **ShellCheck** skill...

Workflow Routing

Quick Reference

Basic Usage

# Check a script
shellcheck myscript.sh

# Specify shell dialect
shellcheck -s bash myscript.sh

# Exclude specific codes
shellcheck -e SC2086,SC2046 myscript.sh

# Output formats
shellcheck -f gcc myscript.sh      # Editor integration
shellcheck -f json myscript.sh     # Machine readable
shellcheck -f diff myscript.sh     # Auto-fix patches

Common SC Codes

Inline Directives

# Disable for next command
# shellcheck disable=SC2086
echo $var

# Disable for entire file (after shebang)
#!/bin/bash
# shellcheck disable=SC2086,SC2046

Full Documentation

• Error Codes: SkillSearch('shellcheck error codes') -> loads ErrorCodes.md
• Configuration: SkillSearch('shellcheck config') -> loads Configuration.md
• CI/CD Integration: SkillSearch('shellcheck ci') -> loads Integration.md
• Best Practices: SkillSearch('shellcheck practices') -> loads BestPractices.md

Examples

Example 1: Analyze a script

User: "shellcheck my deploy script"
-> Invokes Analyze workflow
-> Runs shellcheck with JSON output
-> Presents findings grouped by severity
-> Suggests fixes with wiki links

Example 2: Fix common issues

User: "fix the shellcheck errors in scripts/"
-> Invokes Fix workflow
-> Generates diff output
-> Applies fixes interactively
-> Re-runs validation

Example 3: Setup for project

User: "setup shellcheck for this repo"
-> Invokes Setup workflow
-> Creates .shellcheckrc
-> Adds pre-commit hook
-> Configures CI workflow

Example 4: Explain an error code

User: "what does SC2086 mean?"
-> Invokes Explain workflow
-> Fetches wiki documentation
-> Shows examples and fixes
-> Provides context-specific guidance

---

Gotchas

• SC2086 is wrong inside `[[ ]]`: Bash's [[ ]] does not word-split, so [[ -n $var ]] is safe unquoted. Disabling SC2086 on [[ ]] blocks is a sign you're applying the lint to the wrong construct, not a sign the rule is broken.
• SC2034 fires on indirectly-used variables: Variables consumed via ${!prefix*} indirection, declare -p introspection, or sourced into another script trigger "unused" false positives. Use # shellcheck disable=SC2034 with a comment explaining the indirection — don't silence globally.
• Shebang determines the dialect, not the filename: script.sh with #!/bin/sh is checked as POSIX sh and rejects bashisms like [[ ]] or arrays. Either set the correct shebang or pass -s bash explicitly; never rely on the .sh extension.
• `shellcheck -e SC2086,SC2046` in `.shellcheckrc` hides real bugs: Project-wide disables compound — a year later nobody remembers why and unquoted expansions ship to prod. Prefer inline disables with a justification comment over global suppression.
• Source-following requires `-x` flag: source ./lib.sh is not analyzed by default. Run with shellcheck -x script.sh for full coverage, or add # shellcheck source=./lib.sh directives. CI configs frequently miss this and ship un-linted sourced files.
• `-f diff` patches assume the script parses cleanly: Syntax errors prevent the auto-fix output entirely, with no clear message. If -f diff produces nothing, run without -f first and fix parse errors before re-running for patches.

ShellCheck Best Practices

Comprehensive guide to writing clean, maintainable shell scripts.

The Top 10 Rules

1. Always Quote Variables

# Bad - word splitting and globbing
echo $filename
rm $file

# Good - prevents issues
echo "$filename"
rm "$file"

# Exception: inside [[ ]] for pattern matching
[[ $string == pattern* ]]

2. Use $() Instead of Backticks

# Bad - hard to nest, hard to read
files=`ls`
date=`date +%Y-\`date +%m\``

# Good - clear nesting
files=$(ls)
date=$(date +%Y-$(date +%m))

3. Use [[ Instead of [ in Bash

# Bad - quoting required, no pattern matching
[ "$var" = "value" ]
[ -n "$var" -a -f "$file" ]

# Good - safer, more features
[[ $var == "value" ]]
[[ -n $var && -f $file ]]
[[ $string =~ ^[0-9]+$ ]]  # Regex support

4. Use set -euo pipefail

#!/bin/bash
set -euo pipefail

# -e: Exit on error
# -u: Error on unset variables
# -o pipefail: Pipeline fails if any command fails

5. Declare and Assign Separately

# Bad - masks return value
local output=$(command_that_might_fail)

# Good - captures return value
local output
output=$(command_that_might_fail) || handle_error

6. Use Arrays for Lists

# Bad - word splitting issues
files="file1.txt file2.txt file with spaces.txt"
for f in $files; do
    process "$f"
done

# Good - proper array handling
files=("file1.txt" "file2.txt" "file with spaces.txt")
for f in "${files[@]}"; do
    process "$f"
done

7. Use "$@" for Arguments

# Bad - loses quoting
wrapper() {
    command $@
}

# Good - preserves quoting
wrapper() {
    command "$@"
}

8. Handle Errors Explicitly

# Bad - continues on failure
cd /some/directory
rm -rf *

# Good - explicit error handling
cd /some/directory || { echo "cd failed" >&2; exit 1; }
rm -rf ./*

# Or with trap
trap 'echo "Error on line $LINENO" >&2' ERR

9. Use command -v Instead of which

# Bad - non-standard, varies by system
if which git > /dev/null; then
    ...
fi

# Good - POSIX compliant
if command -v git > /dev/null 2>&1; then
    ...
fi

10. Use Parameter Expansion

# Bad - external commands
filename=$(basename "$path")
dirname=$(dirname "$path")
extension=$(echo "$file" | sed 's/.*\.//')

# Good - built-in parameter expansion
filename=${path##*/}
dirname=${path%/*}
extension=${file##*.}

Common Anti-Patterns

Parsing ls Output

# Bad - breaks on special characters
for file in $(ls); do
    process "$file"
done

# Good - use globs
for file in *; do
    [[ -f $file ]] && process "$file"
done

# Or find with -print0
while IFS= read -r -d '' file; do
    process "$file"
done < <(find . -type f -print0)

Using cat Unnecessarily

# Bad - useless use of cat (UUOC)
cat file | grep pattern
cat file | wc -l

# Good - direct input
grep pattern file
wc -l < file

Testing with $?

# Bad - indirect check
command
if [ $? -eq 0 ]; then
    echo "success"
fi

# Good - direct check
if command; then
    echo "success"
fi

Unquoted Variables in Tests

# Bad - breaks if empty
if [ -n $var ]; then
    ...
fi

# Good - properly quoted
if [[ -n $var ]]; then
    ...
fi

Read Without -r

# Bad - backslashes interpreted
while read line; do
    echo "$line"
done < file

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

Script Template

#!/usr/bin/env bash
#
# Script: myscript.sh
# Description: Brief description
# Usage: myscript.sh [options] <arguments>
#

set -euo pipefail

# Constants
readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
readonly SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")"

# Default values
VERBOSE=${VERBOSE:-false}
DRY_RUN=${DRY_RUN:-false}

# Colors (if terminal)
if [[ -t 1 ]]; then
    RED='\033[0;31m'
    GREEN='\033[0;32m'
    YELLOW='\033[0;33m'
    NC='\033[0m'
else
    RED=''
    GREEN=''
    YELLOW=''
    NC=''
fi

# Logging functions
log_info() { echo -e "${GREEN}[INFO]${NC} $*"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $*" >&2; }
log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }
die() { log_error "$*"; exit 1; }

# Usage/help
usage() {
    cat << EOF
Usage: $SCRIPT_NAME [options] <arguments>

Description of what this script does.

Options:
    -h, --help      Show this help message
    -v, --verbose   Enable verbose output
    -n, --dry-run   Show what would be done

Examples:
    $SCRIPT_NAME --verbose /path/to/file
    $SCRIPT_NAME -n

EOF
}

# Parse arguments
parse_args() {
    while [[ $# -gt 0 ]]; do
        case $1 in
            -h|--help)
                usage
                exit 0
                ;;
            -v|--verbose)
                VERBOSE=true
                shift
                ;;
            -n|--dry-run)
                DRY_RUN=true
                shift
                ;;
            --)
                shift
                break
                ;;
            -*)
                die "Unknown option: $1"
                ;;
            *)
                break
                ;;
        esac
    done

    # Remaining arguments
    ARGS=("$@")
}

# Cleanup function
cleanup() {
    # Remove temp files, restore state, etc.
    :
}

# Main function
main() {
    trap cleanup EXIT

    parse_args "$@"

    [[ $VERBOSE == true ]] && log_info "Verbose mode enabled"
    [[ $DRY_RUN == true ]] && log_warn "Dry-run mode - no changes will be made"

    # Your main logic here
    if [[ ${#ARGS[@]} -eq 0 ]]; then
        die "No arguments provided"
    fi

    for arg in "${ARGS[@]}"; do
        log_info "Processing: $arg"
    done
}

main "$@"

Quoting Reference

Parameter Expansion Cheat Sheet

Test Operators Cheat Sheet

File Tests

String Tests

Numeric Tests

ShellCheck Workflow

Development Phase

1. Write code with editor integration (real-time feedback) 2. Run shellcheck before committing 3. Fix issues or add justified suppressions

CI Phase

1. Pre-commit hook catches issues before push 2. CI pipeline enforces standards 3. Quality gates prevent merging broken scripts

Suppression Guidelines

Only suppress when:

• False positive (rare)
• Intentional behavior (document why)
• External variable (sourced from elsewhere)

Always add a comment:

# shellcheck disable=SC2034 # Variable used by sourced scripts
readonly CONFIG_PATH="/etc/myapp"

# Intentionally unquoted for word splitting
# shellcheck disable=SC2086
flags=$USER_FLAGS

Resources

• ShellCheck Wiki
• Google Shell Style Guide
• Bash Pitfalls
• Pure Bash Bible

ShellCheck Configuration Reference

Complete guide to configuring ShellCheck behavior.

Configuration Methods

ShellCheck can be configured through multiple methods (in order of precedence):

1. Command-line flags - Highest precedence 2. Inline directives - Per-command or file-wide 3. Configuration file (.shellcheckrc) - Project or user-wide 4. Environment variable (SHELLCHECK_OPTS) - System-wide defaults

Configuration File (.shellcheckrc)

File Locations

ShellCheck searches for configuration in this order:

1. Script's directory - .shellcheckrc or shellcheckrc 2. Parent directories - Walking up to root 3. Home directory - ~/.shellcheckrc 4. XDG config - ~/.config/shellcheckrc (Unix) 5. AppData - %APPDATA%/shellcheckrc (Windows)

Only the first file found is used.

File Format

# Comments start with #
key=value
key=value with spaces
key="quoted value"
key='single quoted'

Example .shellcheckrc

# Project-wide ShellCheck configuration

# Shell dialect (sh, bash, dash, ksh, busybox)
shell=bash

# Source file handling
source-path=SCRIPTDIR
source-path=SCRIPTDIR/lib
source-path=/usr/local/lib/myproject

# Allow following source statements
external-sources=true

# Enable extended dataflow analysis
extended-analysis=true

# Enable optional checks
enable=quote-safe-variables
enable=check-unassigned-uppercase
enable=require-variable-braces
enable=deprecate-which

# Disable specific warnings
disable=SC2059  # printf format string variable
disable=SC2034  # Unused variable (false positives)
disable=SC1090  # Can't follow non-constant source
disable=SC1091  # Not following sourced file

Minimal Project .shellcheckrc

# Minimum recommended configuration
shell=bash
source-path=SCRIPTDIR
external-sources=true
enable=deprecate-which

Inline Directives

Syntax

# shellcheck key=value

Placement Rules

Available Directive Keys

disable

Suppress specific warnings:

# Single code
# shellcheck disable=SC2086
echo $var

# Multiple codes
# shellcheck disable=SC2086,SC2046
files=$(ls *.txt)

# Range of codes
# shellcheck disable=SC1090-SC1100

# All warnings (v0.8+)
# shellcheck disable=all

enable

Activate optional checks:

#!/bin/bash
# shellcheck enable=require-variable-braces
# shellcheck enable=quote-safe-variables

shell

Specify shell dialect:

#!/bin/sh
# shellcheck shell=bash
# Script uses bash features despite sh shebang

source

Override sourced file location:

# Skip sourcing (use /dev/null)
# shellcheck source=/dev/null
source "$CONFIG_FILE"

# Specify actual location
# shellcheck source=./lib/common.sh
source "$LIB_DIR/common.sh"

# Use script directory
# shellcheck source=SCRIPTDIR/lib/utils.sh
source "$(dirname "$0")/lib/utils.sh"

source-path

Add search paths for sourced files:

# shellcheck source-path=SCRIPTDIR
# shellcheck source-path=SCRIPTDIR/../lib
# shellcheck source-path=/usr/local/lib

external-sources

Allow following arbitrary source statements:

# Can ONLY be set in .shellcheckrc, not inline
external-sources=true

extended-analysis

Toggle dataflow analysis (for performance on large files):

# Disable for auto-generated scripts
# shellcheck extended-analysis=false

Command-Line Options

Analysis Options

# Specify shell dialect
shellcheck -s bash script.sh
shellcheck --shell=bash script.sh

# Include sourced file warnings
shellcheck -a script.sh
shellcheck --check-sourced script.sh

# Follow external sources
shellcheck -x script.sh
shellcheck --external-sources script.sh

# Source search paths
shellcheck -P ./lib:./src script.sh
shellcheck --source-path=./lib:./src script.sh

Filtering Options

# Exclude codes
shellcheck -e SC2086,SC2046 script.sh
shellcheck --exclude=SC2086,SC2046 script.sh

# Include only specific codes
shellcheck -i SC2086 script.sh
shellcheck --include=SC2086 script.sh

# Enable optional checks
shellcheck -o require-variable-braces script.sh
shellcheck --enable=require-variable-braces script.sh
shellcheck -o all script.sh  # Enable all optional

# Minimum severity
shellcheck -S error script.sh      # Only errors
shellcheck -S warning script.sh    # Errors + warnings
shellcheck -S info script.sh       # Errors + warnings + info
shellcheck -S style script.sh      # All (default)
shellcheck --severity=warning script.sh

Output Options

# Output format
shellcheck -f tty script.sh        # Human-readable (default)
shellcheck -f gcc script.sh        # GCC format for editors
shellcheck -f checkstyle script.sh # XML for CI tools
shellcheck -f diff script.sh       # Unified diff for auto-fix
shellcheck -f json script.sh       # JSON (legacy)
shellcheck -f json1 script.sh      # JSON (compact)
shellcheck -f quiet script.sh      # Exit code only
shellcheck --format=gcc script.sh

# Color control
shellcheck -C always script.sh
shellcheck -C never script.sh
shellcheck -C auto script.sh
shellcheck --color=always script.sh

# Wiki links
shellcheck -W 3 script.sh          # Show 3 wiki links
shellcheck -W 0 script.sh          # Disable wiki links
shellcheck --wiki-link-count=3 script.sh

Configuration Options

# Skip .shellcheckrc
shellcheck --norc script.sh

# Use specific config file
shellcheck --rcfile=./custom.shellcheckrc script.sh

# Extended analysis control
shellcheck --extended-analysis=true script.sh
shellcheck --extended-analysis=false script.sh

# List optional checks
shellcheck --list-optional

Environment Variable

Set default options via SHELLCHECK_OPTS:

# In ~/.bashrc or ~/.zshrc
export SHELLCHECK_OPTS='--shell=bash --exclude=SC2016 --enable=deprecate-which'

# One-time override
SHELLCHECK_OPTS='-x -S warning' shellcheck script.sh

Optional Checks

List available with shellcheck --list-optional:

Enabling Optional Checks

# Command line
shellcheck -o deprecate-which,require-variable-braces script.sh
shellcheck -o all script.sh  # Enable all

# .shellcheckrc
enable=deprecate-which
enable=require-variable-braces

# Inline (file-wide only)
#!/bin/bash
# shellcheck enable=require-variable-braces

Platform-Specific Notes

Snap Users

The Snap sandbox blocks hidden files. Use shellcheckrc (no dot):

# Instead of .shellcheckrc
mv .shellcheckrc shellcheckrc

Docker Users

Mount config files explicitly:

docker run --rm \
  -v "$PWD:/mnt" \
  -v "$HOME/.shellcheckrc:/root/.shellcheckrc:ro" \
  koalaman/shellcheck /mnt/script.sh

Or use environment variable:

docker run --rm \
  -e SHELLCHECK_OPTS='--shell=bash' \
  -v "$PWD:/mnt" \
  koalaman/shellcheck /mnt/script.sh

ShellCheck Error Codes Reference

Complete reference for ShellCheck diagnostic codes (SC codes).

Code Categories

SC1xxx - Parser and Syntax Errors

Fundamental parsing issues and syntax violations.

SC2xxx - Semantic and Style Issues

Logic errors, performance concerns, and best practices.

Quoting Issues

Variable Issues

SC3xxx - POSIX Compatibility

Warnings for non-POSIX features in sh scripts.

Severity Levels

ShellCheck categorizes warnings by severity:

Wiki Links

Each code has detailed documentation at: https://www.shellcheck.net/wiki/SCXXXX

For example: https://www.shellcheck.net/wiki/SC2086

ShellCheck CI/CD Integration Guide

Complete guide for integrating ShellCheck into development workflows.

Pre-commit Hooks

Official Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.11.0
    hooks:
      - id: shellcheck
        # Optional: customize arguments
        args: ["--severity=warning"]

Alternative: shellcheck-py

repos:
  - repo: https://github.com/shellcheck-py/shellcheck-py
    rev: v0.9.0.5
    hooks:
      - id: shellcheck

Custom Pre-commit Script

#!/bin/bash
# .git/hooks/pre-commit

# Find all staged shell scripts
staged_scripts=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(sh|bash|zsh)$')

if [[ -n "$staged_scripts" ]]; then
    echo "Running ShellCheck on staged scripts..."

    # Run shellcheck on all staged scripts
    if ! echo "$staged_scripts" | xargs shellcheck; then
        echo "ShellCheck found issues. Please fix them before committing."
        exit 1
    fi
fi

exit 0

Make executable:

chmod +x .git/hooks/pre-commit

GitHub Actions

Basic Workflow

# .github/workflows/shellcheck.yml
name: ShellCheck

on:
  push:
    branches: [main, develop]
    paths:
      - '**.sh'
      - '**.bash'
  pull_request:
    paths:
      - '**.sh'
      - '**.bash'

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run ShellCheck
        uses: ludeeus/action-shellcheck@master
        with:
          severity: warning
          scandir: './scripts'
          format: gcc
          additional_files: 'entrypoint'

Advanced Workflow with Annotations

name: ShellCheck

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install ShellCheck
        run: sudo apt-get install -y shellcheck

      - name: Find shell scripts
        id: scripts
        run: |
          scripts=$(find . -type f \( -name "*.sh" -o -name "*.bash" \) ! -path "./.git/*")
          echo "scripts<<EOF" >> $GITHUB_OUTPUT
          echo "$scripts" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Run ShellCheck
        run: |
          echo "${{ steps.scripts.outputs.scripts }}" | xargs shellcheck -f gcc || true

      - name: ShellCheck with annotations
        run: |
          echo "${{ steps.scripts.outputs.scripts }}" | xargs shellcheck -f json | \
            jq -r '.[] | "::warning file=\(.file),line=\(.line),col=\(.column)::\(.message) [\(.code)]"'

Matrix Testing Multiple Shells

name: ShellCheck Multi-Shell

on: [push, pull_request]

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shell: [sh, bash, dash, ksh]
    steps:
      - uses: actions/checkout@v4

      - name: Run ShellCheck for ${{ matrix.shell }}
        run: |
          find ./scripts -name "*.sh" -exec shellcheck -s ${{ matrix.shell }} {} +

GitLab CI/CD

Basic Pipeline

# .gitlab-ci.yml
shellcheck:
  image: koalaman/shellcheck-alpine:stable
  stage: test
  script:
    - find . -name "*.sh" -exec shellcheck {} +
  only:
    changes:
      - "**/*.sh"

With Artifacts

shellcheck:
  image: koalaman/shellcheck-alpine:stable
  stage: lint
  script:
    - find . -name "*.sh" -print0 | xargs -0 shellcheck -f checkstyle > shellcheck-report.xml || true
  artifacts:
    reports:
      junit: shellcheck-report.xml
    paths:
      - shellcheck-report.xml
    expire_in: 1 week

Jenkins

Declarative Pipeline

pipeline {
    agent any

    stages {
        stage('ShellCheck') {
            steps {
                sh '''
                    find . -name "*.sh" | xargs shellcheck -f checkstyle > shellcheck.xml || true
                '''
            }
            post {
                always {
                    recordIssues tools: [checkStyle(pattern: 'shellcheck.xml')]
                }
            }
        }
    }
}

With Docker

pipeline {
    agent {
        docker {
            image 'koalaman/shellcheck-alpine:stable'
        }
    }

    stages {
        stage('Lint') {
            steps {
                sh 'find . -name "*.sh" -exec shellcheck {} +'
            }
        }
    }
}

CircleCI

# .circleci/config.yml
version: 2.1

orbs:
  shellcheck: circleci/shellcheck@3.2.0

workflows:
  lint:
    jobs:
      - shellcheck/check:
          dir: ./scripts
          severity: warning
          exclude: SC1091

Travis CI

# .travis.yml
language: shell

addons:
  apt:
    packages:
      - shellcheck

script:
  - find . -name "*.sh" -exec shellcheck {} +

Azure DevOps

# azure-pipelines.yml
trigger:
  paths:
    include:
      - '**/*.sh'

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: Bash@3
    displayName: 'Install ShellCheck'
    inputs:
      targetType: 'inline'
      script: |
        sudo apt-get update
        sudo apt-get install -y shellcheck

  - task: Bash@3
    displayName: 'Run ShellCheck'
    inputs:
      targetType: 'inline'
      script: |
        find . -name "*.sh" -exec shellcheck -f gcc {} +

Makefile Integration

# Makefile

SHELL_SCRIPTS := $(shell find . -name "*.sh" -not -path "./.git/*")

.PHONY: lint lint-fix check-shellcheck

# Check if shellcheck is installed
check-shellcheck:
	@command -v shellcheck >/dev/null 2>&1 || { echo "shellcheck not installed. Run: brew install shellcheck"; exit 1; }

# Run shellcheck
lint: check-shellcheck
	@echo "Running ShellCheck on $(words $(SHELL_SCRIPTS)) scripts..."
	@shellcheck $(SHELL_SCRIPTS)

# Run with severity filter
lint-warnings: check-shellcheck
	@shellcheck -S warning $(SHELL_SCRIPTS)

lint-errors: check-shellcheck
	@shellcheck -S error $(SHELL_SCRIPTS)

# Generate diff for auto-fixes
lint-fix: check-shellcheck
	@shellcheck -f diff $(SHELL_SCRIPTS) | patch -p1

# Generate JSON report
lint-report: check-shellcheck
	@shellcheck -f json $(SHELL_SCRIPTS) > shellcheck-report.json

# CI mode - fail on any issue
ci-lint: check-shellcheck
	@shellcheck -S warning -f gcc $(SHELL_SCRIPTS)

Editor Integration

VS Code

Install vscode-shellcheck extension:

// .vscode/settings.json
{
  "shellcheck.enable": true,
  "shellcheck.run": "onSave",
  "shellcheck.executablePath": "shellcheck",
  "shellcheck.exclude": ["SC1091"],
  "shellcheck.customArgs": ["-x"]
}

Vim/Neovim with ALE

" ~/.vimrc or init.vim
let g:ale_linters = {
\   'sh': ['shellcheck'],
\   'bash': ['shellcheck'],
\}

let g:ale_sh_shellcheck_options = '-x'
let g:ale_sh_shellcheck_exclusions = 'SC1091'

Neovim with nvim-lint

-- lua/plugins/lint.lua
require('lint').linters_by_ft = {
  sh = {'shellcheck'},
  bash = {'shellcheck'},
}

require('lint').linters.shellcheck.args = {
  '-x',
  '-f', 'gcc',
  '-',
}

Emacs with Flycheck

;; ~/.emacs.d/init.el
(use-package flycheck
  :ensure t
  :init (global-flycheck-mode)
  :config
  (setq flycheck-shellcheck-follow-sources nil)
  (add-to-list 'flycheck-disabled-checkers 'sh-posix-dash))

Sublime Text

Install SublimeLinter-shellcheck via Package Control.

Docker Usage

Basic Docker Run

# Check single file
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable /mnt/script.sh

# Check directory
docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable /mnt/**/*.sh

# With options
docker run --rm -v "$PWD:/mnt" \
  -e SHELLCHECK_OPTS='-x -S warning' \
  koalaman/shellcheck:stable /mnt/scripts/*.sh

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  shellcheck:
    image: koalaman/shellcheck:stable
    volumes:
      - ./:/mnt:ro
      - ./.shellcheckrc:/root/.shellcheckrc:ro
    command: /mnt/scripts/*.sh

Multi-stage Dockerfile with ShellCheck

# Dockerfile
FROM koalaman/shellcheck:stable AS shellcheck
COPY scripts/ /scripts/
RUN shellcheck /scripts/*.sh

FROM ubuntu:22.04
COPY --from=shellcheck /scripts/ /app/scripts/
# ... rest of build

Quality Gate Integration

SonarQube

Use CheckStyle format and import:

shellcheck -f checkstyle *.sh > shellcheck-checkstyle.xml

Codacy

ShellCheck is natively supported. Enable in repository settings.

Code Climate

Add to .codeclimate.yml:

version: "2"
plugins:
  shellcheck:
    enabled: true
    config:
      severity: warning

CodeFactor

ShellCheck is enabled by default for shell scripts.

Analyze Workflow

Analyze shell scripts with ShellCheck and present findings.

Trigger

• "shellcheck this script"
• "lint my shell script"
• "check for shell errors"
• "analyze bash script"

Process

1. Identify Scripts

Find shell scripts to analyze:

# Single file provided
shellcheck "$FILE"

# Find all scripts in directory
find . -type f \( -name "*.sh" -o -name "*.bash" -o -name "*.zsh" \) ! -path "./.git/*"

# Or detect by shebang
find . -type f ! -path "./.git/*" -exec sh -c '
    head -1 "$1" | grep -qE "^#!.*(bash|sh|zsh|ksh)" && echo "$1"
' _ {} \;

2. Run ShellCheck

# JSON output for parsing
shellcheck -f json "$SCRIPTS" 2>/dev/null

# GCC format for quick viewing
shellcheck -f gcc "$SCRIPTS"

# With all optional checks enabled
shellcheck -o all -f json "$SCRIPTS"

3. Parse and Present Results

Group findings by severity:

# Count by severity
shellcheck -f json script.sh | jq 'group_by(.level) | map({level: .[0].level, count: length})'

4. Output Format

Present findings in structured format:

## ShellCheck Analysis: script.sh

### Summary
- **Errors:** 2
- **Warnings:** 5
- **Info:** 3
- **Style:** 1

### Findings

#### Errors (Must Fix)

**SC2086** (line 15): Double quote to prevent globbing and word splitting.

Line 15

echo $variable

Fix

echo "$variable"

[Wiki: SC2086](https://www.shellcheck.net/wiki/SC2086)

#### Warnings

**SC2046** (line 23): Quote this to prevent word splitting.

Line 23

files=$(ls *.txt)

Fix

files="$(ls *.txt)"

[Wiki: SC2046](https://www.shellcheck.net/wiki/SC2046)

### Quick Fixes

Apply auto-fixes with:

shellcheck -f diff script.sh | patch -p1

Example Invocations

# Basic analysis
shellcheck script.sh

# Strict analysis (all checks)
shellcheck -o all -S warning script.sh

# Check multiple files
shellcheck scripts/*.sh

# Recursive directory
find . -name "*.sh" -exec shellcheck {} +

# With specific shell
shellcheck -s bash script.sh

Integration with Workflows

After analysis, suggest:

1. Auto-fix available issues:

   shellcheck -f diff script.sh | patch -p1

2. Configure suppressions for false positives

3. Set up pre-commit hook for continuous validation

Explain Workflow

Explain ShellCheck error codes and provide context-specific guidance.

Trigger

• "explain SC2086"
• "what does SC2086 mean"
• "shellcheck error SC2046"
• "help with SC code"

Process

1. Parse Error Code

Extract the SC code from user input:

• SC2086
• 2086
• shellcheck SC2086

2. Fetch Documentation

Reference the wiki URL:

https://www.shellcheck.net/wiki/SCXXXX

3. Provide Explanation

Structure the response:

1. What it means - Plain language explanation 2. Why it matters - The actual problem it catches 3. How to fix - Code examples 4. When to suppress - Legitimate exceptions

Common Error Explanations

SC2086 - Double quote to prevent globbing and word splitting

What it means: Variable is unquoted, which allows word splitting and glob expansion.

Why it matters:

# If filename contains spaces or glob characters
filename="my file*.txt"

# Bad - expands to multiple arguments or matches files
rm $filename

# Could become:
rm my file*.txt  # 3 separate args!
# Or expand globs to match actual files

How to fix:

rm "$filename"

When to suppress:

• Intentionally splitting a variable: # shellcheck disable=SC2086
• Variable contains intentional glob pattern

---

SC2046 - Quote this to prevent word splitting

What it means: Command substitution output is unquoted.

Why it matters:

# Bad - output split on whitespace
files=$(find . -name "*.txt")
for f in $files; do  # Breaks on spaces in filenames
    process "$f"
done

How to fix:

# Use arrays
mapfile -t files < <(find . -name "*.txt")
for f in "${files[@]}"; do
    process "$f"
done

# Or use while read
find . -name "*.txt" -print0 | while IFS= read -r -d '' f; do
    process "$f"
done

---

SC2034 - Variable appears unused

What it means: A variable is assigned but never used in the script.

Why it matters:

• Dead code that should be removed
• Possible typo in variable name
• Variable meant for external use

How to fix:

# If truly unused, remove it
# readonly UNUSED_VAR="value"  # Delete

# If used externally, export it
export CONFIG_PATH="/etc/myapp"

# If false positive, disable with explanation
# shellcheck disable=SC2034 # Used by sourced scripts
readonly LIB_VERSION="1.0.0"

---

SC2154 - Variable is referenced but not assigned

What it means: Using a variable that was never set.

Why it matters:

• Typo in variable name
• Missing assignment
• Variable expected from environment/sourced file

How to fix:

# Ensure assignment
MY_VAR="value"
echo "$MY_VAR"

# For environment variables, check existence
if [[ -z ${ENV_VAR:-} ]]; then
    echo "ENV_VAR not set" >&2
    exit 1
fi

# For sourced files, add directive
# shellcheck source=./config.sh
source "$CONFIG_FILE"

---

SC2155 - Declare and assign separately

What it means: local declaration combined with command substitution masks the exit code.

Why it matters:

# Bad - exit code of 'command' is lost
local output=$(command_that_might_fail)
# $? is always 0 (from successful 'local')

# If command_that_might_fail returns 1, you won't know

How to fix:

# Declare separately
local output
output=$(command_that_might_fail) || return 1

---

SC2164 - Use 'cd ... || exit' in case cd fails

What it means: cd can fail, and subsequent commands would run in wrong directory.

Why it matters:

# Dangerous!
cd /some/directory
rm -rf *  # If cd failed, deletes from current directory!

How to fix:

cd /some/directory || exit 1
rm -rf ./*

# Or with error handling
cd /some/directory || {
    echo "Failed to cd to /some/directory" >&2
    exit 1
}

---

SC1090 - Can't follow non-constant source

What it means: ShellCheck can't analyze a dynamically sourced file.

Why it matters: ShellCheck needs to know what's being sourced to check for issues.

How to fix:

# Tell ShellCheck where to find the file
# shellcheck source=./lib/common.sh
source "$LIB_DIR/common.sh"

# Or skip if file doesn't exist at check time
# shellcheck source=/dev/null
source "$DYNAMIC_CONFIG"

---

SC2006 - Use $(...) instead of backticks

What it means: Using legacy backtick syntax for command substitution.

Why it matters:

• Backticks are harder to read
• Can't be nested easily
• Quoting rules are confusing

How to fix:

# Bad
date=`date +%Y-%m-%d`
nested=`echo \`hostname\``

# Good
date=$(date +%Y-%m-%d)
nested=$(echo "$(hostname)")

---

SC2162 - read without -r will mangle backslashes

What it means: read interprets backslashes as escape sequences without -r.

Why it matters:

# Bad
echo "path\to\file" | read line
echo "$line"  # Outputs: pathoile (backslashes interpreted)

How to fix:

# Use -r for raw input
while IFS= read -r line; do
    echo "$line"
done < file

Output Template

## SC{CODE}: {Title}

### Explanation
{Plain language explanation}

### Why This Matters
{Real-world consequences}

### Before (Problematic)

{bad code}

### After (Fixed)

{fixed code}

### When to Suppress
{Legitimate exceptions with example}

shellcheck disable=SC{CODE}

Reason: {justification}

{code}

### Related Codes
- SC{related1}: {description}
- SC{related2}: {description}

### Resources
- [Wiki: SC{CODE}](https://www.shellcheck.net/wiki/SC{CODE})

Fix Workflow

Apply ShellCheck fixes to shell scripts.

Trigger

• "fix shellcheck errors"
• "apply shellcheck fixes"
• "auto-fix shell script"
• "fix SC2086"

Process

1. Generate Diff

# Generate unified diff for all fixable issues
shellcheck -f diff script.sh > fixes.patch

# Preview changes
cat fixes.patch

2. Review Fixes

Present the diff to user for review:

# Show with color
diff -u original.sh fixed.sh | colordiff

# Or use git diff
git diff --no-index original.sh fixed.sh

3. Apply Fixes

Option A: Apply patch

shellcheck -f diff script.sh | patch -p1

Option B: Apply with git

shellcheck -f diff script.sh | git apply

Option C: Selective application

# Apply only specific files
shellcheck -f diff script.sh | patch -p1 --dry-run  # Preview
shellcheck -f diff script.sh | patch -p1            # Apply

4. Verify Fixes

# Re-run shellcheck to confirm
shellcheck script.sh

# Should show fewer/no issues
echo "Exit code: $?"  # 0 = clean

Common Fixes

SC2086 - Quote Variables

Before:

echo $variable
rm $files

After:

echo "$variable"
rm "$files"

SC2046 - Quote Command Substitution

Before:

files=$(find . -name "*.txt")

After:

files="$(find . -name "*.txt")"

SC2006 - Use $() Instead of Backticks

Before:

date=`date +%Y-%m-%d`

After:

date=$(date +%Y-%m-%d)

SC2155 - Declare and Assign Separately

Before:

local output=$(command)

After:

local output
output=$(command)

SC2164 - Add || exit After cd

Before:

cd /some/directory
rm -rf *

After:

cd /some/directory || exit 1
rm -rf ./*

Batch Fix Multiple Files

#!/bin/bash
# fix-all-scripts.sh

set -euo pipefail

# Find all shell scripts
scripts=$(find . -name "*.sh" -o -name "*.bash" | grep -v ".git")

for script in $scripts; do
    echo "Fixing: $script"

    # Generate and apply fixes
    if diff=$(shellcheck -f diff "$script" 2>/dev/null); then
        if [[ -n "$diff" ]]; then
            echo "$diff" | patch -p1
            echo "  Applied fixes"
        else
            echo "  No fixes needed"
        fi
    else
        echo "  Error running shellcheck"
    fi
done

echo "Done. Re-running shellcheck..."
find . -name "*.sh" -exec shellcheck {} + || true

Manual Fix Patterns

When auto-fix isn't available:

Array Expansion

# Bad: SC2068
process ${array[@]}

# Good
process "${array[@]}"

Read Without -r

# Bad: SC2162
while read line; do

# Good
while IFS= read -r line; do

Test Command

# Bad: SC2070
[ -n $var ]

# Good
[[ -n $var ]]

Output Format

After applying fixes, report:

## Fixes Applied

**Script:** deploy.sh

| Line | Code | Fix Applied |
|------|------|-------------|
| 15 | SC2086 | Quoted `$variable` |
| 23 | SC2046 | Quoted command substitution |
| 45 | SC2006 | Replaced backticks with `$()` |

**Remaining Issues:**
- SC2034 (line 8): Variable appears unused - manual review needed
- SC1090 (line 3): Can't follow dynamic source - add directive

**Commands:**

Verify fixes

shellcheck deploy.sh

Add directive for SC1090

shellcheck source=/dev/null

source "$CONFIG_FILE"

Setup Workflow

Configure ShellCheck for a project with configuration file, pre-commit hooks, and CI integration.

Trigger

• "setup shellcheck for this project"
• "configure shellcheck"
• "add shellcheck to CI"
• "install shellcheck"

Process

1. Check Installation

# Check if installed
if command -v shellcheck >/dev/null 2>&1; then
    echo "ShellCheck $(shellcheck --version | head -2 | tail -1) installed"
else
    echo "ShellCheck not installed"
fi

2. Install ShellCheck

macOS:

brew install shellcheck

Debian/Ubuntu:

sudo apt-get update && sudo apt-get install -y shellcheck

Arch Linux:

sudo pacman -S shellcheck

Fedora:

sudo dnf install ShellCheck

From Binary (Linux):

VERSION="v0.11.0"
wget -qO- "https://github.com/koalaman/shellcheck/releases/download/${VERSION}/shellcheck-${VERSION}.linux.x86_64.tar.xz" | tar -xJf -
sudo cp "shellcheck-${VERSION}/shellcheck" /usr/local/bin/

3. Create .shellcheckrc

Create project configuration:

cat > .shellcheckrc << 'EOF'
# ShellCheck Configuration
# https://www.shellcheck.net/wiki/

# Shell dialect (sh, bash, dash, ksh, busybox)
shell=bash

# Source file handling
source-path=SCRIPTDIR
source-path=SCRIPTDIR/lib
external-sources=true

# Enable dataflow analysis
extended-analysis=true

# Enable optional checks
enable=deprecate-which
enable=quote-safe-variables
enable=require-variable-braces

# Disable common false positives (customize as needed)
# disable=SC1090  # Can't follow non-constant source
# disable=SC1091  # Not following sourced file
# disable=SC2034  # Variable appears unused
EOF

4. Setup Pre-commit Hook

Option A: Using pre-commit framework

Create/update .pre-commit-config.yaml:

repos:
  - repo: https://github.com/koalaman/shellcheck-precommit
    rev: v0.11.0
    hooks:
      - id: shellcheck
        args: ["--severity=warning"]

Install:

pip install pre-commit
pre-commit install

Option B: Git hook directly

cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# ShellCheck pre-commit hook

set -euo pipefail

# Find staged shell scripts
staged=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(sh|bash)$' || true)

if [[ -n "$staged" ]]; then
    echo "Running ShellCheck..."
    if ! echo "$staged" | xargs shellcheck; then
        echo ""
        echo "ShellCheck found issues. Fix them or use:"
        echo "  git commit --no-verify"
        exit 1
    fi
    echo "ShellCheck passed!"
fi
EOF

chmod +x .git/hooks/pre-commit

5. Setup CI Pipeline

GitHub Actions:

Create .github/workflows/shellcheck.yml:

name: ShellCheck

on:
  push:
    branches: [main, develop]
    paths:
      - '**.sh'
      - '**.bash'
      - '.shellcheckrc'
  pull_request:
    paths:
      - '**.sh'
      - '**.bash'
      - '.shellcheckrc'

jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run ShellCheck
        uses: ludeeus/action-shellcheck@master
        with:
          severity: warning
          scandir: '.'
          format: gcc

GitLab CI:

Add to .gitlab-ci.yml:

shellcheck:
  image: koalaman/shellcheck-alpine:stable
  stage: lint
  script:
    - find . -name "*.sh" -not -path "./.git/*" -exec shellcheck {} +
  only:
    changes:
      - "**/*.sh"
      - ".shellcheckrc"

6. Add Makefile Target

# Add to Makefile
SHELL_SCRIPTS := $(shell find . -name "*.sh" -not -path "./.git/*")

.PHONY: lint lint-shell

lint-shell:
	@echo "Running ShellCheck..."
	@shellcheck $(SHELL_SCRIPTS)

lint: lint-shell
	@echo "All linters passed!"

7. Editor Configuration

VS Code:

Create .vscode/settings.json:

{
  "shellcheck.enable": true,
  "shellcheck.run": "onSave",
  "shellcheck.exclude": [],
  "shellcheck.customArgs": ["-x"]
}

Vim (with ALE):

Add to .vimrc or project .vimrc:

let g:ale_linters = {'sh': ['shellcheck'], 'bash': ['shellcheck']}
let g:ale_sh_shellcheck_options = '-x'

Output Format

After setup, present summary:

## ShellCheck Setup Complete

### Files Created/Modified

| File | Purpose |
|------|---------|
| `.shellcheckrc` | Project configuration |
| `.pre-commit-config.yaml` | Pre-commit hook |
| `.github/workflows/shellcheck.yml` | CI pipeline |
| `Makefile` | Added `lint-shell` target |

### Quick Commands

Check all scripts

make lint-shell

Check single file

shellcheck script.sh

Auto-fix issues

shellcheck -f diff script.sh | patch -p1

Run pre-commit manually

pre-commit run shellcheck --all-files

### Configuration Summary

- **Shell:** bash
- **Optional checks:** deprecate-which, quote-safe-variables, require-variable-braces
- **Severity:** warning (CI), all (local)
- **Source paths:** SCRIPTDIR, SCRIPTDIR/lib

### Next Steps

1. Run `shellcheck scripts/*.sh` to check existing scripts
2. Fix any issues or add justified suppressions
3. Commit the configuration files

Customization Options

Ask user about preferences:

1. Shell dialect: bash (default), sh, zsh, ksh 2. Strictness level: relaxed, standard (default), strict 3. Optional checks: which ones to enable 4. CI platform: GitHub Actions, GitLab CI, none 5. Pre-commit: pre-commit framework, git hook, none