ShellCheck - A shell script static analysis tool

ShellCheck is a GPLv3 tool that gives warnings and suggestions for bash/sh shell scripts:

.

The goals of ShellCheck are

• To point out and clarify typical beginner's syntax issues that cause a shell to give cryptic error messages.

• To point out and clarify typical intermediate level semantic problems that cause a shell to behave strangely and counter-intuitively.

• To point out subtle caveats, corner cases and pitfalls that may cause an advanced user's otherwise working script to fail under future circumstances.

See the gallery of bad code for examples of what ShellCheck can help you identify!

How to use

There are a variety of ways to use ShellCheck!

On the web

Paste a shell script on http://www.shellcheck.net for instant feedback.

ShellCheck.net is always synchronized to the latest git commit, and is the simplest way to give ShellCheck a go. Tell your friends!

From your terminal

Run  shellcheck yourscript  in your terminal for instant output, as seen above.

In your editor

You can see ShellCheck suggestions directly in a variety of editors.

• Vim, through Syntastic:

.

• Emacs, through Flycheck:

.

• Sublime, through SublimeLinter.

• Atom, through Linter.

• Most other editors, through GCC error compatibility.

In your build or test suites

While ShellCheck is mostly intended for interactive use, it can easily be added to builds or test suites.

Use ShellCheck's exit code, or its CheckStyle compatible XML output. There's also a simple JSON output format for easy integration.

Installing

The easiest way to install ShellCheck locally is through your package manager.

On systems with Cabal (installs to  ~/.cabal/bin ):

normalcabal update
cabal install shellcheck
normal

On Debian based distros:

normalapt-get install shellcheck
normal

On Fedora based distros:

normaldnf install ShellCheck
normal

On OS X with homebrew:

normalbrew install shellcheck
normal

On OS X with MacPorts:

normalport install shellcheck
normal

On openSUSE:Tumbleweed:

normalzypper in ShellCheck
normal

On other openSUSE distributions:

add OBS devel:languages:haskell repository from https://build.opensuse.org/project/repositories/devel:languages:haskell

normalzypper ar http://download.opensuse.org/repositories/devel:/languages:/haskell/openSUSE_$(version)/devel:languages:haskell.repo
zypper in ShellCheck
normal

or use OneClickInstall - https://software.opensuse.org/package/ShellCheck

Compiling from source

This section describes how to build ShellCheck from a source directory. ShellCheck is written in Haskell and requires 2GB of RAM to compile.

Installing Cabal

ShellCheck is built and packaged using Cabal. Install the package  cabal-install  from your system's package manager (with e.g.  apt-get ,  yum ,  zypper  or  brew ).

On MacPorts, the package is instead called  hs-cabal-install , while native Windows users should install the latest version of the Haskell platform from https://www.haskell.org/platform/

Verify that  cabal  is installed and update its dependency list with

normal$ cabal update
normal

Compiling ShellCheck

 git clone  this repository, and  cd  to the ShellCheck source directory to build/install:

normal$ cabal install
normal

This will compile ShellCheck and install it to your  ~/.cabal/bin  directory.

Add this directory to your  PATH  (for bash, add this to your  ~/.bashrc ):

normalexport PATH="$HOME/.cabal/bin:$PATH"
normal

Log out and in again, and verify that your PATH is set up correctly:

normal$ which shellcheck
~/.cabal/bin/shellcheck
normal

On native Windows, the  PATH  should already be set up, but the system may use a legacy codepage. In  cmd.exe ,  powershell.exe  and Powershell ISE, make sure to use a TrueType font, not a Raster font, and set the active codepage to UTF-8 (65001) with  chcp :

normal> chcp 65001
Active code page: 65001
normal

In Powershell ISE, you may need to additionally update the output encoding:

