Kotlinter Gradle

Painless Gradle plugin for linting and formatting Kotlin source files using the awesome ktlint engine.

It aims to be easy to set up with zero required configuration and behaves as you'd expect out of the box.

It's also fast because it integrates the ktlint engine directly with Gradle's incremental build and uses the Worker API to parallelize work.

Versions

This documentation is for version 5+. For documentation on version 4x and earlier, see README-4x.md.

Installation

Available on the Gradle Plugins Portal: https://plugins.gradle.org/plugin/org.jmailen.kotlinter

Single module

Kotlin

plugins {
    id("org.jmailen.kotlinter") version "5.0.1"
}

Groovy

plugins {
    id "org.jmailen.kotlinter" version "5.0.1"
}

Multi-module and Android

Kotlin

Root `build.gradle.kts`

plugins {
    id("org.jmailen.kotlinter") version "5.0.1" apply false
}

Each module build.gradle.kts with Kotlin source

plugins {
    id("org.jmailen.kotlinter")
}

Groovy

Root `build.gradle`

plugins {
    id 'org.jmailen.kotlinter' version "5.0.1" apply false
}

Each module build.gradle with Kotlin source

plugins {
    id 'org.jmailen.kotlinter'
}

Compatibility

• Kotlin -- generally compatible so long as the language features are supported by the version of ktlint selected
• Gradle 8.4+
• Ktlint 1.0+

Features

• Supports Kotlin Gradle plugins:
  • JVM
  • Multiplatform
  • Android
• Supports .kt and .kts files
• Standalone LintTask and FormatTask types for defining custom tasks
• Incremental build support and fast parallelization with Gradle Worker API
• Configures from .editorconfig when available
• Configurable reporters

Tasks

When your project uses one of the supported Kotlin Gradle plugins, Kotlinter adds these tasks:

formatKotlin: format Kotlin source code according to ktlint rules or warn when auto-format not possible.

lintKotlin: report Kotlin lint errors and by default fail the build.

Also check becomes dependent on lintKotlin.

Granular tasks are added for each source set in the project: formatKotlinSourceSet and lintKotlinSourceSet.

Git Hooks

Kotlinter can install a hook to run pre-push (installKotlinterPrePushHook). The hook runs lintKotlin and, if there are errors, formatKotlin and exits non-zero leaving changed files to be committed.

You must apply the kotlinter plugin to your root project to make this task available. If using git worktree you must install the hook from the parent git directory.

To install the hook automatically when someone runs the build, add this to your root project build.gradle.kts:

Kotlin

tasks.check {
    dependsOn("installKotlinterPrePushHook")
}

Groovy

tasks.named('check') {
    dependsOn 'installKotlinterPrePushHook'
}

Configuration

Options are configured in the kotlinter extension. Defaults shown (you may omit the configuration block entirely if you want the defaults).

Kotlin

kotlinter {
    ktlintVersion = "1.5.0"
    ignoreFormatFailures = true
    ignoreLintFailures = false
    reporters = arrayOf("checkstyle")
}

Groovy

kotlinter {
    ktlintVersion = "1.5.0"
    ignoreFormatFailures = true
    ignoreLintFailures = false
    reporters = ['checkstyle']
}

The ktlintVersion property allows you to override the default version of ktlint used by the plugin. Compatibility will generally be good, but ktlint consumer API changes may break compatibility in some rare cases.

Setting ignoreFormatFailures to false will configure the formatKotlin task to fail the build when auto-format is not able to fix a lint error.

Options for reporters: checkstyle, html, json, plain, sarif

Reporters behave as described at: https://github.com/pinterest/ktlint

Editorconfig

Kotlinter will configure itself using an .editorconfig file if one is present.

This configuration includes code style and linting rules.

See KtLint configuration for details.

Customizing Tasks

The formatKotlinSourceSet and lintKotlinSourceSet tasks inherit from SourceTask so you can customize includes, excludes, and source.

Note that exclude paths are relative to the package root. If you need to exclude at the src directory level, you can use a syntax like the below:

Kotlin

tasks.withType<LintTask> {
    this.source = this.source.minus(fileTree("src/generated")).asFileTree
}

tasks.withType<FormatTask> {
    this.source = this.source.minus(fileTree("src/generated")).asFileTree
}

Groovy

tasks.named("lintKotlinMain") {
  source = source - fileTree("$buildDir/generated")
}

Custom Tasks

If you aren't using autoconfiguration from a supported plugin or otherwise need to handle additional source code, you can create custom tasks:

Kotlin

import org.jmailen.gradle.kotlinter.tasks.LintTask
import org.jmailen.gradle.kotlinter.tasks.FormatTask

tasks.register<LintTask>("ktLint") {
    group = "verification"
    source(files("src"))
    reports.set(
        mapOf(
            "plain" to file("build/lint-report.txt"),
            "json" to file("build/lint-report.json")
        )
    )
}

tasks.register<FormatTask>("ktFormat") {
    group = "formatting"
    source(files("src"))
    report.set(file("build/format-report.txt"))
}

Groovy

import org.jmailen.gradle.kotlinter.tasks.LintTask
import org.jmailen.gradle.kotlinter.tasks.FormatTask

tasks.register('ktLint', LintTask) {
    group 'verification'
    source files('src')
    reports = [
            'plain': file('build/lint-report.txt'),
            'json' : file('build/lint-report.json')
    ]
}


tasks.register('ktFormat', FormatTask) {
  group 'formatting'
  source files('src/test')
  report = file('build/format-report.txt')
}

Custom Rules

You can add custom ktlint RuleSets using the ktlint dependency configuration:

Kotlin

dependencies {
  ktlint(project(":extra-rules"))
  ktlint("org.other.ktlint:custom-rules:1.0")
}

Groovy

dependencies {
  ktlint project(':extra-rules')
  ktlint 'org.other.ktlint:custom-rules:1.0'
}