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.
Available on the Gradle Plugins Portal: https://plugins.gradle.org/plugin/org.jmailen.kotlinter
Kotlin
plugins {
id("org.jmailen.kotlinter") version "4.4.1"
}
Groovy
plugins {
id "org.jmailen.kotlinter" version "4.4.1"
}
Kotlin
Root `build.gradle.kts`plugins {
id("org.jmailen.kotlinter") version "4.4.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 "4.4.1" apply false
}
Each module build.gradle
with Kotlin source
plugins {
id 'org.jmailen.kotlinter'
}
kotlinter version | min kotlin version | max kotlin version | min gradle version |
---|---|---|---|
4.2.0+ | 1.9.20 | - | 8.4 |
4.0.0+ | 1.9.0 | - | 7.6 |
3.14.0+ | 1.8.0 | 1.8.22 | 7.6 |
3.11.0+ | 1.7.0 | 1.7.22 | 7.0 |
3.10.0+ | 1.6.20 | 1.6.21 | 7.0 |
3.7.0+ | 1.5.31 | 1.6.10 | 7.0 |
3.5.0+ | 1.5.0 | 1.5.30 | 6.8 |
3.0.0+ | 1.4.0 | 1.4.30 | 6.8 |
2.0.0+ | 1.3.0 | 1.3.30 | - |
- Supports Kotlin Gradle plugins:
- Supports
.kt
and.kts
files - Standalone
LintTask
andFormatTask
types for defining custom tasks - Incremental build support and fast parallelization with Gradle Worker API
- Configures from
.editorconfig
when available - Configurable reporters
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: formatKotlin
SourceSet
and lintKotlin
SourceSet
.
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'
}
Options are configured in the kotlinter
extension. Defaults shown (you may omit the configuration block entirely if you want these defaults).
Kotlin
kotlinter {
failBuildWhenCannotAutoFormat = false
ignoreFailures = false
reporters = arrayOf("checkstyle", "plain")
}
Groovy
kotlinter {
failBuildWhenCannotAutoFormat = false
ignoreFailures = false
reporters = ['checkstyle', 'plain']
}
Setting failBuildWhenCannotAutoFormat
to true
will configure the formatKotlin
task to fail the build when auto-format is not able to fix a lint error. This is overrided by setting ignoreFailures
to true
.
Options for reporters
: checkstyle
, html
, json
, plain
, sarif
Reporters behave as described at: https://github.com/pinterest/ktlint
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.
The formatKotlin
SourceSet
and lintKotlin
SourceSet
tasks inherit from SourceTask
so you can customize includes, excludes, and source.
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")
}
Note that exclude paths are relative to the package root.
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')
}
If you need to use a different version of ktlint
you can override the dependency.
Kotlin or Groovy
buildscript {
configurations.classpath {
resolutionStrategy {
force(
"com.pinterest.ktlint:ktlint-rule-engine:1.2.1",
"com.pinterest.ktlint:ktlint-rule-engine-core:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-core:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-checkstyle:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-json:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-html:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-plain:1.2.1",
"com.pinterest.ktlint:ktlint-cli-reporter-sarif:1.2.1",
"com.pinterest.ktlint:ktlint-ruleset-standard:1.2.1"
)
}
}
}
Alternatively, if you have a custom build convention plugin that utilizes kotlinter, you can enforce a newer KtLint version through a platform
directive:
Kotlin or Groovy
dependencies {
implementation(platform("com.pinterest.ktlint:ktlint-bom:1.2.1"))
implementation("org.jmailen.gradle:kotlinter-gradle:4.4.1")
}
You can add custom ktlint RuleSets using the buildscript
classpath:
Kotlin
buildscript {
dependencies {
classpath(files("libs/my-custom-ktlint-rules.jar"))
classpath("org.other.ktlint:custom-rules:1.0")
}
}
Groovy
buildscript {
dependencies {
classpath files('libs/my-custom-ktlint-rules.jar')
classpath 'org.other.ktlint:custom-rules:1.0'
}
}