How to use the command shellcheck (with examples)

Shellcheck is a powerful static analysis tool for shell scripts. It helps to identify errors, deprecated/insecure features, and bad practices in shell scripts. This article will illustrate how to use the shellcheck command with various use cases.

Use case 1: Check a shell script

Code:

shellcheck path/to/script.sh

Motivation: By using the shellcheck command followed by the path to a shell script, you can quickly check the script for any errors or bad practices. This is useful to ensure the script is written correctly and follows best practices.

Explanation:

• shellcheck is the command itself.
• path/to/script.sh is the path to the shell script you want to check.

Example output:

In path/to/script.sh line 5:
echo $VAR
     ^-- SC2086: Double quote to prevent globbing and word splitting.

Use case 2: Check a shell script interpreting it as the specified shell dialect

Code:

shellcheck --shell sh path/to/script.sh

Motivation: Sometimes, the shebang (#!/bin/sh) at the top of the shell script may not accurately represent the intended shell dialect. By using the --shell flag, you can override the shebang and specify the shell dialect to interpret the script.

Explanation:

• --shell sh specifies that the script should be interpreted as the “sh” shell dialect.
• path/to/script.sh is the path to the shell script you want to check.

Example output:

In path/to/script.sh line 7:
[ -z "$VAR" ]
^-- SC2236: Use -n instead of ! -z.

Use case 3: Ignore one or more error types

Code:

shellcheck --exclude SC1009,SC1073 path/to/script.sh

Motivation: There may be certain error types that you want to exclude from the shellcheck analysis. By using the --exclude flag, you can specify one or more error types to ignore.

Explanation:

• --exclude SC1009,SC1073 specifies that the error types SC1009 and SC1073 should be ignored.
• path/to/script.sh is the path to the shell script you want to check.

Example output:

No output if SC1009 or SC1073 errors are present in path/to/script.sh.

Use case 4: Also check any sourced shell scripts

Code:

shellcheck --check-sourced path/to/script.sh

Motivation: When a shell script sources another shell script, it is important to ensure that the sourced script is also checked for errors and bad practices. By using the --check-sourced flag, shellcheck will analyze both the main script and any sourced scripts.

Explanation:

• --check-sourced flag indicates that shellcheck should also check any scripts sourced within the main script.
• path/to/script.sh is the path to the main shell script you want to check.

Example output:

In path/to/sourced-script.sh line 3:
echo $VAR
     ^-- SC2086: Double quote to prevent globbing and word splitting.

Use case 5: Display output in the specified format

Code:

shellcheck --format json path/to/script.sh

Motivation: By default, shellcheck outputs the analysis results in a human-readable format. However, in some cases, you may need the results in a different format for further processing. By using the --format flag, you can specify the desired format of the output.

Explanation:

• --format json specifies that the output should be in JSON format.
• path/to/script.sh is the path to the shell script you want to check.

Example output:

{
    "file": "path/to/script.sh",
    "line": 5,
    "column": 6,
    "level": "warning",
    "code": 2086,
    "message": "Double quote to prevent globbing and word splitting."
}

Use case 6: Enable one or more optional checks

Code:

shellcheck --enable=avoid-nullary-conditions path/to/script.sh

Motivation: By default, shellcheck performs a set of predefined checks. However, there may be additional checks available that are disabled by default. By using the --enable flag, you can enable one or more optional checks.

Explanation:

• --enable=avoid-nullary-conditions enables the optional check “avoid-nullary-conditions”.
• path/to/script.sh is the path to the shell script you want to check.

Example output:

In path/to/script.sh line 8:
if [ -n "$VAR" ];
                  ^-- SC2015: Note that comparisons should be lowercase for globbing (unless case-insensitive matching is intended).

Use case 7: List all available optional checks that are disabled by default

Code:

shellcheck --list-optional

Motivation: Sometimes, you may want to see a list of all available optional checks in shellcheck. This is useful to explore additional checks that can be enabled to enhance the analysis of shell scripts.

Explanation:

• --list-optional displays a list of all available optional checks.

Example output:

avoid-nullary-conditions
avoid-unquoted-environment-variables
...

Conclusion:

In this article, we have explored different use cases of the shellcheck command. Whether it is checking a shell script for errors, specifying the shell dialect, ignoring specific error types, analyzing sourced scripts, formatting the output, enabling optional checks, or listing available optional checks, shellcheck provides a comprehensive solution for static analysis of shell scripts. By utilizing these use cases, you can improve the quality and security of your shell scripts.