Home

Awesome

ktfmt-gradle ๐Ÿงน๐Ÿ˜

A wrapper to apply ktfmt to your Gradle builds, and reformat you Kotlin source code like a glimpse.

Plugin Portal Pre Merge Checks Language License Use this template Twitter

How to use ๐Ÿ‘ฃ

ktfmt-gradle is distributed through Gradle Plugin Portal. To use it you need to add the following dependency to your gradle files.

Please note that those code needs to be added the gradle file of the module where you want to reformat the code (not the top level build.gradle[.kts] file).

If you're using the plugin{} blocks in your Gradle file:

plugins {
    id("com.ncorti.ktfmt.gradle") version "<latest_version>"
}

If you're instead using the Groovy Gradle files and the old buildscript block:

buildscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2/" }
    }

    dependencies {
        classpath "com.ncorti.ktfmt.gradle:plugin:<latest_version>"
    }
}

apply plugin: "com.ncorti.ktfmt.gradle"

Requirements

Please note that ktfmt-gradle relies on ktfmt hence the minimum supported JDK version is 11.

Please also note the following requirements:

Task

By default, ktfmt-gradle will add two Gradle tasks to your build:

Those two tasks will invoke ktfmt on the whole module. More specific tasks are avialable based on the module type.

Additionally, the plugin will create check/format tasks for top-level Kotlin script files:

Jvm/Js Modules

For Jvm/Js modules, the plugin will create a check/format task for every source set. For example, jvm modules will have a ktfmtCheckMain and ktfmtCheckTest tasks for the main and test source sets.

Multiplatform Modules

Kotlin Multiplatform modules will have separate tasks for every target/source set. You will have tasks like ktfmtCheckCommonMain and ktfmtCheckCommonTest and so on. If you target also Android, the tasks explained below will be added as well.

Android Modules

Kotlin Android modules will also have separate tasks for every source set. Due to how source sets are handled on Android, you can expect ktfmt tasks to follow the convention: ktfmt[Check|Format][SourceSet][Variant]JavaSource. For example, the ktfmtCheckAndroidTestDebugJavaSource.

Features ๐ŸŽจ

Configuring ๐Ÿ› 

You can configure the behavior of the ktfmt invocation with the ktfmt block in your build.gradle.[kts] file.

To enable different styles you can simply:

ktfmt {
    // Google style - 2 space indentation & automatically adds/removes trailing commas
    googleStyle()
    
    // KotlinLang style - 4 space indentation - From kotlinlang.org/docs/coding-conventions.html
    kotlinLangStyle()
}

If you wish to have further control on the tool you can instead:

ktfmt {
    // Breaks lines longer than maxWidth. Default 100.
    maxWidth.set(80)
    // blockIndent is the indent size used when a new block is opened, in spaces.
    blockIndent.set(8)
    // continuationIndent is the indent size used when a line is broken because it's too
    continuationIndent.set(8)
    // Whether ktfmt should remove imports that are not used.
    removeUnusedImports.set(false)
    // Whether ktfmt should automatically add/remove trailing commas.
    manageTrailingCommas.set(false)
}

By default, sourceSets that are in your build folder are ignored. To customize this, you can set a regex pattern to exclude certain sourceSets:

ktfmt {
    srcSetPathExclusionPattern = Regex(".*generated.*")
}

Please note, that this property will only affect the sourceSet path and not the individual files inside the sourceSet. To include or exclude files inside a sourceSet, use the include and exclude properties of the ktfmt tasks.

Using with a pre-commit hook ๐ŸŽฃ

You can leverage the --include-only to let ktfmt-gradle run only on a specific subset of files.

To do this you can register a simple task of type KtfmtCheckTask or KtfmtFormatTask in your build.gradle.kts as follows:

import com.ncorti.ktfmt.gradle.tasks.*

tasks.register<KtfmtFormatTask>("ktfmtPrecommit") {
    source = project.fileTree(rootDir)
    include("**/*.kt")
}

You can then invoke the task with --include-only and a comma-separated (or colon-separated) list of relative path of files:

./gradlew ktfmtPrecommit --include-only=src/main/java/File1.kt:src/main/java/File2.kt

The task will execute only on the file you passed and will skip all the others.

Contributing ๐Ÿค

Feel free to open a issue or submit a pull request for any bugs/improvements.

License ๐Ÿ“„

This project is licensed under the MIT License - see the License file for details