@@ -29,7 +29,7 @@ offsets (`--offset`), passing through to standard-out (default) or altered
2929in-place (` --replace ` ).
3030
3131Option ` --help ` will print full usage details; including built-in documentation
32- about other flags, such as ` --aosp ` , ` --fix-imports-only ` ,
32+ about other flags, such as ` --style ` , ` --max-line-length ` , ` --fix-imports-only ` ,
3333` --skip-sorting-imports ` , ` --skip-removing-unused-import ` ,
3434` --skip-reflowing-long-strings ` , ` --skip-javadoc-formatting ` , or the ` --dry-run `
3535and ` --set-exit-if-changed ` .
@@ -40,9 +40,10 @@ arguments.
4040To reformat changed lines in a specific patch, use
4141[ ` google-java-format-diff.py ` ] ( https://github.com/google/google-java-format/blob/master/scripts/google-java-format-diff.py ) .
4242
43- *** Note:*** * There is no configurability as to the formatter's algorithm for
44- formatting. This is a deliberate design decision to unify our code formatting on
45- a single format.*
43+ *** Note:*** * There is almost no configurability as to the formatter's algorithm
44+ for formatting. This is a deliberate design decision to unify our code
45+ formatting on a single format. See [ Configuration] ( #configuration ) for the few
46+ options that are available.*
4647
4748### IntelliJ, Android Studio, and other JetBrains IDEs
4849
@@ -192,6 +193,46 @@ new Formatter().formatSource(source, output);
192193Your starting point should be the instance methods of
193194` com.google.googlejavaformat.java.Formatter ` .
194195
196+ ## Configuration
197+
198+ ` google-java-format ` is an opinionated formatter with very little configuration.
199+ Its core formatting decisions, like where lines break and how much continuation
200+ lines are indented, are deliberately not configurable. See also
201+ [ this FAQ entry] ( https://github.com/google/google-java-format/wiki/FAQ#i-just-need-to-configure-it-a-bit-differently-how )
202+ for more details.
203+
204+ There are a few configuration options for projects that need them:
205+
206+ * ` --style=google|aosp ` selects the code style. The default, ` google ` , follows
207+ [ Google Java Style] [ ] . ` aosp ` follows the
208+ [ AOSP Java code style] ( https://source.android.com/docs/setup/contribute/code-style ) :
209+ it indents blocks by 4 spaces and continuation lines by 8, instead of 2
210+ and 4. Line breaking is otherwise the same as Google style, so
211+ ` --style=aosp ` is also an option for projects that want 4-space indentation
212+ without otherwise following AOSP conventions. (` --google-style ` and ` --aosp `
213+ are equivalent shorthands.)
214+ * ` --max-line-length=N ` sets the column limit. The default is 100.
215+
216+ Besides layout, the formatter makes some changes that aren't just whitespace,
217+ and each of them can be turned off:
218+
219+ * ` --cleanup=false ` disables small cleanups such as removing redundant
220+ semicolons, empty annotation parentheses (` @Foo() ` to ` @Foo ` ), and
221+ parentheses around a single lambda parameter (` (x) -> ... ` to ` x -> ... ` ).
222+ Cleanups are enabled by default, and only apply to the lines being
223+ formatted.
224+ * ` --skip-sorting-imports ` and ` --skip-removing-unused-imports ` disable import
225+ sorting and unused import removal (` --fix-imports-only ` does only those, and
226+ no other formatting).
227+ * ` --skip-reordering-modifiers ` keeps modifiers in their existing order.
228+ * ` --skip-reflowing-long-strings ` disables splitting string literals that
229+ exceed the column limit.
230+ * ` --skip-javadoc-formatting ` leaves Javadoc comments unformatted.
231+
232+ Run ` google-java-format --help ` for the full command-line reference. When using
233+ the formatter as a library, ` JavaFormatterOptions.builder() ` and
234+ ` JavaFormatterOptions.Style.builder() ` provide the corresponding options.
235+
195236## Building from source
196237
197238```
0 commit comments