Great Gradle Goodies: Code Formatting with Spotless

Recently I had the opportunity to try some new (to me) features in my favourite build tool Gradle, I’d like to share what I learned about these. Today: Code formatting with Spotless.

To be honest, I hated it at first. The idea behind Spotless is that the build tool enforces a comprehensive set of code formatting rules. If I use the wrong number of spaces or tabs for indentation, the build will fail — so far, so Checkstlye.

The cool thing about Spotless, however, is that it doesn’t just enforce the rules; it can also automatically apply them to the codebase. This solves the common issue of differing opinions between developers and inconsistent IDE formatter configurations, while also ensuring that style violations are fixed automatically.

This also solves the problem of code reviews where there reviewer is hardly able to see the actual change between all the reformatting.

In my experience, most people can debate indentation or line length for hours, but as soon as there’s a “good enough” standard, they stop caring about it. 🤷

How does it work?

We can add the Spotless Gradle plugin to the build file. There are a lot of configuration options you can find in the plugin’s GitHub repository. But unlike Checkstyle, we don’t need to configure the details, but can rely on comprehensive formatters.

For example, to format all Kotlin code in my project, I simply add

spotless {
  kotlin {
    ktfmt().googleStyle()
  }
}

great-gradle-goodies/build.gradle.kts at main · mkutz/great-gradle-goodies

By default the check task will automatically include spotlessCheck, which will fail the build if any violations are found.

Preventing CI failures

To avoid that frustrating moment when your continuous integration (CI) build fails after just a few seconds due to formatting issues, we can take some precautions:

1. Use IDE plugins — Spotless plugins are available for IntelliJ IDEA and VS Code.
2. Set up a Git pre-commit hook — This is a more universal (but somewhat debatable) approach:

#!/bin/sh

staged_files=$(git diff --staged --name-only)

echo "🧹 Formatting code in staged files…"
./gradlew spotlessApply
for file in $staged_files; do
  if test -f "$file"; then
    git add "$file"
  fi
done

exit 0

This script automatically runs spotlessApply before each commit and re-adds the modified files. So whenever you commit something, Git triggers Gradle to reformat the changed files in the background.

Is this controversial?

Some developers argue that this approach alters files after they’ve been reviewed, potentially making unnoticed changes. Personally, I’ve had nothing but good experiences with it.

All the files!

For “hard” code, like Kotlin, Java, C++ etc. this is really great to settle unproductive debates and reach a truely consistently formatted code base. But Spotless can also care of things like YAML, XML, JSON, Markdown, and even fix the order of things in a pom.xml file! Checkout the README.md for more.