ktfmt

ktfmt is a program that pretty-prints (formats) Kotlin code, based on google-java-format.

The minimum supported runtime version is JDK 11, released September 2018.

Demo

Before Formatting	Formatted by ktfmt

For comparison, the same code formatted by ktlint and IntelliJ:

Formatted by ktlint	Formatted by IntelliJ

Playground

We have a live playground where you can easily see how ktfmt would format your code. Give it a try! https://facebook.github.io/ktfmt/

Using the formatter

IntelliJ, Android Studio, and other JetBrains IDEs

A ktfmt IntelliJ plugin is available from the plugin repository. To install it:

1. Go to your IDE’s settings
2. Select the Plugins category
3. Go to the Marketplace tab
4. Search for the ktfmt plugin
5. Install it

The plugin will be disabled by default. To enable it in the current project, go to File → Settings... → ktfmt Settings (or IntelliJ IDEA → Preferences... → Editor → ktfmt Settings on macOS) and check the Enable ktfmt checkbox. A notification will be presented when you first open a project offering to do this for you.

To enable it by default in new projects, use File → New Project Settings → Preferences for new Projects → Editor → ktfmt Settings.

When enabled, it will replace the normal Reformat Code action, which can be triggered from the Code menu or with the Ctrl-Alt-L (by default) keyboard shortcut.

To configure IntelliJ to approximate ktfmt’s formatting rules during code editing, you can edit your project’s .editorconfig file to include the Kotlin section from one of the files inside docs/editorconfig.

Share IntelliJ ktfmt settings

In order to share the settings, make sure to commit the file .idea/ktfmt.xml into your codebase.

Installation

Homebrew

If you’re a Homebrew user, you can install ktfmt via:

$ brew install ktfmt

from the command-line

Download the formatter and run it with:

$ java -jar /path/to/ktfmt-<VERSION>-with-dependencies.jar [--kotlinlang-style | --google-style] [files...]

--kotlinlang-style makes ktfmt use a block indent of 4 spaces instead of 2. See below for details.

--enable-editorconfig makes ktfmt enable limited support to override the style’s configuration based on the following subset of editorconfig properties:

EditorConfig Property	Description
max_line_length	will override the max line width
indent_size or tab_width if indent_size = tab	will override the block indent
ij_continuation_indent_size	will override the continuation indent
ktfmt_trailing_comma_management_strategy	one of none, only_add or complete will override the trailing comma management strategy

Note: There is no configurability as to the formatter’s algorithm for formatting (apart from the different styles or limited .editorconfig support). This is a deliberate design decision to unify our code formatting on a single format.

using Gradle

A Gradle plugin (ktfmt-gradle) is available on the Gradle Plugin Portal. To set it up, just follow the instructions in the How-to-use section.

Alternatively, you can use Spotless with the ktfmt Gradle plugin.

using Maven

Consider using Spotless with the ktfmt Maven plugin.

using pre-commit hooks

A pre-commit hook is implemented in language-formatters-pre-commit-hooks

FAQ

ktfmt vs ktlint vs IntelliJ

ktfmt uses google-java-format’s underlying engine, and as such, many items on google-java-format’s FAQ apply to ktfmt as well.

In particular, here are the principles that we try to adhere to:

1. 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.
2. 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.
   1. For exposed configurations, like style, we aim to make sure that those are easily shared across your organization/codebase to avoid bikeshedding discussions about code format.

These two properties make ktfmt a good fit in large Kotlin code bases, where consistency is very important.

We created ktfmt because at the time ktlint and IntelliJ sometimes failed to produce nice-looking code that fits in 100 columns, as can be seen in the Demo section.

ktfmt uses a 2-space indent; why not 4? any way to change that?

Two reasons -

1. Many of our projects use a mixture of Kotlin and Java, and we found the back-and-forth in styles to be distracting.
2. 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.

However, we do offer an alternative style for projects that absolutely cannot make the move to ktfmt because of 2-space: the style --kotlinlang-style changes block indents to 4-space.

Alternatively, the ktfmt command-line supports a limited subset of .editorconfig properties; see above.

Developer’s Guide

Setup

Open the build.gradle.kts at the root of the repo in IntelliJ. Choose “Open as a Project”.

Development

• Currently, we mainly develop by adding tests to FormatterTest.kt.

Building on the Command Line

• Run ./gradlew :ktfmt:shadowJar
• Run java -jar core/build/libs/ktfmt-<VERSION>-with-dependencies.jar

Releasing

See RELEASING.md.

License

Apache License 2.0