llm-wiki/raw/official-docs/spotless-gradle-plugin-readme.md

---
title: Spotless Gradle Plugin — Official README (diffplug/spotless)
source_type: official-doc
url: https://github.com/diffplug/spotless/blob/main/plugin-gradle/README.md
archive_url: https://raw.githubusercontent.com/diffplug/spotless/main/plugin-gradle/README.md
vendor: DiffPlug (diffplug/spotless)
related_branches: [feature-static-analysis-quality-contract]
related_projects: [ca-skeleton, ca-tmpl]
tags: [official-doc, ca-skeleton, ci-cd, gradle]
created: 2026-06-15
---

# Spotless Gradle Plugin — Official README (diffplug/spotless)

> Layer: `raw/` — 외부 자료(공식 문서)의 **원문 발췌·출처 기록**.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-static-analysis-quality-contract]] | D1/D9 — Spotless Gradle plugin(`com.diffplug.spotless`) 채택 + `spotlessCheck`(CI 검증) vs `spotlessApply`(자동수정) task 분리 + `googleJavaFormat` step 사용 + Gradle/JRE 버전 요건 확인 |

## 출처 / Source

- 원본 URL: https://github.com/diffplug/spotless/blob/main/plugin-gradle/README.md
- 아카이브 URL: https://raw.githubusercontent.com/diffplug/spotless/main/plugin-gradle/README.md
- 저자 / 조직: DiffPlug (https://github.com/diffplug)
- 발행일: 공개 GitHub README (현재 버전 8.6.0 기준)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

`feature-static-analysis-quality-contract` 브랜치의 D1/D9 결정 — Spotless Gradle plugin 채택과 `spotlessCheck`/`spotlessApply` task 이중 운용 방식 — 의 공식 근거로 보관. Gradle 7.3 / JRE 17 최소 요건 및 `googleJavaFormat` 상세 옵션도 함께 수록되어 있어 구현 명세 작성에 직접 인용 가능.

## 핵심 인용 / Key quotes (verbatim, 5문장)

> [§Quickstart] "To use it in your buildscript, just [add the Spotless dependency](https://plugins.gradle.org/plugin/com.diffplug.spotless), and configure it like so:"

> [§Quickstart — console demo] "  Run './gradlew spotlessApply' to fix these violations."

> [§Requirements] "Spotless requires JRE 17+ and Gradle 7.3 or newer."

> [§Disabling warnings and error messages] "The `check` task is Gradle's built-in task for grouping all verification tasks - unit tests, static analysis, etc.  By default, `spotlessCheck` is added as a dependency to `check`."

> [§google-java-format] "    googleJavaFormat('1.8').aosp().reflowLongStrings().formatJavadoc(false).reorderImports(false).groupArtifact('com.google.googlejavaformat:google-java-format')"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SPOTLESS-GRADLE-C1 | Spotless Gradle plugin의 ID는 `com.diffplug.spotless`이며, buildscript의 `spotless { }` 블록으로 포매터를 구성한다 | [§Quickstart] "To use it in your buildscript, just [add the Spotless dependency](https://plugins.gradle.org/plugin/com.diffplug.spotless), and configure it like so:" | `official-vendor-doc` | Gradle 프로젝트에 Spotless를 적용하는 모든 경우 | 특정 formatter 조합이 코드 품질을 보장한다는 뜻은 아님 |
| SPOTLESS-GRADLE-C2 | `spotlessCheck`는 위반 파일을 감지(수정 없음)하고, `spotlessApply`는 자동으로 수정한다; CI에서 `build` 태스크가 `spotlessCheck`에 의존한다 | [§console demo] "Run './gradlew spotlessApply' to fix these violations." | `official-vendor-doc` | Gradle CI 파이프라인에서 check/apply 분리 운용 | `spotlessCheck`가 모든 포매터 오류를 정확히 잡는다는 보장은 없음 |
| SPOTLESS-GRADLE-C3 | `spotlessCheck`는 Gradle의 `check` 태스크에 기본으로 의존성이 추가된다 | [§Disabling warnings] "By default, `spotlessCheck` is added as a dependency to `check`." | `official-vendor-doc` | Gradle `check` 태스크를 사용하는 모든 Spotless 프로젝트 | `enforceCheck false` 설정 시 이 기본 동작이 비활성화됨 |
| SPOTLESS-GRADLE-C4 | `googleJavaFormat('1.8')` 에 `.aosp()`, `.reflowLongStrings()`, `.formatJavadoc(false)`, `.reorderImports(false)`, `.groupArtifact(...)` 옵션을 체이닝할 수 있다 | [§google-java-format] "googleJavaFormat('1.8').aosp().reflowLongStrings().formatJavadoc(false).reorderImports(false).groupArtifact('com.google.googlejavaformat:google-java-format')" | `official-vendor-doc` | Java 포매터로 google-java-format을 사용하는 경우 | 특정 옵션 조합이 프로젝트의 기존 코드 스타일과 호환된다는 뜻은 아님 |
| SPOTLESS-GRADLE-C5 | Spotless 최신 버전은 JRE 17+ 및 Gradle 7.3 이상을 요구한다 | [§Requirements] "Spotless requires JRE 17+ and Gradle 7.3 or newer." | `official-vendor-doc` | 최신 Spotless 버전(`8.6.0` 기준)을 사용하는 Gradle 프로젝트 | JRE 11 또는 구형 Gradle 환경에서의 적용 여부(별도 구버전 필요) |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `SPOTLESS-GRADLE-C1`: plugin id `com.diffplug.spotless` 가 공식 플러그인 식별자임
  - `SPOTLESS-GRADLE-C2`: `spotlessCheck`(감지 전용) vs `spotlessApply`(자동수정) 역할 분리가 공식 설계임
  - `SPOTLESS-GRADLE-C3`: `spotlessCheck`가 `check` 태스크에 기본 wiring됨 — `./gradlew check` 시 자동 실행
  - `SPOTLESS-GRADLE-C4`: `googleJavaFormat` 의 버전·스타일·옵션 체이닝 API 공식 형식
  - `SPOTLESS-GRADLE-C5`: 최소 런타임 요건(JRE 17+, Gradle 7.3+) 공식 문서 명시
- 이 자료가 증명하지 않는 것:
  - multi-module(subprojects) 에서의 공식 권장 패턴 — README는 `spotlessPredeclare`(루트에서 의존성 중앙화)만 설명하고, `subprojects { apply plugin: ... }` 패턴은 명시적 권고 없음
  - `googleJavaFormat` 특정 버전이 ca-tmpl의 기존 코드베이스와 충돌 없이 동작한다는 것
  - CI 환경(GitHub Actions 등)에서의 캐싱/성능 특성
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl의 현재 Gradle/JRE 버전이 요건을 충족하는지 확인 (`SPOTLESS-GRADLE-C5` 적용 전)
  - `googleJavaFormat` 버전을 `1.8` vs `최신`으로 고정할지 결정 — 버전 고정 시 `build-release-supply-chain-contract` 의 dependency locking 과 연동 필요

## 메모 / Notes

- 버전 8.6.0 기준 README. `CHANGES.md` 확인 시 마이너 버전별 API 변경 있을 수 있음.
- `spotlessPredeclare` 블록은 대형 멀티모듈 병렬 빌드에서 의존성 해석 충돌을 방지하는 공식 메커니즘. Isolated Projects와 비호환이므로 ca-tmpl에서 Isolated Projects 사용 여부 확인 필요.
- `ratchetFrom 'origin/main'` 옵션: 변경된 파일에만 포맷 강제 — "format-everything" 커밋 없이 점진적 도입 가능. 신규 feature 브랜치 도입 시 유용.
- `./gradlew spotlessApply -PspotlessFiles=<pattern>` 으로 특정 파일만 선택 적용 가능 (디버깅용).

## Related / 관련

- 같은 주제 다른 official-doc / company-tech-blog: 없음 (현재)
- 이 자료를 인용한 wiki 요약: `[[wiki/concepts/spotless-gradle-formatter]]` (생성 시)
- 연관 브랜치: [[raw/branch-notes/feature-static-analysis-quality-contract]]
- 연관 소스: [[raw/official-docs/archunit-user-guide]] — 같은 static analysis 브랜치의 ArchUnit 근거