llm-wiki/vault/20-evidence/official-docs/google-java-format-readme.md

---
title: google-java-format — README & FAQ (Official Repo)
source_type: official-doc
url: https://github.com/google/google-java-format
archive_url: https://web.archive.org/web/2026/https://github.com/google/google-java-format
related_branches: [feature-static-analysis-quality-contract]
related_projects: [ca-skeleton]
tags: [official-doc, ca-skeleton, ci-cd, gradle, static-analysis]
created: 2026-06-15
---

# google-java-format — README & FAQ (Official Repo)

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

## Parent / 활용 branch (필수, 최소 1개+)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-static-analysis-quality-contract]] | D1 — Spotless + google-java-format 채택. 포맷터의 scope(naming 등 다른 style 측면은 정하지 않음), Java 21 최소 런타임 요건, zero-configurability 설계 결정, JDK 16+ 에서 필요한 --add-exports JVM flag 를 공식 확인. |

## 출처 / Source

- 원본 URL: https://github.com/google/google-java-format
- 추가 URL (FAQ): https://github.com/google/google-java-format/wiki/FAQ
- 아카이브 URL: https://web.archive.org/web/2026/https://github.com/google/google-java-format
- 저자 / 조직: Google (open-source)
- 발행일: 2015 (리포지토리 최초 릴리즈); 최신 v1.35.0 (March 2026)
- 마지막 확인일: 2026-06-15

## 왜 저장했는지 / Why archived

feature-static-analysis-quality-contract D1 의 Spotless + google-java-format 채택 결정을 뒷받침하는 공식 근거. 포맷터의 scope(formatting 전용, naming 등 미포함), Java 21 최소 버전 요건, zero-configurability 설계 철학, JDK 16+ JVM 플래그 요건을 원문으로 확보해 두어 "왜 이 도구를 골랐나" 질문에 직접 인용 가능한 상태로 보관.

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

> [README §command-line] "The minimum Java version can be found in `core/pom.xml` (currently Java 21)."

> [README §command-line note] "There is no configurability as to the formatter's algorithm for formatting. This is a deliberate design decision to unify our code formatting on a single format."

> [README §as-a-library] "`google-java-format` uses internal javac APIs for parsing Java source. The following JVM flags are required when running on JDK 16 and newer, due to [JEP 396: Strongly Encapsulate JDK Internals by Default](https://openjdk.java.net/jeps/396):"

> [FAQ §Principles-and-goals / "So formatter output is considered valid Google Style by definition?"] "And of course, many style rules concern issues the formatter has nothing to do with, such as naming."

## Claims Extracted / 추출된 주장

> 이 자료가 **직접 말하는 것만** claim 으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| GJF-README-C1 | google-java-format 의 scope 는 formatting/whitespace 에 한정되며, naming 등 다른 style 측면은 정하지 않는다 | [FAQ §Principles] "many style rules concern issues the formatter has nothing to do with, such as naming." | `official-vendor-doc` | google-java-format 을 Google Java Style 전체 준수 도구로 오해하는 상황 방지 | Checkstyle / SpotBugs 등 다른 static-analysis 도구의 scope 를 증명하지 않음 |
| GJF-README-C2 | google-java-format 실행을 위한 최소 Java 런타임 버전은 Java 21(JDK) 이다 | [README §command-line] "The minimum Java version can be found in `core/pom.xml` (currently Java 21)." | `official-vendor-doc` | google-java-format CLI 또는 Spotless googleJavaFormat() step 을 사용하는 모든 Gradle/Maven 빌드 | `core/pom.xml` 기준이므로 버전 업그레이드 시 변경 가능 — 최신 버전 확인 필요 |
| GJF-README-C3 | 포맷터 알고리즘에 대한 configurability 가 전혀 없다; 이는 코드 포맷을 단일 형식으로 통일하기 위한 의도적인 설계 결정이다 | [README §command-line note] "There is no configurability as to the formatter's algorithm for formatting. This is a deliberate design decision to unify our code formatting on a single format." | `official-vendor-doc` | google-java-format 을 프로젝트에 도입할 때 "커스텀 indent 폭" 등의 옵션을 기대하는 상황 | `--aosp` flag(4-space indent) 는 예외적으로 존재함 — FAQ에 명시 |
| GJF-README-C4 | JDK 16 이상에서 google-java-format 을 라이브러리로 사용하려면 특정 --add-exports JVM flag 가 필요하다 (JEP 396 강한 캡슐화 때문) | [README §as-a-library] "The following JVM flags are required when running on JDK 16 and newer, due to [JEP 396: Strongly Encapsulate JDK Internals by Default]" | `official-vendor-doc` | google-java-format 을 Gradle/Maven 빌드 플러그인(Spotless 등) 또는 라이브러리로 JDK 16+ 에서 실행하는 경우 | CLI JAR 실행(java -jar) 시에도 동일 flag 필요 여부는 실제 실행 검증 필요 |

