groovyfmt
v0.20.3
Published
Fast formatter and linter for Groovy, Gradle build scripts, and Jenkinsfiles
Maintainers
Readme
A fast formatter and linter for Groovy, Gradle build scripts and Jenkinsfiles. One static binary, no JVM. Written in Rust on a tree-sitter grammar.
$ groovyfmt --check
Jenkinsfile
test/groovy/BaseTest.groovy
...
would reformat 27 of 27 files
$ groovyfmt
reformatted 27 of 27 files
$ groovyfmt --lint
test/groovy/BaseTest.groovy:2:1: UnusedImport: The [mock.CurrentBuild] import is never referenced (fixable)
...
10 violations in 27 files (UnnecessaryGroovyImport 1, UnusedImport 9)Run on jenkins-infra/pipeline-library.
- Safe. Formatting changes whitespace only by default. Output is re-parsed and token-compared with the input, and a file is left untouched if anything else would change. Files that don't parse are never touched.
- Fast. Formats the 635-file spock repo in 0.19 s. npm-groovy-lint didn't finish in 15 minutes (benchmark).
- Broad. 99.6% of a 23,766-file corpus (grails-core, gradle, spock, nextflow, Jenkins pipelines) parses (coverage).
Install
brew install costajohnt/tap/groovyfmt # macOS, Linux
npm install --save-dev groovyfmt # or: npx groovyfmt --check
cargo install --locked groovyfmt # Rust 1.90+ and a C compilerPrebuilt binaries for Linux (static musl), macOS and Windows, each with a .sha256, are on every release. See also Windows. Not published yet: the Gradle plugin on the Gradle Plugin Portal (it works from a checkout) and a Docker image.
Usage
| Command | Does |
|---|---|
| groovyfmt | format files under the current directory in place |
| groovyfmt --check | list files that would change, exit 1 if any (--diff to show them) |
| groovyfmt --lint | report lint violations, exit 1 if any |
| groovyfmt --lint --fix | fix what can be fixed (imports, semicolons), report the rest |
| groovyfmt --syntax | report parse errors |
| groovyfmt --explain <Rule> | explain a lint rule |
| groovyfmt --suggest-style | suggest indent settings that fit existing code |
Exit status: 0 clean, 1 something to fix, 2 error. Picks up *.groovy, *.gradle, Jenkinsfiles and groovy #! scripts. Command line has every option.
Configuration
.groovyfmt.toml, found by walking up from each file:
indent = 4
continuation_indent = 8 # default: same as indent
use_tabs = false
normalize_spacing = false # also fix spaces between tokens
max_line_length = 120 # wrap long lines where safe (default: off)
exclude = ["generated/**"]
[lint] # turn rules on or off// groovyfmt: off / // groovyfmt: on protect a region. More in Formatting and Configuration.
Linting
81 rules, 57 on by default (groovyfmt --rules). General rules follow CodeNarc names; Jenkinsfile, Gradle and Spock rules catch mistakes that otherwise surface only when a build runs. Coming from CodeNarc or npm-groovy-lint? groovyfmt --import-codenarc <config> converts your config. Suppress with // groovyfmt-ignore or @SuppressWarnings; adopt gradually with --write-baseline.
Lint has every rule. Output formats covers JSON, SARIF and GitHub annotations.
CI
- uses: actions/checkout@v5
- uses: costajohnt/[email protected] # runs groovyfmt --check --output-format github
- run: groovyfmt --lint --output-format githubpre-commit:
repos:
- repo: https://github.com/costajohnt/groovyfmt
rev: v0.20.3
hooks:
- id: groovyfmt # or groovyfmt-check
- id: groovyfmt-lintCI covers action inputs, SARIF upload, --strict and the Gradle plugin.
Editors and agents
groovyfmt --lsp is a language server: formatting, parse errors and lint as you type, fixes as code actions. Extensions for VS Code and JetBrains IDEs; setup for Neovim, Helix and Zed in Editors.
Coding agents editing a Jenkinsfile have no compiler to catch a broken file. groovyfmt --syntax <file> answers in milliseconds. Coding agents has an AGENTS.md snippet and a Claude Code hook.
Contributing
See Development for tests, the corpus workflow, grammar changes and releases.
License
MIT
