LinuxCommandLibrary

shellcheck

Analyze shell scripts for errors

TLDR

Check a shell script

$ shellcheck [path/to/script.sh]
copy

Check a shell script interpreting it as the specified shell dialect (overrides the shebang at the top of the script)
$ shellcheck [[-s|--shell]] [sh|bash|dash|ksh] [path/to/script.sh]
copy

Ignore one or more error types
$ shellcheck [[-e|--exclude]] [SC1009,SC1073,...] [path/to/script.sh]
copy

Also check any sourced shell scripts
$ shellcheck [[-a|--check-sourced]] [path/to/script.sh]
copy

Display output in the specified format (defaults to tty)
$ shellcheck [[-f|--format]] [tty|checkstyle|diff|gcc|json|json1|quiet] [path/to/script.sh]
copy

Enable one or more [o]ptional checks
$ shellcheck [[-o|--enable]] [add-default-case,avoid-nullary-conditions,...] [path/to/script.sh]
copy

List all available optional checks that are disabled by default
$ shellcheck --list-optional
copy

Adjust the level of severity to consider (defaults to style)
$ shellcheck [[-S|--severity]] [error|warning|info|style] [path/to/script.sh]
copy

SYNOPSIS

shellcheck [OPTIONS] [FILE ...]
shellcheck [OPTIONS] --shell=SH -

FILE ...: One or more shell script files to analyze.
-: Reads script content from standard input.

PARAMETERS

--external-sources
    Include sourced files in the analysis. By default, sourced files are ignored.

--format=FMT
    Specify the output format. Common formats include tty (default, human-readable), gcc (for integration with compilers/IDEs), json, checkstyle, and quiet.

--severity=LEVEL
    Set the minimum severity level to report. Levels are error, warning, info, and style. Defaults to info.

--enable=CODE
    Enable specific checks by their SC code (e.g., SC2000). Can be a comma-separated list or specified multiple times.

--disable=CODE
    Disable specific checks by their SC code (e.g., SC2039). Can be a comma-separated list or specified multiple times.

--shell=SH
    Explicitly specify the shell dialect to use for analysis (sh, bash, dash, ksh). If omitted, Shellcheck tries to guess from the shebang.

--color=WHEN
    Control output coloring. Options are always, auto (default), or never.

--version
    Display the Shellcheck version information.

--help
    Show the help message and exit.

DESCRIPTION

Shellcheck is a powerful static analysis tool designed to find common mistakes and bad practices in shell scripts. It supports various shell dialects including bash, dash, and ksh.

By analyzing scripts without executing them, Shellcheck helps identify a wide range of issues, from simple syntax errors and missing quotes to more complex logical flaws, potential security vulnerabilities (like command injection opportunities), and violations of best practices. It provides detailed explanations for each detected issue, often including suggested fixes and links to its comprehensive wiki for further information. This makes it an invaluable asset for improving script quality, reliability, and maintainability. Shellcheck is widely used by developers for proactive error detection and can be seamlessly integrated into development workflows and Continuous Integration/Continuous Deployment (CI/CD) pipelines.

CAVEATS

  • Shellcheck performs static analysis, meaning it does not execute the script. Therefore, it cannot detect runtime errors or issues that depend on specific execution conditions or external program outputs.
  • While highly accurate, it can occasionally produce false positives for complex or highly dynamic shell constructs that are difficult to analyze without execution.
  • It primarily focuses on common pitfalls and best practices; it might not catch every possible logical flaw or adherence to highly specialized coding standards.
  • Effective use often requires understanding the specific SC codes reported, although Shellcheck's output and wiki links are excellent resources.

ERROR CODES AND EXPLANATIONS

Each issue identified by Shellcheck is assigned a unique SC code (e.g., SC2086 for 'Double quote to prevent globbing and word splitting'). Shellcheck's output not only provides this code but also a concise description and, crucially, a direct link to its wiki page (e.g., https://www.shellcheck.net/wiki/SC2086). These wiki pages offer in-depth explanations, common scenarios, and concrete examples of how to fix the reported issue, making Shellcheck an invaluable learning resource for shell scripting.

EDITOR INTEGRATION

Shellcheck can be seamlessly integrated into many popular code editors and Integrated Development Environments (IDEs), including VS Code, Vim, Emacs, and others. This integration provides real-time feedback as you type, highlighting potential issues directly within your editor. This immediate visual cue significantly speeds up the development process by allowing developers to catch and fix errors proactively, often before even attempting to run the script.

HISTORY

Shellcheck was created by Koichi Sakata and first released in 2012. It is notably implemented in Haskell, a functional programming language, which contributes to its robust parsing capabilities and reliability. The project was conceived to fill a significant gap in the shell scripting ecosystem by providing a reliable and comprehensive tool to catch common errors and encourage best practices, similar to how linters exist for other programming languages. Its intuitive interface, clear error messages, and detailed explanations quickly led to its widespread adoption within the Unix/Linux communities and integration into professional development workflows.

SEE ALSO

bash(1): The GNU Bourne-Again SHell, a common target for Shellcheck's analysis., sh(1): The standard command language interpreter, representing POSIX-compliant shell scripting., dash(1): A lightweight, POSIX-compliant shell often used for system scripts., ksh(1): The KornShell, another powerful and widely used shell environment., lint(1): A general term for static analysis tools; Shellcheck is a specialized linter for shell scripts.

Copied to clipboard