# Spotless — Multi-Language Code Formatter for JVM Projects

> Spotless is a flexible code formatting tool for Gradle and Maven that enforces consistent style across Java, Kotlin, Groovy, SQL, Markdown, and more with zero configuration drift.

## Install

Save as a script file and run:

# Spotless — Multi-Language Code Formatter for JVM Projects

## Quick Use
```bash
# Gradle — check formatting
./gradlew spotlessCheck

# Gradle — apply formatting
./gradlew spotlessApply

# Maven — check formatting
mvn spotless:check

# Maven — apply formatting
mvn spotless:apply
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-9f54585c
Author: Script Depot