Configure ShellCheck for Code Quality

ShellCheck Configuration and Static Analysis guides the use of ShellCheck to identify problematic shell patterns and maintain consistent script quality. It covers Bash, sh, dash, ksh, and POSIX-oriented analysis, with configuration for the intended dialect, optional checks, and exclusions. The workflow includes project configuration, diagnosis, developer feedback, and CI enforcement.

A project-level .shellcheckrc can select the shell and enable or disable checks. Explicit command options offer another way to configure the dialect and rules. Consult the installed help and official diagnostic pages rather than relying on invented environment variables or treating numeric diagnostic ranges as categories.

Use it to add shell linting to CI/CD, analyze existing scripts, understand warnings, configure a project-specific rule set, or migrate scripts toward a quality gate. Editor feedback and pre-commit checks help identify issues during development rather than waiting until merge time.

Do not analyze Bash code as sh unless portability to sh is the actual target. Suppressions need a narrow scope and recorded justification; addressing a real issue is preferable to disabling its warning. Missing task constraints or inputs need clarification, and static analysis still requires validation against the intended script behavior.

Inputs include scripts, target dialect, rc files, sourced files, enabled checks, and any justified exclusions. Output can use the default human-readable format, GCC-style locations for CI, JSON for parsing, or quiet output with a nonzero result when issues are found. A parsing-oriented command is:

shellcheck --format=json script.sh

Diagnostic guidance distinguishes quoting and semantics. SC2086 concerns splitting and globbing; quoting a Bash array expansion differs from quoting a scalar list. SC2206 requires deliberate array construction or a suitable read operation. SC2181 favors checking the command directly, SC2015 warns that an and/or chain can run its fallback after the middle command fails, and SC3010 identifies syntax unavailable in POSIX sh. Other examples address single-quote expansion and process searching.

Multi-file checks can run sequentially or in parallel. Cached results must be bound to the ShellCheck version, options, dialect, rc files, sourced contents, and main script; a main-file hash alone is insufficient. Pre-commit checks must inspect staged bytes, including partially staged files. Use NUL-delimited paths and exclude deleted files.

Installation examples include Homebrew, Debian-style packages, and building from source. Git hooks, GitHub Actions, and GitLab CI demonstrate automated checks, including failing a pipeline on findings. Editor integration provides immediate feedback. External-source settings help analyze sourced context where appropriate, while documented exclusions keep the chosen rule policy understandable.