Ktlint Gradle

Provides a convenient wrapper plugin over the ktlint project.

Latest plugin version: 6.3.1

This plugin creates convenient tasks in your Gradle project that run ktlint checks or do code auto format.

Plugin can be applied to any project, but only activates if that project has the kotlin plugin applied. The assumption being that you would not want to lint code you weren't compiling.

Table of content

Supported Kotlin plugins
How to use
Task details
- Main tasks
- Additional tasks
FAQ
Developers
- Importing the project
- Building the project
Links

Supported Kotlin plugins

This plugin supports following kotlin plugins:

"kotlin"
"kotlin-android"
"kotlin2js"
"kotlin-platform-common"
"kotlin-platform-js"
"kotlin-platform-jvm"
"konan"
"org.jetbrains.kotlin.native"
"kotlin-multiplatform"

If you know any new Kotlin plugin that are not in this list - please, open a new issue.

How to use

Minimal supported versions

This plugin was written using the new API available for gradle script kotlin builds. This API is available in new versions of gradle.

Minimal supported Gradle version: 4.3

Minimal supported ktlint version: 0.10.0

Ktlint plugin

Simple setup

Build script snippet for use in all Gradle versions:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "org.jlleitschuh.gradle:ktlint-gradle:<current_version>"
  }
}

apply plugin: "org.jlleitschuh.gradle.ktlint"

Using new plugin API

Build script snippet for new, incubating, plugin mechanism introduced in Gradle 2.1:

plugins {
  id "org.jlleitschuh.gradle.ktlint" version "<current_version>"
}

Applying to subprojects

Optionally apply plugin to all project modules:

subprojects {
    apply plugin: "org.jlleitschuh.gradle.ktlint" // Version should be inherited from parent
}

IntelliJ Idea Only Plugin

Note: This plugin is automatically applied by the main ktlint plugin.

This plugin just adds special tasks that can generate IntelliJ IDEA codestyle rules using ktlint.

Idea plugin simple setup

For all gradle versions:

Use the same buildscript logic as above, but with this instead of the above suggested apply line.

apply plugin: "org.jlleitschuh.gradle.ktlint-idea"

Idea plugin setup using new plugin API

Build script snippet for new, incubating, plugin mechanism introduced in Gradle 2.1:

plugins {
  id "org.jlleitschuh.gradle.ktlint-idea" version "<current_version>"
}

Configuration

The following configuration block is optional.

If you don't configure this the defaults defined in the KtlintExtension object will be used.

The version of ktlint used by default may change between patch versions of this plugin. If you don't want to inherit these changes then make sure you lock your version here.

import org.jlleitschuh.gradle.ktlint.reporter.ReporterType

ktlint {
    version = "0.22.0"
    debug = true
    verbose = true
    android = false
    outputToConsole = true
    reporters = [ReporterType.PLAIN, ReporterType.CHECKSTYLE]
    ignoreFailures = true
    ruleSets = [
        "/path/to/custom/rulseset.jar",
        "com.github.username:rulseset:master-SNAPSHOT"
    ]
    filter {
        exclude("**/generated/**")
        include("**/kotlin/**")
    }
}

or in kotlin script:

import org.jlleitschuh.gradle.ktlint.reporter.ReporterType

ktlint {
    version.set("0.22.0")
    debug.set(true)
    verbose.set(true)
    android.set(false)
    outputToConsole.set(true)
    reporters.set(setOf(ReporterType.PLAIN, ReporterType.CHECKSTYLE))
    ignoreFailures.set(true)
    ruleSets.set(listOf(
        "/path/to/custom/rulseset.jar",
        "com.github.username:rulseset:master-SNAPSHOT"
    ))
    filter {
        exclude("**/generated/**")
        include("**/kotlin/**")
    }
}

Samples

This repository provides following examples how to setup this plugin:

android-app - applies plugin to android application project
kotlin-gradle - applies plugin to plain Kotlin project that uses groovy in build.gradle files
kotlin-js - applies plugin to kotlin js project
kotlin-ks - applies plugin to plain Kotlin project that uses Kotlin DSL in build.gradle.kts files
kotlin-multiplatform-common - applies plugin to Kotlin common multiplatform module
kotlin-multiplatform-js - applies plugin to Kotlin Javascript multiplatform module
kotlin-multiplatform-jvm - applies plugin to Kotlin JVM multiplatform module
kotlin-native - applies plugin to Kotlin native project
kotlin-rulesets-using - adds custom example ruleset

Tasks Added

Main tasks

This plugin adds two tasks to every source set: ktlint[source set name]SourceSetCheck and ktlint[source set name]SourceSetFormat. Additionally, a simple ktlintCheck task has also been added that checks all of the source sets for that project. Similarly, a ktlintFormat task has been added that formats all of the source sets.

If the project has subprojects then the plugin also adds two meta tasks ktlintCheck and ktlintFormat to the root project that triggers the related tasks in the subprojects.

Android projects, additionally, will have meta tasks for Android variants, that will process all source sets in variant. For example, if app has foo flavor, following meta tasks will be added: ktlintFooDebugCheck, ktlintFooReleaseCheck, ktlintFooDebugFormat, ktlintFooReleaseFormat.

Additional helper tasks

Two another tasks are added:

ktlintApplyToIdea - The task generates IntelliJ IDEA (or Android Studio) Kotlin style files in the project .idea/ folder.
ktlintApplyToIdeaGlobally - The task generates IntelliJ IDEA (or Android Studio) Kotlin style files in the user home IDEA (or Android Studio) settings folder.

They are always added only to the root project.

Note that this tasks will overwrite the existing style file.

FAQ

Is it possible to not stop tasks execution if some of subprojects tasks failed?

Yes. Just use gradle --continue option:

$ ./gradlew --continue ktlintCheck

Can I mix old plugin and new plugin API setup in my project (see simple-setup and using new plugin API setup)?

No. This approaches are not equivalent how they work. The problem that plugin may not find some of kotlin plugins if both approaches are used in the project configuration. Especially it is related to Android plugin.

How can I import ReporterType in my external Gradle script?

Gradle doesn't allow to have import statements in external gradle script files (for example: quality/foo.gradle). To solve this - add following line in your root build.gradle file:

ext.ReporterType = org.jlleitschuh.gradle.ktlint.reporter.ReporterType

Then ReporterType will be available in your external Gradle script without any import line.

Developers

Importing

Import the settings.gradle.kts file into your IDE.

To enable the Android sample either define the ANDROID_HOME environmental variable or add a local.properties file to the project root folder with the following content:

sdk.dir=<android-sdk-location>

Building

Building the plugin: ./plugin/gradlew build

On how to run the current plugin snapshot check on sample projects: ./gradlew ktlintCheck

Links

Ktlint Gradle Plugin on the Gradle Plugin Registry

devisnik/ktlint-gradle