ZShellCheck VS Code Extension
Run zshellcheck inside VS Code and publish diagnostics for Zsh files such as .zsh, .zshrc, .zshenv, .zprofile, and .zsh-theme.
What it does
- lints matching Zsh files with
zshellcheck -format json
- maps ZShellCheck severities into VS Code diagnostics
- supports automatic linting on save or type, plus a manual lint command
- lets you choose the executable path, minimum severity, custom args, and matching file patterns
Requirements
Install zshellcheck somewhere VS Code can execute it:
go install github.com/afadesigns/zshellcheck/cmd/zshellcheck@latest
or use the upstream install script:
curl -fsSL https://raw.githubusercontent.com/afadesigns/zshellcheck/main/install.sh | bash
If the binary is not on PATH, set zshellcheck.executablePath in your VS Code settings.
Extension settings
| Setting |
Purpose |
zshellcheck.enable |
Enable or disable diagnostics. |
zshellcheck.executablePath |
Path or command name for zshellcheck. |
zshellcheck.run |
Run on save, on type, or only manually. |
zshellcheck.minimumSeverity |
Passes the selected severity threshold to zshellcheck. |
zshellcheck.customArgs |
Extra CLI flags to append before the file path. |
zshellcheck.filePatterns |
Glob patterns used to identify Zsh files. |
zshellcheck.ignoreFileSchemes |
URI schemes the extension should skip. |
zshellcheck.useWorkspaceRootAsCwd |
Run from the workspace folder instead of the file directory. |
Development
npm install
npm run build
npm run format
Open the folder in VS Code and use the Run Extension launch configuration with F5. This starts an Extension Development Host. Do not run dist/extension.js directly with the plain Node debugger, because the vscode module only exists inside the extension host.
Tests
The repo includes an automated extension test suite that runs against a fake zshellcheck executable. It covers activation, file matching, diagnostics publication, and severity-threshold behavior.
npm test
Packaging
Create a local VSIX with:
npm run package
This packages with the Marketplace metadata in package.json. Publish with vsce after authenticating your publisher account.
CI
GitHub Actions is configured in .github/workflows/ci.yml to run:
npm run format:checknpm run buildnpm run check-typesnpm test
