• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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-1.8-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` action, which can be
48triggered from the `Code` menu or with the Ctrl-Alt-L (by default) keyboard
49shortcut.
50
51The import ordering is not handled by this plugin, unfortunately. To fix the
52import order, download the
53[IntelliJ Java Google Style file](https://raw.githubusercontent.com/google/styleguide/gh-pages/intellij-java-google-style.xml)
54and import it into File→Settings→Editor→Code Style.
55
56### Eclipse
57
58Version 1.6 of the
59[google-java-format Eclipse plugin](https://github.com/google/google-java-format/releases/download/google-java-format-1.6/google-java-format-eclipse-plugin_1.6.0.jar)
60can be downloaded from the releases page. Drop it into the Eclipse
61[drop-ins folder](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fp2_dropins_format.html)
62to activate the plugin.
63
64The plugin adds a `google-java-format` formatter implementation that can be
65configured in `Window > Preferences > Java > Code Style > Formatter > Formatter
66Implementation`.
67
68### Third-party integrations
69
70*   Gradle plugins
71    *   [spotless](https://github.com/diffplug/spotless/tree/main/plugin-gradle#google-java-format)
72    *   [sherter/google-java-format-gradle-plugin](https://github.com/sherter/google-java-format-gradle-plugin)
73*   Apache Maven plugins
74    *   [spotless](https://github.com/diffplug/spotless/tree/main/plugin-maven#google-java-format)
75    *   [coveo/fmt-maven-plugin](https://github.com/coveo/fmt-maven-plugin)
76    *   [talios/googleformatter-maven-plugin](https://github.com/talios/googleformatter-maven-plugin)
77    *   [Cosium/maven-git-code-format](https://github.com/Cosium/maven-git-code-format):
78        A maven plugin that automatically deploys google-java-format as a
79        pre-commit git hook.
80*   SBT plugins
81    *   [sbt/sbt-java-formatter](https://github.com/sbt/sbt-java-formatter)
82*   [maltzj/google-style-precommit-hook](https://github.com/maltzj/google-style-precommit-hook):
83    A pre-commit (pre-commit.com) hook that will automatically run GJF whenever
84    you commit code to your repository
85*   [Github Actions](https://github.com/features/actions)
86    *   [googlejavaformat-action](https://github.com/axel-op/googlejavaformat-action):
87        Automatically format your Java files when you push on github
88
89### as a library
90
91The formatter can be used in software which generates java to output more
92legible java code. Just include the library in your maven/gradle/etc.
93configuration.
94
95#### Maven
96
97```xml
98<dependency>
99  <groupId>com.google.googlejavaformat</groupId>
100  <artifactId>google-java-format</artifactId>
101  <version>1.8</version>
102</dependency>
103```
104
105#### Gradle
106
107```groovy
108dependencies {
109  compile 'com.google.googlejavaformat:google-java-format:1.8'
110}
111```
112
113You can then use the formatter through the `formatSource` methods. E.g.
114
115```java
116String formattedSource = new Formatter().formatSource(sourceString);
117```
118
119or
120
121```java
122CharSource source = ...
123CharSink output = ...
124new Formatter().formatSource(source, output);
125```
126
127Your starting point should be the instance methods of
128`com.google.googlejavaformat.java.Formatter`.
129
130## Building from source
131
132```
133mvn install
134```
135
136## Contributing
137
138Please see [the contributors guide](CONTRIBUTING.md) for details.
139
140## License
141
142```text
143Copyright 2015 Google Inc.
144
145Licensed under the Apache License, Version 2.0 (the "License"); you may not
146use this file except in compliance with the License. You may obtain a copy of
147the License at
148
149    http://www.apache.org/licenses/LICENSE-2.0
150
151Unless required by applicable law or agreed to in writing, software
152distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
153WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
154License for the specific language governing permissions and limitations under
155the License.
156```
157