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.
By default the formatter re-indents every line from the parse tree, trims trailing whitespace and collapses runs of blank lines; spacing within lines and line wrapping are opt-in (formatting).
$ groovyfmt --check --diff build.gradle
--- a/build.gradle
+++ b/build.gradle
@@ -1,8 +1,8 @@
dependencies {
- implementation 'org.slf4j:slf4j-api:2.0.9'
+ implementation 'org.slf4j:slf4j-api:2.0.9'
}
tasks.register('hello') {
- doLast {
-println 'hello'
- }
+ doLast {
+ println 'hello'
+ }
}
would reformat 1 of 1 files$ 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 (measured on 0.5). npm-groovy-lint didn't finish in 15 minutes (benchmark).
- Compared. Spotless formats Groovy with the Eclipse formatter (greclipse), on the JVM inside a Gradle or Maven build. npm-groovy-lint runs CodeNarc on a JVM. groovyfmt runs without a JVM or a build.
- Broad. 99.6% of a 23,766-file corpus (grails-core, gradle, spock, nextflow, Jenkins pipelines) parses (coverage).
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 compiler
docker run --rm -v "$PWD:/src" -w /src ghcr.io/costajohnt/groovyfmt --checkPrebuilt binaries for Linux (static musl), macOS and Windows, each with a .sha256, are on every release. See also Windows.
In a Gradle build, the Gradle plugin adds groovyfmtCheck and groovyfmtLint to check: id 'io.github.costajohnt.groovyfmt' version '0.30.2'.
| 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 the rules mark fixable (imports, semicolons, removed Gradle syntax and more), 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, *.gvy, *.gy, *.gsh, Jenkinsfiles and groovy #! scripts. Kotlin DSL scripts (build.gradle.kts) are not handled. Command line has every option.
.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
UnnecessaryGString = true// groovyfmt: off / // groovyfmt: on protect a region. More in Formatting and Configuration.
84 rules, 60 on by default (groovyfmt --rules).
- General rules follow CodeNarc names.
groovyfmt --import-codenarc <config>converts a CodeNarc or npm-groovy-lint config. - Jenkinsfile, Gradle and Spock rules catch mistakes that otherwise surface only when a build runs, such as Gradle 9 and Groovy 4 removals.
// groovyfmt-ignoreor@SuppressWarningssuppress a report;--write-baselinelets you adopt lint gradually.
$ groovyfmt --lint
build.gradle:3:1: GradleRemovedApi: The project property `sourceCompatibility` was removed in Gradle 9.0 with the plugin conventions; use java { sourceCompatibility = ... }Lint has every rule. Output formats covers JSON, SARIF and GitHub annotations.
- uses: actions/checkout@v5
- uses: costajohnt/groovyfmt@v0.30.2 # runs groovyfmt --check --output-format github
- run: groovyfmt --lint --output-format githubpre-commit:
repos:
- repo: https://github.com/costajohnt/groovyfmt
rev: v0.30.2
hooks:
- id: groovyfmt # or groovyfmt-check
- id: groovyfmt-lintCI covers action inputs, SARIF upload, --strict and the Gradle plugin.
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.
See Development for tests, the corpus workflow, grammar changes and releases.
MIT
