Spotless — Multi-Language Code Formatter for JVM Projects

Introduction

Spotless is a general-purpose formatting tool that integrates into Gradle and Maven build pipelines. It ensures every file in a project adheres to a declared style, catching formatting drift before code reaches review. Unlike language-specific linters, Spotless handles Java, Kotlin, Groovy, Scala, SQL, JSON, YAML, Markdown, and more through a single plugin.

What Spotless Does

• Enforces consistent code style across an entire repository via build-time checks
• Supports multiple formatters per language including google-java-format, ktlint, Prettier, and Eclipse JDT
• Runs as a Gradle plugin or Maven plugin with identical configuration semantics
• Provides incremental formatting that only re-checks changed files for fast CI
• Formats non-JVM files like SQL, CSS, and Markdown alongside Java sources

Architecture Overview

Spotless operates as a build plugin that registers formatting steps per file type. Each step declares a set of source files via include/exclude patterns and a chain of formatter functions. On spotlessCheck, the plugin reads each file, pipes it through its formatter chain, and fails the build if the output differs from the original. On spotlessApply, it writes the formatted output back. The Gradle plugin supports up-to-date checks so unchanged files are skipped on repeated runs.

Self-Hosting & Configuration

• Add the Spotless Gradle plugin: id 'com.diffplug.spotless' version '7.x' in plugins {} block
• For Maven, add spotless-maven-plugin under <build><plugins>
• Configure per-language blocks like java { googleJavaFormat() } or kotlin { ktlint() }
• Set ratchetFrom 'origin/main' to only format files changed since a base branch
• Integrate into CI by running spotlessCheck as a required build step

Key Features

• Supports 15+ languages and file types from a single plugin
• Pluggable formatter backends — swap google-java-format for palantir-java-format in one line
• Ratchet mode limits formatting to changed files, easing adoption in large codebases
• License header management inserts or updates copyright headers automatically
• Works with both Gradle and Maven, covering the two dominant JVM build systems

Comparison with Similar Tools

• google-java-format — Java-only formatter; Spotless wraps it and adds multi-language support
• ktlint — Kotlin-only linter/formatter; Spotless can delegate to ktlint while also covering Java files
• Prettier — Focuses on JS/TS/CSS; Spotless can call Prettier for frontend files inside a JVM project
• Checkstyle — Reports style violations but does not auto-fix; Spotless auto-formats in place
• EditorConfig — Declares style preferences for editors; Spotless enforces them at build time

FAQ

Q: Does Spotless modify files automatically? A: Only when you run spotlessApply. The spotlessCheck task is read-only and fails the build on drift without changing files.

Q: Can I use Spotless on a project that mixes Java and Kotlin? A: Yes. Configure separate java {} and kotlin {} blocks in the same plugin closure; each block targets its own source set.

Q: How does ratchet mode work? A: When ratchetFrom is set, Spotless only formats files that have been modified relative to the specified git ref, making gradual adoption painless.

Q: Is Spotless compatible with Gradle configuration cache? A: Yes. Recent versions of the Gradle plugin fully support configuration cache for faster incremental builds.

Sources

• https://github.com/diffplug/spotless
• https://github.com/diffplug/spotless/tree/main/plugin-gradle
• https://github.com/diffplug/spotless/tree/main/plugin-maven