google-java-format: the Java formatter that refuses to be configured

What google-java-format actually decides for you

The project is a formatter for Java source that produces output conforming to Google Java Style. That is the whole scope: it does not lint, it does not compile, it does not review. The README is explicit that there is no configurability in the formatting algorithm, and calls this a deliberate design decision to unify code formatting on a single format. So the problem it solves is not "format my code" in general but "stop arguing about format". If two engineers disagree about where a line breaks, the tool has one answer and neither engineer gets a vote. That makes it a good fit for organisations that want a mechanical, reviewable style gate, and a poor fit for anyone who treats indentation width or import ordering as a matter of team preference. The README also points out that the formatter parses Java using the jdk.compiler module, so the java binary you run it with must be a JDK, not a JRE, and must be at least as new as the Java language version of the files being formatted. The minimum Java version lives in pom.xml and is currently Java 21. That single constraint shapes most of the installation friction described below.

How the formatter processes a file

The mechanism is visible in the repository layout and the README. The core/ directory holds the formatter itself, and the tool parses Java source through internal javac APIs rather than a hand-written parser. That is why the JVM flags appear everywhere in the documentation: on JDK 16 and newer, JEP 396 strongly encapsulates JDK internals by default, so the formatter needs explicit --add-exports lines to reach com.sun.tools.javac.api, code, file, parser, tree and util. The data flow is straightforward. Input is a Java file, or a set of files, or a line range, or a byte offset. The formatter parses it with javac, rewrites the token stream into Google Java Style, and either writes the result to standard output (the default) or back over the file with --replace. It can also act on limited lines with --lines and on specific offsets with --offset, which matters for large files where you only want to touch a patch. Import handling is part of the same pass: sorting and removal of unused imports happen by default and can be turned off with --skip-sorting-imports and --skip-removing-unused-import. The --aosp flag switches the output to the Android Open Source Project style, which is the 4-space variant also exposed by the Eclipse plugin as aosp-java-format. The README notes an @<filename> form for reading options and filenames from a file instead of arguments, and a --dry-run plus --set-exit-if-changed pair that lets the tool act as a check rather than a rewriter.

Installing the jar and formatting a first file

The README's primary path is to download the formatter from the releases page and run it directly. The release artifact is an all-deps jar, and the invocation below is the one the README gives, with the version placeholder left as the project writes it. The command prints the reformatted source to standard output by default, so redirect or add --replace when you want the file changed on disk.

java -jar /path/to/google-java-format-${GJF_VERSION?}-all-deps.jar <options> [files...]

Before running it, confirm the java binary is from a JDK 21 or newer. If it is not, the formatter will fail while parsing rather than produce a useful error about versions. The README also mentions GraalVM based native binaries as an alternative for environments where a suitable JDK is awkward to provide.

A first real use is to check, not rewrite. The --dry-run and --set-exit-if-changed flags make the tool exit non-zero when a file is not already formatted, which is the shape you want in a pre-commit hook or a CI step. The README documents both flags but does not document a rollback path, so if you run with --replace on files that are not under version control you have no undo from the tool itself.

For a patch rather than a whole file, the repository ships scripts/google-java-format-diff.py, which the README describes as the way to reformat changed lines in a specific patch. That is the practical entry point for teams that do not want a formatting-only commit touching every file in the tree.

IntelliJ and Eclipse need JVM exports before the plugin works

Both IDE integrations depend on the same internal javac classes, and both therefore require you to edit the IDE's JVM options. In IntelliJ and other JetBrains IDEs, the plugin is installed from the Marketplace under Plugins, then enabled in Project settings under google-java-format Settings; it is disabled by default, and enabling it replaces the normal Reformat Code and Optimize Imports actions. The JRE configuration goes in Help, Edit Custom VM Options, and the README lists six --add-exports lines for jdk.compiler packages. Eclipse takes the same six lines, pasted into eclipse.ini anywhere after -vmargs, and the plugin is activated by dropping it into the drop-ins folder. Eclipse exposes two formatter implementations, google-java-format with 2 spaces and aosp-java-format with 4 spaces, selectable under Window, Preferences, Java, Code Style, Formatter, Formatter Implementation. This is the part of the project that ages worst: every IDE upgrade that changes its bundled JVM can invalidate the export list, and the failure mode is a plugin that silently does nothing rather than an error dialog.

