https://github.com/afadesigns/zshellcheck
Static analysis and auto-fix for the setopts, hooks, and globs Bash never learned.
https://github.com/afadesigns/zshellcheck
ast format go lint scripts shell zsh zshell zshrc
Last synced: 4 days ago
JSON representation
Static analysis and auto-fix for the setopts, hooks, and globs Bash never learned.
- Host: GitHub
- URL: https://github.com/afadesigns/zshellcheck
- Owner: afadesigns
- License: mit
- Created: 2025-11-12T22:06:11.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-06-14T01:37:17.000Z (7 days ago)
- Last Synced: 2026-06-14T02:23:40.923Z (7 days ago)
- Topics: ast, format, go, lint, scripts, shell, zsh, zshell, zshrc
- Language: Go
- Homepage: https://github.com/afadesigns/zshellcheck
- Size: 25.5 MB
- Stars: 29
- Watchers: 1
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.bib
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
### The quiet linter for a quiet shell.
Static analysis and auto-fix for the setopts, hooks, and globs Bash never learned.
[](https://github.com/afadesigns/zshellcheck/actions/workflows/ci.yml)
[](https://github.com/afadesigns/zshellcheck/releases/latest)
[](https://github.com/marketplace/actions/zshellcheck-v1)
[](KATAS.md)
[](go.mod)
[](https://goreportcard.com/report/github.com/afadesigns/zshellcheck)
[](https://codecov.io/gh/afadesigns/zshellcheck)
[](https://securityscorecards.dev/viewer/?uri=github.com/afadesigns/zshellcheck)
[](https://www.bestpractices.dev/projects/12657)
[](https://slsa.dev)
[**Install**](INSTALL.md) · [**User guide**](docs/USER_GUIDE.md) · [**Katas**](KATAS.md) · [**Integrations**](INTEGRATIONS.md) · [**Roadmap**](ROADMAP.md) · [**Changelog**](CHANGELOG.md)
---
## See it in action
## Install
```bash
# macOS, Linux, WSL
curl -fsSL https://raw.githubusercontent.com/afadesigns/zshellcheck/main/install.sh | bash
```
```powershell
# Windows
irm https://raw.githubusercontent.com/afadesigns/zshellcheck/main/install.ps1 | iex
```
```bash
# Anywhere Go is installed
go install github.com/afadesigns/zshellcheck/cmd/zshellcheck@latest
```
`--uninstall` reverses any of them.
Native `.deb`, `.rpm`, `.apk`, and a multi-arch container at `ghcr.io/afadesigns/zshellcheck` ship on every release tag.
Pinning, cosign verification, and distro one-liners are in [INSTALL.md](INSTALL.md).
## Run
```bash
# Lint
zshellcheck path/to/script.zsh
# Write SARIF for GitHub Code Scanning
zshellcheck -severity warning -format sarif ./scripts > zshellcheck.sarif
# Preview every auto-fix as a unified diff
zshellcheck -diff path/to/script.zsh
# Apply the fixes
zshellcheck -fix path/to/script.zsh
```
Exits `0` on a clean run, `1` when anything was flagged.
`zshellcheck -h` lists every flag, grouped by intent.
Silence inline with `# noka: ZC1234`.
Bare `# noka` silences every kata on the line.
Trailing, preceding, and file-wide forms are documented in [USER_GUIDE.md](docs/USER_GUIDE.md#inline-noka-directives).
### CI/CD
The published action checks out your repository, installs a signed release binary, runs it, and fails the job on any finding.
Add the SARIF upload to surface results in the repository Security tab:
```yaml
# .github/workflows/lint.yml
name: zshellcheck
on: [push, pull_request]
permissions:
contents: read
security-events: write
jobs:
zshellcheck:
runs-on: ubuntu-latest
steps:
- uses: afadesigns/zshellcheck@latest
with:
args: -format sarif -severity warning ./scripts > zshellcheck.sarif
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: zshellcheck.sarif
```
Run it as a pre-commit hook instead:
```yaml
# .pre-commit-config.yaml
- repo: https://github.com/afadesigns/zshellcheck
rev: latest
hooks:
- id: zshellcheck
```
Pin `@latest` and `rev: latest` to a tag from [Releases](https://github.com/afadesigns/zshellcheck/releases/latest) for reproducible CI.
## Integrations
ZShellCheck is verified against widely used Zsh frameworks, plugin managers, plugins, and prompts on every release.
Each runs a parse-and-findings sweep: zero parser errors, zero crashes, and kata findings locked to a reviewed baseline.
The full catalog with file counts lives in [INTEGRATIONS.md](INTEGRATIONS.md).
| Category | Examples |
| :--- | :--- |
| Frameworks | [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh), [prezto](https://github.com/sorin-ionescu/prezto), [prezto-contrib](https://github.com/belak/prezto-contrib), [zephyr](https://github.com/mattmc3/zephyr), [zimfw](https://github.com/zimfw/zimfw) |
| Plugin managers | [antidote](https://github.com/mattmc3/antidote), [zinit](https://github.com/zdharma-continuum/zinit) |
| Plugins | [zsh-syntax-highlighting](https://github.com/zsh-users/zsh-syntax-highlighting), [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions), [zsh-autocomplete](https://github.com/marlonrichert/zsh-autocomplete), [atuin](https://github.com/atuinsh/atuin), [zsh-help](https://github.com/Freed-Wu/zsh-help) |
| Prompts | [powerlevel10k](https://github.com/romkatv/powerlevel10k), [spaceship-prompt](https://github.com/spaceship-prompt/spaceship-prompt), [starship](https://github.com/starship/starship), [gitstatus](https://github.com/romkatv/gitstatus) |
| Tooling | [fzf](https://github.com/junegunn/fzf), [fzf-tab](https://github.com/Aloxaf/fzf-tab), [fast-syntax-highlighting](https://github.com/zdharma-continuum/fast-syntax-highlighting) |
## Quality
Every release replays the linter over the pinned integration corpora and gates on two snapshots:
- Parser errors and crashes stay at zero.
- Kata findings match a reviewed baseline; a new finding on known-good code fails the build as a candidate false positive.
Semantic-preserving rewrites — added blank lines, comments, or variable renames — must not change which katas fire.
See the [local checks](CONTRIBUTING.md#local-checks) for the commands.
## Documentation
**Use it**
- [INSTALL.md](INSTALL.md) — install and uninstall paths for macOS, Windows, Linux, and Docker.
- [USER_GUIDE.md](docs/USER_GUIDE.md) — CLI reference, configuration, inline directives, FAQ.
- [KATAS.md](KATAS.md) — every kata with description, severity, and auto-fix status.
- [INTEGRATIONS.md](INTEGRATIONS.md) — verified Zsh frameworks, plugins, and prompts.
**Develop with it**
- [DEVELOPER.md](docs/DEVELOPER.md) — architecture, AST reference, kata authoring, auto-fix catalog.
- [REFERENCE.md](docs/REFERENCE.md) — governance, glossary, ShellCheck comparison.
- [ROADMAP.md](ROADMAP.md) — LSP, distribution channels, plugin system.
- [CHANGELOG.md](CHANGELOG.md) — per-release history.
**Contribute**
- [CONTRIBUTING.md](CONTRIBUTING.md) — workflow, signing requirements, kata standards.
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community expectations.
- [SECURITY.md](SECURITY.md) — vulnerability disclosure.
- [SUPPORT.md](SUPPORT.md) — bug, kata, and discussion routing.
## Contributing
Contributions of all kinds are welcome.
Start with [CONTRIBUTING.md](CONTRIBUTING.md).
- A question or idea? Open a [discussion](https://github.com/afadesigns/zshellcheck/discussions).
- A bug? File an [issue](https://github.com/afadesigns/zshellcheck/issues).
- A new kata? See the kata-authoring guide in [CONTRIBUTING.md](CONTRIBUTING.md).
## License
ZShellCheck is licensed under the [MIT License](LICENSE).
## Credits
Authored and maintained by Andreas Fahl ([@afadesigns](https://github.com/afadesigns)).
Inspired by [ShellCheck](https://www.shellcheck.net/).
[](https://afadesign.co)
[](https://github.com/afadesigns)
[](https://linkedin.com/in/andreasfahl)
[](https://instagram.com/afadesign.official)
[](https://facebook.com/andreas.fahl.5)