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