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### IntelliJ, Android Studio, and other JetBrains IDEs 31 32A 33[google-java-format IntelliJ plugin](https://plugins.jetbrains.com/plugin/8527) 34is available from the plugin repository. To install it, go to your IDE's 35settings and select the `Plugins` category. Click the `Marketplace` tab, search 36for the `google-java-format` plugin, and click the `Install` button. 37 38The plugin will be disabled by default. To enable it in the current project, go 39to `File→Settings...→google-java-format Settings` (or `IntelliJ 40IDEA→Preferences...→Other Settings→google-java-format Settings` on macOS) and 41check the `Enable google-java-format` checkbox. (A notification will be 42presented when you first open a project offering to do this for you.) 43 44To enable it by default in new projects, use `File→Other Settings→Default 45Settings...`. 46 47When enabled, it will replace the normal `Reformat Code` and `Optimize Imports` 48actions. 49 50#### IntelliJ JRE Config 51 52The google-java-format plugin uses some internal classes that aren't available 53without extra configuration. To use the plugin, go to `Help→Edit Custom VM 54Options...` and paste in these lines: 55 56``` 57--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED 58--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED 59--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED 60--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED 61--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED 62--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED 63``` 64 65Once you've done that, restart the IDE. 66 67### Eclipse 68 69The latest version of the `google-java-format` Eclipse plugin can be downloaded 70from the [releases page](https://github.com/google/google-java-format/releases). 71Drop it into the Eclipse 72[drop-ins folder](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fp2_dropins_format.html) 73to activate the plugin. 74 75The plugin adds a `google-java-format` formatter implementation that can be 76configured in `Window > Preferences > Java > Code Style > Formatter > Formatter 77Implementation`. 78 79### Third-party integrations 80 81* Gradle plugins 82 * [spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle#google-java-format) 83 * [sherter/google-java-format-gradle-plugin](https://github.com/sherter/google-java-format-gradle-plugin) 84* Apache Maven plugins 85 * [spotless](https://github.com/diffplug/spotless/tree/main/plugin-maven#google-java-format) 86 * [spotify/fmt-maven-plugin](https://github.com/spotify/fmt-maven-plugin) 87 * [talios/googleformatter-maven-plugin](https://github.com/talios/googleformatter-maven-plugin) 88 * [Cosium/maven-git-code-format](https://github.com/Cosium/maven-git-code-format): 89 A maven plugin that automatically deploys google-java-format as a 90 pre-commit git hook. 91* SBT plugins 92 * [sbt/sbt-java-formatter](https://github.com/sbt/sbt-java-formatter) 93* [Github Actions](https://github.com/features/actions) 94 * [googlejavaformat-action](https://github.com/axel-op/googlejavaformat-action): 95 Automatically format your Java files when you push on github 96 97### as a library 98 99The formatter can be used in software which generates java to output more 100legible java code. Just include the library in your maven/gradle/etc. 101configuration. 102 103`google-java-format` uses internal javac APIs for parsing Java source. The 104following JVM flags are required when running on JDK 16 and newer, due to 105[JEP 396: Strongly Encapsulate JDK Internals by Default](https://openjdk.java.net/jeps/396): 106 107``` 108--add-exports=jdk.compiler/com.sun.tools.javac.api=ALL-UNNAMED 109--add-exports=jdk.compiler/com.sun.tools.javac.code=ALL-UNNAMED 110--add-exports=jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED 111--add-exports=jdk.compiler/com.sun.tools.javac.parser=ALL-UNNAMED 112--add-exports=jdk.compiler/com.sun.tools.javac.tree=ALL-UNNAMED 113--add-exports=jdk.compiler/com.sun.tools.javac.util=ALL-UNNAMED 114``` 115 116#### Maven 117 118```xml 119<dependency> 120 <groupId>com.google.googlejavaformat</groupId> 121 <artifactId>google-java-format</artifactId> 122 <version>${google-java-format.version}</version> 123</dependency> 124``` 125 126#### Gradle 127 128```groovy 129dependencies { 130 implementation 'com.google.googlejavaformat:google-java-format:$googleJavaFormatVersion' 131} 132``` 133 134You can then use the formatter through the `formatSource` methods. E.g. 135 136```java 137String formattedSource = new Formatter().formatSource(sourceString); 138``` 139 140or 141 142```java 143CharSource source = ... 144CharSink output = ... 145new Formatter().formatSource(source, output); 146``` 147 148Your starting point should be the instance methods of 149`com.google.googlejavaformat.java.Formatter`. 150 151## Building from source 152 153``` 154mvn install 155``` 156 157## Contributing 158 159Please see [the contributors guide](CONTRIBUTING.md) for details. 160 161## License 162 163```text 164Copyright 2015 Google Inc. 165 166Licensed under the Apache License, Version 2.0 (the "License"); you may not 167use this file except in compliance with the License. You may obtain a copy of 168the License at 169 170 http://www.apache.org/licenses/LICENSE-2.0 171 172Unless required by applicable law or agreed to in writing, software 173distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 174WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 175License for the specific language governing permissions and limitations under 176the License. 177``` 178