ShellCheck for Visual Studio Code

Integrates ShellCheck into VS Code, a linter for Shell scripts.

Quick start

Extension GIF

Disclaimer

This VS Code extension requires shellcheck (the awesome static analysis tool for shell scripts) to work.

Precompiled shellcheck binaries are bundled in this extension for these platforms:

Linux (x86_64, arm, arm64)
macOS (x86_64, arm64)
Windows (x86_64, arm)

Requirements

Run Install Extension command from Command Palette.
Search and choose shellcheck.

Troubleshooting

If shellcheck seems not working, a helper command ShellCheck: ShellCheck: Collect Diagnostics For Current Document from the Command Palette is provided to help troubleshooting.

Options

There are various options that can be configured by making changes to your user or workspace preferences.

Default options are:

{
  "shellcheck.enable": true,
  "shellcheck.enableQuickFix": true,
  "shellcheck.run": "onType",
  "shellcheck.executablePath": "", // Priority: user defined > bundled shellcheck binary > "shellcheck"
  "shellcheck.exclude": [],
  "shellcheck.customArgs": [],
  "shellcheck.ignorePatterns": {
    "**/*.xonshrc": true,
    "**/*.xsh": true,
    "**/*.zsh": true,
    "**/*.zshrc": true,
    "**/zshrc": true,
    "**/*.zprofile": true,
    "**/zprofile": true,
    "**/*.zlogin": true,
    "**/zlogin": true,
    "**/*.zlogout": true,
    "**/zlogout": true,
    "**/*.zshenv": true,
    "**/zshenv": true,
    "**/*.zsh-theme": true
  },
  "shellcheck.ignoreFileSchemes": ["git", "gitfs", "output"]
}

`shellcheck.ignorePatterns`

The shellcheck.ignorePatterns works exactly the same as search.exclude, read more about glob patterns here

For example:

{
  "shellcheck.ignorePatterns": {
    "**/*.zsh": true,
    "**/*.zsh*": true,
    "**/.git/*.sh": true,
    "**/folder/**/*.sh": true
  }
}

Fix all errors on save

The auto-fixable errors can be fixed automatically on save by using the following configuration:

{
  "editor.codeActionsOnSave": {
    "source.fixAll.shellcheck": true
  }
}

Alternatively, you can fix all errors on demand by running the command Fix All in the VS Code Command Palette.

Lint onType or onSave

By default the linter will lint as you type. Alternatively, set shellcheck.run to onSave if you want to lint only when the file is saved (works best if auto-save is on).

{
  "shellcheck.run": "onType" // also: "onSave"
}

Excluding Checks

By default all shellcheck checks are performed and reported on as necessary. To globally ignore certain checks in all files, add the "SC identifiers" to shellcheck.exclude. For example, to exclude SC1017:

{
  "shellcheck.exclude": ["1017"]
}

Using Docker version of shellcheck

In order to get it to work, you need a "shim" script, and then, just remember, do not try to construct command line arguments for shellcheck yourself.

Here is a simple "shim" script to get start with (See discussion: #24):

#!/bin/bash

exec docker run --rm -i -v "$PWD:/mnt:ro" koalaman/shellcheck:latest "$@"

For example, you can place it at shellcheck.sh in the root of your workspace and ensure that it have execution permission with chmod +x shellcheck.sh. And then, you can configure the extension to use it:

// .vscode/settings.json
{
  // use the shim as shellcheck executable
  "shellcheck.executablePath": "${workspaceFolder}/shellcheck.sh",

  // you may also need to turn this option on, so shellcheck in the container
  // can access all the files in the workspace
  "shellcheck.useWorkspaceRootAsCwd": true
}

Advanced usage

Integrating other VS Code extensions

This extension provides a small API, which allows other VS Code extensions to interact with the ShellCheck extension. For details, see API.md.

Acknowledgements

This extension is based on @hoovercj's Haskell Linter.

Contributors

LICENSE

This extension is licensed under the MIT license.

Bundled shellcheck binaries are licensed under GPLv3.

ShellCheck

Timon Wong