## Usage Boundaries / 적용 경계

- 이 자료가 직접 증명하는 것:
  - `GJF-README-C1`: google-java-format 이 formatting만 다루고 naming/import 순서 이외의 style 검사는 하지 않음
  - `GJF-README-C2`: Java 21 이상 JDK 가 필요함 (v1.35.0 기준, core/pom.xml 정의)
  - `GJF-README-C3`: 포맷 알고리즘 설정 불가 — 의도적 설계 결정
  - `GJF-README-C4`: JDK 16+ 에서 `--add-exports=jdk.compiler/com.sun.tools.javac.*=ALL-UNNAMED` 6개 flag 필요
- 이 자료가 증명하지 않는 것:
  - Spotless Gradle plugin 의 `googleJavaFormat()` step 이 자동으로 이 flag 를 처리하는지 여부 (Spotless 공식 문서 별도 확인 필요)
  - google-java-format 이 ca-tmpl 프로젝트의 실제 빌드에서 오류 없이 동작하는지 (로컬 검증 필요)
  - Checkstyle, SpotBugs 등 다른 static-analysis 도구와의 rule 중복/충돌 여부
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  - ca-tmpl 의 Spotless 설정이 JDK 21 에서 --add-exports flag 를 자동 주입하는지 (`spotless-gradle-plugin-readme.md` C4 참조)
  - `core/pom.xml` Java 21 버전 명시가 최신 릴리즈(v1.35.0)에서도 유지되는지 확인

## 메모 / Notes

- README 에 scope 진술("naming 등은 대상 아님")이 없고 FAQ 에만 있음 — 두 URL 이 이 파일의 출처임을 frontmatter 와 § 출처에 명시했음.
- `--aosp` flag 는 4-space indent 를 허용하는 유일한 configuration 예외이나, Google 내부 통합에서는 노출되지 않는다고 FAQ 에 명시됨.
- JDK 16+ flag 목록: `--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED`, `.code=ALL-UNNAMED`, `.file=ALL-UNNAMED`, `.parser=ALL-UNNAMED`, `.tree=ALL-UNNAMED`, `.util=ALL-UNNAMED` (6개).
- 추가로 봐야 할 동일 출처 페이지: https://github.com/google/google-java-format/wiki/FAQ (FAQ 전체), https://github.com/google/google-java-format/releases (버전 변경 이력)

## Related / 관련

- 같은 주제 다른 official-doc: [[raw/official-docs/spotless-gradle-plugin-readme]] — Spotless Gradle plugin(D1/D9 근거), `googleJavaFormat()` step 사용법
- 같은 주제 다른 official-doc: [[raw/official-docs/checkstyle-google-style-reference]] — Checkstyle google_checks.xml (D2 근거), naming/formatting 모듈 분류
- Parent branch: [[raw/branch-notes/feature-static-analysis-quality-contract]]