Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
Instrucciones de origen · Vista previa de solo lectura
name
shellcheck-configuration
description
Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
Comprehensive guidance for configuring and using ShellCheck to improve shell script quality, catch common pitfalls, and enforce best practices through static code analysis.
Do not use this skill when
The task is unrelated to shellcheck configuration and static analysis
You need a different domain or tool outside this scope
Instructions
Clarify goals, constraints, and required inputs.
Apply relevant best practices and validate outcomes.
Provide actionable steps and verification.
If detailed examples are required, open resources/implementation-playbook.md.
Use this skill when
Setting up linting for shell scripts in CI/CD pipelines
Analyzing existing shell scripts for issues
Understanding ShellCheck error codes and warnings
Configuring ShellCheck for specific project requirements
Integrating ShellCheck into development workflows
Suppressing false positives and configuring rule sets
Enforcing consistent code quality standards
Migrating scripts to meet quality gates
ShellCheck Fundamentals
What is ShellCheck?
ShellCheck is a static analysis tool that analyzes shell scripts and detects problematic patterns. It supports:
Bash, sh, dash, ksh, and other POSIX shells
Over 100 different warnings and errors
Configuration for target shell and flags
Integration with editors and CI/CD systems
Installation
# macOS with Homebrew
brew install shellcheck
# Ubuntu/Debian
apt-get install shellcheck
# From source
git clone https://github.com/koalaman/shellcheck.git
cd shellcheck
make build
make install
# Verify installation
shellcheck --version
# Set default shell target
SHELLCHECK_SHELL=bash
SHELLCHECK_STRICT=
SHELLCHECK_CONFIG=~/.shellcheckrc
export
# Enable strict mode
export
true
# Specify configuration file location
export
Common ShellCheck Error Codes
SC1000-1099: Parser Errors
# SC1004: Backslash continuation not followed by newlineecho hello\
world # Error - needs line continuation# SC1008: Invalid data for operator `=='if [[ $var = "value" ]]; then# Space before ==truefi
SC2000-2099: Shell Issues
# SC2009: Consider using pgrep or pidof instead of grep|grep
ps aux | grep -v grep | grep myprocess # Use pgrep instead# SC2012: Use `ls` only for viewing. Use `find` for reliable outputfor file in $(ls -la) # Better: use find or globbing# SC2015: Avoid using && and || instead of if-then-else
[[ -f "$file" ]] && echo"found" || echo"not found"# Less clear# SC2016: Expressions don't expand in single quotesecho'$VAR'# Literal $VAR, not variable expansion# SC2026: This word is non-standard. Set POSIXLY_CORRECT# when using with scripts for other shells
SC2100-2199: Quoting Issues
# SC2086: Double quote to prevent globbing and word splittingfor i in$list; do# Should be: for i in $list or for i in "$list"echo"$i"done# SC2115: Literal tilde in path not expanded. Use $HOME instead
~/.bashrc # In strings, use "$HOME/.bashrc"# SC2181: Check exit code directly with `if`, not indirectly in a list
some_command
if [ $? -eq 0 ]; then# Better: if some_command; then# SC2206: Quote to prevent word splitting or set IFS
array=( $items ) # Should use: array=( $items )
SC3000-3999: POSIX Compliance Issues
# SC3010: In POSIX sh, use 'case' instead of 'cond && foo'
[[ $var == "value" ]] && do_something # Not POSIX# SC3043: In POSIX sh, use 'local' is undefinedfunctionmy_func() {
local var=value # Not POSIX in some shells
}
Practical Configuration Examples
Minimal Configuration (Strict POSIX)
#!/bin/bash# Configure for maximum portability
shellcheck \
--shell=sh \
--external-sources \
--check-sourced \
script.sh
Development Configuration (Bash with Relaxed Rules)
#!/bin/bash# Configure for Bash development
shellcheck \
--shell=bash \
--exclude=SC1091,SC2119 \
--enable=all \
script.sh
CI/CD Integration Configuration
#!/bin/bashset -Eeuo pipefail
# Analyze all shell scripts and fail on issues
find . -type f -name "*.sh" | whileread -r script; doecho"Checking: $script"
shellcheck \
--shell=bash \
--format=gcc \
--exclude=SC1091 \
"$script" || exit 1
done
.shellcheckrc for Project
# Shell dialect to analyze against
shell=bash
# Enable optional checks
enable=avoid-nullary-conditions,require-variable-braces,check-unassigned-uppercase
# Disable specific warnings
# SC1091: Not following sourced files (many false positives)
disable=SC1091
# SC2119: Use function_name instead of function_name -- (arguments)
disable=SC2119
# External files to source for context
external-sources=true
Integration Patterns
Pre-commit Hook Configuration
#!/bin/bash# .git/hooks/pre-commit#!/bin/bashset -e
# Find all shell scripts changed in this commit
git diff --cached --name-only | grep '\.sh$' | whileread -r script; doecho"Linting: $script"if ! shellcheck "$script"; thenecho"ShellCheck failed on $script"exit 1
fidone
