Kotlin Formatter

This project provides:

• A command-line tool for formatting Kotlin source code files, implemented as a wrapper around ktfmt.
• An IntelliJ idea plugin for formatting Kotlin source code files.

It can be used to automate code formatting, ensuring a clean and consistent codebase, while integrating seamlessly into development workflows.

Why Kotlin Formatter?

The main goal of this project is to establish a single, consistent formatting standard across CLI, Gradle, and IntelliJ, while integrating smoothly into existing developer workflows.

While ktfmt provides a solid foundation, we built Kotlin Formatter to address additional use cases:

• Configurable max-width – When we first explored ktfmt, its CLI didn’t support configuring max-width. Different projects and repositories have varying formatting standards, and we wanted to support this flexibility. In our case, we use a standard formatting width of 120 characters.
• Automated Formatting Support in Git Workflow – We wanted formatting to be automatically applied before code is committed to prevent formatting drift as early as possible, keeping it closest to the inner development loop.
• Format-on-save for IntelliJ – Format-on-save for IntelliJ – While ktfmt provides IntelliJ integration, our plugin includes format-on-save support in addition to manual formatting, reducing manual steps for developers.
• Consistent formatting experience across tools – We ensure consistency by having CLI, Gradle, and IntelliJ all use the same CLI under the hood, applying the same formatting rules across all workflows.

We hope these tools will make it easier for teams to maintain a consistent formatting experience with automated formatting—whether through Git hook integration or format-on-save—while seamlessly integrating into existing development workflows. 🚀

CLI Overview

The CLI provides the following capabilities:

• Format files and directories: Apply consistent formatting to files, directories, or standard input.
• Integrate with Git workflows:
  • Pre-commit: Format staged files before committing.
  • Pre-push: Check committed files before pushing.
• Daemon mode (experimental): Run a background process to avoid JVM startup time on repeated formatting calls.

Usage

kotlin-format [OPTIONS] [FILES...]

Options

Option	Description
--set-exit-if-changed	Exit with a non-zero code if any files needed changes.
--dry-run	Display the changes that would be made without writing them to disk.
--pre-commit	Format staged files as part of the pre-commit process. Mutually exclusive with --pre-push.
--pre-push	Check committed files as part of the pre-push process. Mutually exclusive with --pre-commit.
--push-commit=<text>	The SHA of the commit to use for pre-push. Defaults to HEAD.
--print-stats	Emit performance-related statistics to help diagnose performance issues.
--daemon	Run the CLI in daemon mode.
--stop-daemon	Stop the daemon if it's running.
-h, --help	Show help message and exit.

Arguments

Argument	Description
<files>	Files or directories to format. Use - for standard input.

⚡ Daemon Mode (Experimental)

⚠️ Warning: daemon mode is experimental and subject to change ⚠️ Formatting via the CLI involves slow Java startup. To avoid this, Kotlin Formatter can be run in daemon mode.

kotlin-format --daemon

In daemon mode, the CLI starts a server that listens for requests to format files. The port is chosen dynamically, and written to .kotlinformatter/kf.lock in the root of the git dir where kotlin-format is run. Only one daemon will run per git dir. If a daemon is already running, invoking kotlin-format --daemon will be a no-op, unless the running daemon is an older version.

.kotlinformatter/kf.lock should be added to your .gitignore.

The daemon only supports a limited set of formatting options compared to the CLI. To format files using the daemon, send a message containing the options:

pre-commit <files>
pre-push <sha> <files>

The daemon will respond with a status code on the first line of the response, followed by the output of the formatting operation.

A full example of using the daemon might look like this:

# start the daemon in the background
nohup kotlin-format --daemon > /dev/null 2>&1 &
# read values from lockfile
line=$(head -n 1 "$daemon_lock_file")
version=$(echo "$line" | cut -d ' ' -f 1)
port=$(echo "$line" | cut -d ' ' -f 2)
# format files
echo pre-commit file1.kt file2.kt | nc localhost $port

Additionally, the daemon knows the following commands:

exit # stop the daemon
status # get the status of the daemon

The daemon will automatically shut down after one hour of inactivity, or if it's been running for more than 24 hours. You can also manually shut down the daemon by sending the exit command, or running kotlin-format --stop-daemon.

Installing the CLI

There are multiple ways to install and use the Kotlin Formatter CLI:

1. Using Hermit

If you don't have Hermit installed, follow the Hermit Getting Started Guide to install it first. Once Hermit is installed, you can install the Kotlin Formatter CLI using:

hermit install kotlin-format

Once installed, you can run the CLI with:

kotlin-format [OPTIONS] [FILES...]

2. Downloading the pre-packaged distribution with a script

A pre-packaged distribution is available on Maven Central and GitHub Releases

VERSION=X.Y.Z
curl -L -o kotlin-formatter-dist.zip https://github.com/block/kotlin-formatter/releases/download/$VERSION/kotlin-formatter-dist-$VERSION.zip
unzip kotlin-formatter-dist.zip
cd kotlin-format-shadow-$VERSION

Once downloaded and extracted, you can run the CLI with:

./bin/kotlin-format [OPTIONS] [FILES...]

3. Downloading the JAR manually

A fat JAR of the CLI is available on Maven Central and GitHub Releases. Once downloaded, you can run the CLI with:

java -jar path/to/kotlin-formatter-$version-all.jar [OPTIONS] [FILES...]

IntelliJ IDEA Plugin Overview

The plugin enables Kotlin file formatting on save or via the format action.

Usage

To configure the plugin for a project, create a properties file named kotlin-formatter.properties and place it in the .idea directory. The following properties are supported

• kotlin-formatter.enabled: Enable or disable the plugin, disabled by default.
• kotlin-formatter.script-path: Path to the Kotlin Formatter script. The kotlin-format library in this project is used if this is not specified.

Example:

kotlin-formatter.enabled=true
kotlin-formatter.script-path=bin/kotlin-format

🚨 Changes to this configuration require an IDE restart to take effect.

Enabling Format-on-Save

To enable formatting of files on save, navigate to "Settings" > "Tools" > Actions on Save", activate the "Reformat code" checkbox, and ensure that the "Kotlin" file type is selected. Make sure "Optimize imports" is NOT enabled for the "Kotlin" file type.

IntelliJ IDEA Plugin Installation

Download from JetBrains Marketplace