README.md
1# ktfmt [](https://github.com/facebook/ktfmt/releases/) [](https://central.sonatype.com/artifact/com.facebook/ktfmt) [](https://github.com/facebook/ktfmt/actions/workflows/build_and_test.yml "GitHub Actions workflow status") [](https://slack-chats.kotlinlang.org/c/ktfmt) [](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up) [](https://github.com/facebook/ktfmt/issues)
2
3`ktfmt` is a program that pretty-prints (formats) Kotlin code, based on
4[google-java-format](https://github.com/google/google-java-format).
5
6The minimum supported runtime version is JDK 11, released September 2018.
7
8## Demo
9
10|Before Formatting| Formatted by `ktfmt`|
11| ---- | ---- |
12|  |  |
13
14For comparison, the same code formatted by [`ktlint`](https://github.com/pinterest/ktlint) and
15IntelliJ:
16
17| Formatted by `ktlint`|Formatted by IntelliJ|
18| ------ | --------|
19|  |  |
20
21## Playground
22
23We have a [live playground](https://facebook.github.io/ktfmt/) where you can easily see how ktfmt
24would format your code.
25Give it a try! https://facebook.github.io/ktfmt/
26
27## Using the formatter
28
29### IntelliJ, Android Studio, and other JetBrains IDEs
30
31A [ktfmt IntelliJ plugin](https://plugins.jetbrains.com/plugin/14912-ktfmt) is available from the
32plugin repository. To install it, go to your IDE's settings and select the `Plugins` category. Click
33the `Marketplace` tab, search for the `ktfmt` plugin, and click the `Install` button.
34
35The plugin will be disabled by default. To enable it in the current project, go to
36`File → Settings... → ktfmt Settings` (or `IntelliJ IDEA → Preferences... → Editor → ktfmt Settings`
37on macOS) and check the `Enable ktfmt` checkbox. A notification will be presented when you first
38open a project offering to do this for you.
39
40To enable it by default in new projects, use
41`File → New Project Settings → Preferences for new Projects → Editor → ktfmt Settings`.
42
43When enabled, it will replace the normal `Reformat Code` action, which can be triggered from the
44`Code` menu or with the Ctrl-Alt-L (by default) keyboard shortcut.
45
46To configure IntelliJ to approximate ktfmt's formatting rules during code editing, you can edit your
47project's
48[`.editorconfig` file](https://www.jetbrains.com/help/idea/configuring-code-style.html#editorconfig)
49to include the Kotlin section from one of the files inside [`docs/editorconfig`](docs/editorconfig).
50
51#### Share IntelliJ ktfmt settings
52In order to share the settings, make sure to commit the file `.idea/ktfmt.xml` into your codebase.
53
54### Installation
55
56#### Homebrew
57
58If you're a [Homebrew](https://brew.sh) user, you can install
59[ktfmt](https://formulae.brew.sh/formula/ktfmt) via:
60
61```
62$ brew install ktfmt
63```
64
65### from the command-line
66
67[Download the formatter](https://github.com/facebook/ktfmt/releases) and run it with:
68
69```
70java -jar /path/to/ktfmt-<VERSION>-jar-with-dependencies.jar [--kotlinlang-style | --google-style] [files...]
71```
72
73`--kotlinlang-style` makes `ktfmt` use a block indent of 4 spaces instead of 2.
74See below for details.
75
76***Note:***
77*There is no configurability as to the formatter's algorithm for formatting (apart from the
78different styles). This is a deliberate design decision to unify our code formatting on a single
79format.*
80
81### using Gradle
82
83A [Gradle plugin (ktfmt-gradle)](https://github.com/cortinico/ktfmt-gradle) is available on the
84Gradle Plugin Portal. To set it up, just follow the instructions in the
85[How-to-use section](https://github.com/cortinico/ktfmt-gradle#how-to-use-).
86
87Alternatively, you can use [Spotless](https://github.com/diffplug/spotless) with the
88[ktfmt Gradle plugin](https://github.com/diffplug/spotless/tree/main/plugin-gradle#ktfmt).
89
90### using Maven
91
92Consider using [Spotless](https://github.com/diffplug/spotless) with the
93[ktfmt Maven plugin](https://github.com/diffplug/spotless/tree/main/plugin-maven#ktfmt).
94
95### using pre-commit hooks
96
97A [pre-commit hook](https://pre-commit.com/hooks.html) is implemented in
98[language-formatters-pre-commit-hooks](https://github.com/macisamuele/language-formatters-pre-commit-hooks)
99
100## FAQ
101
102### `ktfmt` vs `ktlint` vs IntelliJ
103
104`ktfmt` uses google-java-format's underlying engine, and as such, many items on
105[google-java-format's FAQ](https://github.com/google/google-java-format/wiki/FAQ) apply to `ktfmt`
106as well.
107
108In particular, here are the principles that we try to adhere to:
1091. `ktfmt` ignores most existing formatting. It respects existing newlines in some places, but in
110 general, its output is deterministic and is independent of the input code.
1112. `ktfmt` exposes no configuration options that govern formatting behavior. See
112 https://github.com/google/google-java-format/wiki/FAQ#i-just-need-to-configure-it-a-bit-differently-how
113 for the rationale.
114 1. For exposed configurations, like `style`, we aim to make sure that those are easily shared
115 across your organization/codebase to avoid
116 [bikeshedding discussions](https://thedecisionlab.com/biases/bikeshedding) about code format.
117
118These two properties make `ktfmt` a good fit in large Kotlin code bases, where consistency is very
119important.
120
121We created `ktfmt` because at the time `ktlint` and IntelliJ sometimes failed to produce
122nice-looking code that fits in 100 columns, as can be seen in the [Demo](README.md#Demo) section.
123
124### `ktfmt` uses a 2-space indent; why not 4? any way to change that?
125
126Two reasons -
1271. Many of our projects use a mixture of Kotlin and Java, and we found the back-and-forth in styles
128 to be distracting.
1292. From a pragmatic standpoint, the formatting engine behind google-java-format uses more whitespace
130 and newlines than other formatters. Using an indentation of 4 spaces quickly reaches the maximal
131 column width.
132
133However, we do offer an alternative style for projects that absolutely cannot make the move to
134`ktfmt` because of 2-space: the style `--kotlinlang-style` changes block indents to 4-space.
135
136## Developer's Guide
137
138### Setup
139
140* Open `pom.xml` in IntelliJ. Choose "Open as a Project"
141* The IntelliJ project will unfortunately be broken on import. To fix,
142 * Turn off ErrorProne by removing the compiler parameters in IntelliJ at the bottom of
143 `Settings → Build, Execution, Deployment → Compiler → Java Compiler` (see
144 https://github.com/google/google-java-format/issues/417)
145
146### Development
147
148* Currently, we mainly develop by adding tests to `FormatterTest.kt`.
149
150### Building on the Command Line
151
152* Run `mvn install`
153* Run `java -jar core/target/ktfmt-<VERSION>-jar-with-dependencies.jar`
154
155### Releasing
156
157See [RELEASING.md](RELEASING.md).
158
159## License
160
161Apache License 2.0
162
){kind=link}
){kind=link}
