1# google-java-format 2 3`google-java-format` is a program that reformats Java source code to comply with 4[Google Java Style][]. 5 6[Google Java Style]: https://google.github.io/styleguide/javaguide.html 7 8## Using the formatter 9 10### from the command-line 11 12[Download the formatter](https://github.com/google/google-java-format/releases) 13and run it with: 14 15``` 16java -jar /path/to/google-java-format-${GJF_VERSION?}-all-deps.jar <options> [files...] 17``` 18 19The formatter can act on whole files, on limited lines (`--lines`), on specific 20offsets (`--offset`), passing through to standard-out (default) or altered 21in-place (`--replace`). 22 23To reformat changed lines in a specific patch, use 24[`google-java-format-diff.py`](https://github.com/google/google-java-format/blob/master/scripts/google-java-format-diff.py). 25 26***Note:*** *There is no configurability as to the formatter's algorithm for 27formatting. This is a deliberate design decision to unify our code formatting on 28a single format.* 29 30#### JDK 16 31 32The following flags are required when running on JDK 16, due to 33[JEP 396: Strongly Encapsulate JDK Internals by Default](https://openjdk.java.net/jeps/396): 34 35``` 36java \ 37 --add-exports jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED \ 38 --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED \ 39 --add-exports jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED \ 40 --add-exports jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED \ 41 --add-exports jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED \ 42 -jar google-java-format-${GJF_VERSION?}-all-deps.jar <options> [files...] 43``` 44 45### IntelliJ, Android Studio, and other JetBrains IDEs 46 47A 48[google-java-format IntelliJ plugin](https://plugins.jetbrains.com/plugin/8527) 49is available from the plugin repository. To install it, go to your IDE's 50settings and select the `Plugins` category. Click the `Marketplace` tab, search 51for the `google-java-format` plugin, and click the `Install` button. 52 53The plugin will be disabled by default. To enable it in the current project, go 54to `File→Settings...→google-java-format Settings` (or `IntelliJ 55IDEA→Preferences...→Other Settings→google-java-format Settings` on macOS) and 56check the `Enable google-java-format` checkbox. (A notification will be 57presented when you first open a project offering to do this for you.) 58 59To enable it by default in new projects, use `File→Other Settings→Default 60Settings...`. 61 62When enabled, it will replace the normal `Reformat Code` action, which can be 63triggered from the `Code` menu or with the Ctrl-Alt-L (by default) keyboard 64shortcut. 65 66The import ordering is not handled by this plugin, unfortunately. To fix the 67import order, download the 68[IntelliJ Java Google Style file](https://raw.githubusercontent.com/google/styleguide/gh-pages/intellij-java-google-style.xml) 69and import it into File→Settings→Editor→Code Style. 70 71### Eclipse 72 73The latest version of the `google-java-format` Eclipse plugin can be downloaded 74from the [releases page](https://github.com/google/google-java-format/releases). 75Drop it into the Eclipse 76[drop-ins folder](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fp2_dropins_format.html) 77to activate the plugin. 78 79The plugin adds a `google-java-format` formatter implementation that can be 80configured in `Window > Preferences > Java > Code Style > Formatter > Formatter 81Implementation`. 82 83### Third-party integrations 84 85* Gradle plugins 86 * [spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle#google-java-format) 87 * [sherter/google-java-format-gradle-plugin](https://github.com/sherter/google-java-format-gradle-plugin) 88* Apache Maven plugins 89 * [spotless](https://github.com/diffplug/spotless/tree/main/plugin-maven#google-java-format) 90 * [coveo/fmt-maven-plugin](https://github.com/coveo/fmt-maven-plugin) 91 * [talios/googleformatter-maven-plugin](https://github.com/talios/googleformatter-maven-plugin) 92 * [Cosium/maven-git-code-format](https://github.com/Cosium/maven-git-code-format): 93 A maven plugin that automatically deploys google-java-format as a 94 pre-commit git hook. 95* SBT plugins 96 * [sbt/sbt-java-formatter](https://github.com/sbt/sbt-java-formatter) 97* [maltzj/google-style-precommit-hook](https://github.com/maltzj/google-style-precommit-hook): 98 A pre-commit (pre-commit.com) hook that will automatically run GJF whenever 99 you commit code to your repository 100* [Github Actions](https://github.com/features/actions) 101 * [googlejavaformat-action](https://github.com/axel-op/googlejavaformat-action): 102 Automatically format your Java files when you push on github 103 104### as a library 105 106The formatter can be used in software which generates java to output more 107legible java code. Just include the library in your maven/gradle/etc. 108configuration. 109 110#### Maven 111 112```xml 113<dependency> 114 <groupId>com.google.googlejavaformat</groupId> 115 <artifactId>google-java-format</artifactId> 116 <version>${google-java-format.version}</version> 117</dependency> 118``` 119 120#### Gradle 121 122```groovy 123dependencies { 124 implementation 'com.google.googlejavaformat:google-java-format:$googleJavaFormatVersion' 125} 126``` 127 128You can then use the formatter through the `formatSource` methods. E.g. 129 130```java 131String formattedSource = new Formatter().formatSource(sourceString); 132``` 133 134or 135 136```java 137CharSource source = ... 138CharSink output = ... 139new Formatter().formatSource(source, output); 140``` 141 142Your starting point should be the instance methods of 143`com.google.googlejavaformat.java.Formatter`. 144 145## Building from source 146 147``` 148mvn install 149``` 150 151## Contributing 152 153Please see [the contributors guide](CONTRIBUTING.md) for details. 154 155## License 156 157```text 158Copyright 2015 Google Inc. 159 160Licensed under the Apache License, Version 2.0 (the "License"); you may not 161use this file except in compliance with the License. You may obtain a copy of 162the License at 163 164 http://www.apache.org/licenses/LICENSE-2.0 165 166Unless required by applicable law or agreed to in writing, software 167distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 168WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 169License for the specific language governing permissions and limitations under 170the License. 171``` 172