No configuration is the feature and the limitation

The absence of options is the sharpest edge here. The README states there is no configurability as to the formatter's algorithm, and that this is deliberate. In practice that means you cannot change line width, brace placement, continuation indent or alignment. The flags that exist are narrow: --aosp changes the indent to the Android style, and the --skip-* family turns off import sorting, unused-import removal, long-string reflowing and Javadoc formatting. There is no flag to keep your existing import order or your existing line length. Teams that have an established house style will find the tool rewrites it wholesale, and the resulting diff is large and formatting-only. The second limitation is the JDK floor. Because parsing goes through jdk.compiler, the java binary must be a JDK at least as new as the language version of the files. Formatting a project that uses a newer Java language level than the JDK you invoke the tool with will not work, and the README does not describe a fallback for that case. The third is the IDE export list, which is manual configuration that the tool cannot perform for you. None of these are bugs; they are the cost of parsing with javac internals instead of a standalone grammar.

google-java-format versus Palantir Java Format

Palantir Java Format is the comparison people search for, and the difference is exactly the design decision described above. google-java-format has one output and no knobs; its README frames that as unifying code formatting on a single format. Palantir Java Format is a fork of the same codebase that adds configurable style options, so it occupies the opposite position: you can tune the result, at the cost of the guarantee that every project using it produces identical bytes. The practical consequence is that google-java-format is the better choice when the goal is a mechanical, non-negotiable style gate across many repositories, and Palantir Java Format is the better choice when the goal is to keep an existing style that differs from Google Java Style. Both parse Java with javac internals, so the JDK floor and the --add-exports requirements are not a differentiator between them. If your team's objection to google-java-format is specifically "we want 4 spaces and a different line width", the --aosp flag covers the indentation half and nothing covers the rest.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-17, which is recent. Releases are frequent: v1.36.1 on 2026-07-30, v1.36.0 on 2026-07-29, and v1.35.0 on 2026-03-03. That cadence matters because the formatter's output can change between versions. A formatting-only upgrade can produce a diff across every Java file in a repository, so the upgrade cost is not the download but the review. The README does not document a rollback procedure, and the tool has no compatibility mode for older output, so pinning the version in CI and in the IDE plugin is the only way to keep formatting stable. On licensing, the repository contains a LICENSE file and the project metadata reports the licence as NOASSERTION, which means the GitHub API could not map the file to a known SPDX identifier. Read LICENSE directly before relying on it for redistribution; nothing in the README states the terms, and this is not a substitute for legal review. The third-party integration list in the README is long, including spotless for Gradle and Maven, fmt-maven-plugin, googleformatter-maven-plugin, maven-git-code-format, sbt-java-formatter, a VS Code extension and a GitHub Action, so many teams will consume the formatter through a build plugin rather than the jar. In that case the version you pin is the plugin's, not the jar's, and the two can drift.

Editorial conclusion

Adopt google-java-format if you want a single canonical Java style and are willing to give up formatter configuration entirely; the CLI jar, the IntelliJ plugin and the Eclipse drop-in all target that workflow. Do not adopt it if your team needs to tune line width, indentation or import handling beyond the handful of skip flags, or if you format Java older than the JDK running the formatter. Verify first that the JDK on the machine is 21 or newer and is a JDK rather than a JRE, and check whether your build already routes formatting through a plugin such as spotless before adding a second path.

Frequently asked questions

Official sources

1. google/google-java-format on GitHub
2. Issues
3. README
4. Releases