How to improve and debug your shell scripts with ShellCheck

ShellCheck is a free and open source static analysis tool which can be used to check and improve shell scripts. It is able to highlight both common and edge-case errors, and suggest the appropriate fixes. ShellCheck can be used as an online or system utility, but can also be integrated as a linter in various text editors.

In this tutorial we learn how to install and use ShellCheck on some of the most used Linux distributions, and how to integrate it in Vim and Visual Studio Code.  

In this tutorial you will learn:

  • How to install ShellCheck on some of the most used Linux distributions
  • How to check a shell script using ShellCheck
  • How to use the online version of ShellCheck
  • How to integrate ShellCheck in Vim and Visual Studio Code
How to improve and debug your shell scripts with shellcheck
How to improve and debug your shell scripts with ShellCheck
 

Category Requirements, Conventions or Software Version Used
System Distribution independent
Software ShellCheck
Other Administrative privileges to install software
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user

Installation

First of all, let’s install ShellCheck on our favorite Linux-based system. This is a very easy task, since the utility is packaged in the software repositories of the most used distributions. All we have to do is to use the appropriate package manager. On Fedora, for example, we would use dnf:

$ sudo dnf install ShellCheck

On Debian, and Debian-based system, instead, we would use apt:

$ sudo apt install shellcheck

On Archlinux, we use pacman:

$ sudo pacman -S shellcheck

Basic usage

Using ShellCheck is very simple. Most of the time, we just invoke it and pass the path of the script we want to check as argument. Let’s an example. In the following snippet, you can clearly see we omitted to quote a shell variable. This is a common mistake which, depending on the circumstances, can be dangerous:

  1. #!/bin/bash
  2.  
  3. text=”this is the text”
  4.  
  5. echo $text



We save the code above in a file called script.sh. To check it using ShellCheck we simply pass it as argument to the utility:

$ shellcheck script.sh

The result of the command above is the following:

In script.sh line 5:
echo $text
     ^---^ SC2086 (info): Double quote to prevent globbing and word splitting.

Did you mean: 
echo "$text"

For more information:
  https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent globbing ...

As you can see the error is correctly found and highlighted. The error is identified by a specific code, which in this case is SC2086, and a brief description is provided for it. More information can be retrieved by just clicking on the provided link which points to the corresponding ShellCheck Wiki page:

ShellCheck Wiki
The ShellCheck Wiki page about error SC2086

ShellCheck, among the other things, is also able to detect “bashisms”: non-standard features that are specific to the Bash shell. We are warned when we don’t explicitly specify Bash as the shell interpreter. For instance, take a look at this example:

  1. #!/bin/sh
  2.  
  3. # Prints the current date and time
  4. function now() {
  5.   date ‘+%Y/%m/%d %H:%M’
  6. }

If we run ShellCheck against this code, we receive the following output:

In date.sh line 4:
function now() {
^-- SC2112 (warning): 'function' keyword is non-standard. Delete it.

For more information:
  https://www.shellcheck.net/wiki/SC2112 -- 'function' keyword is non-standar...

Although there are not mistakes in the code, ShellCheck warns us because we used the “function” keyword to create a function: this syntax is bash-specific, but we didn’t explicitly specified bash as the script interpreter (we used /bin/sh which in some distributions, like Ubuntu, is a symbolic link which points to the “dash” shell).

Using the online version of ShellCheck

If for some reasons we can’t or we don’t want to install ShellCheck on our system, we can check our scripts online, by using the web version of ShellCheck. All we have to do is to paste our code in the online editor. Eventual warnings will appear below it:

ShellCheck Web
ShellCheck Web



As you can see in the screenshot above, a sign will appear also on the lines where warnings or errors are found. This behavior can be replicated on most texts editor by integrating ShellCheck as a linter. Let’s see how.

Integrating ShellCheck into text editors

ShellCheck can be integrated in some of the most used text editors as a linter. Let’s see some examples.

Integrating ShellCheck into Vim

To use ShellCheck as a linter directly when using Vim, we first need to install a linting plugin. One of the most popular and modern options, at the time of writing, is ALE. The plugin makes use of the asynchronous features of Neovim and Vim >= 8. There are many ways to install it, using one of the many Vim plugin managers or the native Vim plugin loading system.



Once both the Vim linter plugin and ShellCheck are installed, we can visualize warnings and suggestions directly from the editor interface:

ShellCheck inside Vim
ShellCheck inside Vim

Integrating ShellCheck into Visual Studio Code

Visual Studio Code is a text editor created by Microsoft and developed using the Electron framework.  It is based on an open source project, Code-OSS, and thanks to its large plugin ecosystem it can be easily turned into an IDE for the most used programming languages (Javascript above all). To integrate ShellCheck into Visual Studio Code all we have to do is to search for the “shellcheck” plugin directly from the editor interface, and click on the “install” button:

ShellCheck and VScode
The ShellCheck plugin can be installed directly from the Visual Studio Code marketplace

ShellCheck can also be integrated into other text editors, like Sublime Text and Emacs: instructions can be found in the dedicated section of the ShellCheck README.

Conclusions

In this tutorial we saw how to install and use ShellCheck to debug and improve our shell scripts. ShellCheck is a static analysis tool which can be easily installed in all the most used Linux distributions and can be used from the command line or from a variety of text editors via their dedicated plugins. In this tutorial we saw how to use ShellCheck as a standalone tool from the command line, and how to integrate it into Vim and Visual Studio Code.



Comments and Discussions
Linux Forum