The Shellcheck Plugin

The Shellcheck plugin performs quality checks on your project’s Shell source files using Shellcheck and generates reports from these checks.

Usage

To use the Shellcheck plugin, include the following in your build script:

plugins {
    id("com.felipefzdz.gradle.shellcheck") version "1.5.0"
}

The plugin adds a task to the project called shellcheck that performs the quality checks.

Note that in order to be portable and repeatable Shellcheck will run:

• Through a Docker container

• A configurable Shellcheck version

This implies that no dependencies are required on the executing machine, except for Docker itself.

Tasks

The Shellcheck plugin adds a task called shellcheck to the project.

Extension

shellcheck {
    sources = files("src/shellScripts", "src/moreScripts")
    sourceFiles = fileTree("scr/shellScripts") {
       includes("**/*.txt")
    }
    isIgnoreFailures = true
    isShowViolations = true
    shellcheckVersion = "v0.7.1"
    severity = "error"
    isUseDocker = true
    shellcheckBinary = "/usr/local/bin/shellcheck"
    installer = "brew"
    additionalArguments = "-x"
    workingDir = file("${buildDir}/scripts")
}

• sources - Folders where the shell scripts are located. It will search recursively matching .sh, .bash, .bash_login, .bash_logout, .bash_profile, .bashrc and .ksh files. Don’t set sourceFiles if you set sources.

• sourceFiles - Files to check with shellcheck. Using sourceFiles gives complete control over what files are checked using shellcheck.

• isIgnoreFailures - Whether to allow the build to continue if there are warnings. Defaults to false.

• isShowViolations - Whether rule violations are to be displayed on the console. Defaults to true.

• isUseDocker - Whether to use docker image (true) or local shellcheck binary (false). Defaults to true.

• shellcheckVersion - By default v0.7.1. Ignored if useDocker is false.

• shellcheckBinary - /path/to/shellcheck binary. Defaults to /usr/local/bin/shellcheck. Ignored if useDocker is true.

• installer - for a machine without Docker or the shellcheck binary being installed, provide the installer to be used. It supports the ones mentioned here under the Unix family. By default, none. Ignored if useDocker is true.

• severity - Minimum severity of errors to consider (error, warning, info, style). Defaults to style.

• additionalArguments - Additional arguments to pass to shellcheck.

• workingDir - Sets the working directory to run shellcheck from. Defaults to the project directory.

Customizing the HTML report

The HTML report generated by the Shellcheck task can be customized using a XSLT stylesheet, for example to highlight specific errors or change its appearance:

tasks.withType<Shellcheck>().configureEach {
    reports {
        xml.isEnabled = false
        txt.isEnabled = false
        html.isEnabled = true
        html.stylesheet = resources.text.fromFile("config/xsl/shellcheck-custom.xsl")
    }
}

XML generated report comes from shellcheck -f checkstyle, therefore you can get inspiration from a sample Checkstyle stylesheet.

TXT generated report comes from shellcheck -f tty.

Performance

Using Docker is slower than using a locally installed shellcheck binary since there is a cost to starting up a Docker container.

Additionally, using sourceFiles is slower than using sources (particularly when also using Docker). When script files are provided using sourceFiles, shellcheck is invoked for each file. In contrast, when using sources, shellcheck is invoked only once for all the scripts found in the directories identified by sources.

Despite the performance penalty, sourceFiles is useful if you need to check scripts which do not have a standard shell extension (or no extension at all). Using sourceFiles also avoids issues related to command length (if you have a lot of shell files to check, using sources could fail because the resulting shellcheck command could exceed the shell’s maximum command length).

Testing

With the addition of non Docker mode where a binary is supposed to be previously installed in the executing machine, we introduced a source of non portability of the automated tests. To mitigate so, ShellcheckBinaryPluginFuncTest will be ignored unless an env var called SHELLCHECK_PATH will be present.