normal> [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
normal

Running tests

To run the unit test suite:

normal$ cabal test
normal

Gallery of bad code

So what kind of things does ShellCheck look for? Here is an incomplete list of detected issues.

Quoting

ShellCheck can recognize several types of incorrect quoting:

normalecho $1                           # Unquoted variables
find . -name *.ogg                # Unquoted find/grep patterns
rm "~/my file.txt"                # Quoted tilde expansion
v='--verbose="true"'; cmd $v      # Literal quotes in variables
for f in "*.ogg"                  # Incorrectly quoted 'for' loops
touch $@                          # Unquoted $@
echo 'Don't forget to restart!'   # Singlequote closed by apostrophe
echo 'Don\'t try this at home'    # Attempting to escape ' in ''
echo 'Path is $PATH'              # Variables in single quotes
trap "echo Took ${SECONDS}s" 0    # Prematurely expanded trap
normal

Conditionals

ShellCheck can recognize many types of incorrect test statements.

normal[[ n != 0 ]]                      # Constant test expressions
[[ -e *.mpg ]]                    # Existence checks of globs
[[ $foo==0 ]]                     # Always true due to missing spaces
[[ -n "$foo " ]]                  # Always true due to literals
[[ $foo =~ "fo+" ]]               # Quoted regex in =~
[ foo =~ re ]                     # Unsupported [ ] operators
[ $1 -eq "shellcheck" ]           # Numerical comparison of strings
[ $n && $m ]                      # && in [ .. ]
[ grep -q foo file ]              # Command without $(..)
normal

Frequently misused commands

ShellCheck can recognize instances where commands are used incorrectly:

normalgrep '*foo*' file                 # Globs in regex contexts
find . -exec foo {} && bar {} \;  # Prematurely terminated find -exec
sudo echo 'Var=42' > /etc/profile # Redirecting sudo
time --format=%s sleep 10         # Passing time(1) flags to time builtin
while read h; do ssh "$h" uptime  # Commands eating while loop input
alias archive='mv $1 /backup'     # Defining aliases with arguments
tr -cd '[a-zA-Z0-9]'              # [] around ranges in tr
exec foo; echo "Done!"            # Misused 'exec'
find -name \*.bak -o -name \*~ -delete  # Implicit precedence in find
f() { whoami; }; sudo f           # External use of internal functions
normal

Common beginner's mistakes

ShellCheck recognizes many common beginner's syntax errors:

normalvar = 42                          # Spaces around = in assignments
$foo=42                           # $ in assignments
for $var in *; do ...             # $ in for loop variables
var$n="Hello"                     # Wrong indirect assignment
echo ${var$n}                     # Wrong indirect reference
var=(1, 2, 3)                     # Comma separated arrays
echo "Argument 10 is $10"         # Positional parameter misreference
if $(myfunction); then ..; fi     # Wrapping commands in $()
else if othercondition; then ..   # Using 'else if'
normal

Style

ShellCheck can make suggestions to improve style:

normal[[ -z $(find /tmp | grep mpg) ]]  # Use grep -q instead
a >> log; b >> log; c >> log      # Use a redirection block instead
echo "The time is `date`"         # Use $() instead
cd dir; process *; cd ..;         # Use subshells instead
echo $[1+2]                       # Use standard $((..)) instead of old $[]
echo $(($RANDOM % 6))             # Don't use $ on variables in $((..))
echo "$(date)"                    # Useless use of echo
cat file | grep foo               # Useless use of cat
normal

Data and typing errors

ShellCheck can recognize issues related to data and typing:

normalargs="$@"                         # Assigning arrays to strings
files=(foo bar); echo "$files"    # Referencing arrays as strings
printf "%s\n" "Arguments: $@."    # Concatenating strings and arrays.
[[ $# > 2 ]]                      # Comparing numbers as strings
var=World; echo "Hello " var      # Unused lowercase variables
echo "Hello $name"                # Unassigned lowercase variables
cmd | read bar; echo $bar         # Assignments in subshells
normal

Robustness

ShellCheck can make suggestions for improving the robustness of a script:

normalrm -rf "$STEAMROOT/"*            # Catastrophic rm
touch ./-l; ls *                 # Globs that could become options
find . -exec sh -c 'a && b {}' \; # Find -exec shell injection
printf "Hello $name"             # Variables in printf format
for f in $(ls *.txt); do         # Iterating over ls output
export MYVAR=$(cmd)              # Masked exit codes
normal

Portability

ShellCheck will warn when using features not supported by the shebang. For example, if you set the shebang to  #!/bin/sh , ShellCheck will warn about portability issues similar to  checkbashisms :

normalecho {1..$n}                     # Works in ksh, but not bash/dash/sh
echo {1..10}                     # Works in ksh and bash, but not dash/sh
echo -n 42                       # Works in ksh, bash and dash, undefined in sh
trap 'exit 42' sigint            # Unportable signal spec
cmd &> file                      # Unportable redirection operator
read foo < /dev/tcp/host/22      # Unportable intercepted files
foo-bar() { ..; }                # Undefined/unsupported function name
[ $UID = 0 ]                     # Variable undefined in dash/sh
local var=value                  # local is undefined in sh
normal

Miscellaneous

ShellCheck recognizes a menagerie of other issues:

normalPS1='\e[0;32m\$\e[0m '            # PS1 colors not in \[..\]
PATH="$PATH:~/bin"                # Literal tilde in $PATH
rm “file”                         # Unicode quotes
echo "Hello world"                # Carriage return / DOS line endings
var=42 echo $var                  # Expansion of inlined environment
#!/bin/bash -x -e                 # Common shebang errors
echo $((n/180*100))               # Unnecessary loss of precision
ls *[:digit:].txt                 # Bad character class globs
sed 's/foo/bar/' file > file       # Redirecting to input
normal

Testimonials

At first you're like "shellcheck is awesome" but then you're like "wtf are we still using bash"

Alexander Tarasikov, via Twitter

Reporting bugs

Please use the GitHub issue tracker for any bugs or feature suggestions:

https://github.com/koalaman/shellcheck/issues

Contributing

Please submit patches to code or documentation as GitHub pull requests!

Contributions must be licensed under the GNU GPLv3. The contributor retains the copyright.

Copyright

ShellCheck is licensed under the GNU General Public License, v3. A copy of this license is included in the file LICENSE.

Copyright 2012-2015, Vidar 'koala_man' Holen and contributors.

Happy ShellChecking!