Provides a convenient wrapper plugin over the ktlint project.
Latest plugin version: 12.1.1
This plugin creates convenient tasks in your Gradle project that run ktlint checks or do code auto format.
The 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.
- Supported Kotlin plugins
- How to use
- Task details
- FAQ
- Developers
- Links
This plugin supports the following kotlin plugins:
- "kotlin"
- "kotlin-android"
- "kotlin-multiplatform"
- project kotlin script files
- "org.jetbrains.kotlin.js"
If you know any new Kotlin plugin that is not in this list - please, open a new issue.
This plugin was written using the new API available for the Gradle script Kotlin builds. This API is available in new versions of Gradle.
Minimal supported Gradle version: 7.4
Minimal supported Kotlin version: 1.4
Minimal supported ktlint version: 0.47.1
Minimal supported Android Gradle plugin version: 4.1.0
Build script snippet for new plugin mechanism introduced in Gradle 2.1:
Groovy
plugins {
id "org.jlleitschuh.gradle.ktlint" version "<current_version>"
}
repositories {
// Required to download KtLint
mavenCentral()
}
Kotlin
plugins {
id("org.jlleitschuh.gradle.ktlint") version "<current_version>"
}
repositories {
// Required to download KtLint
mavenCentral()
}
To configure the plugin using a version catalog, first, add the following entries to your libs.versions.toml file:
[versions]
ktlint = "<current_version>"
[plugins]
ktlint = { id = "org.jlleitschuh.gradle.ktlint", version.ref = "ktlint" }
Next, apply it to your project:
Groovy
plugins {
alias(libs.plugins.ktlint)
}
repositories {
// Required to download KtLint
mavenCentral()
}
Kotlin
plugins {
alias(libs.plugins.ktlint)
}
repositories {
// Required to download KtLint
mavenCentral()
}
Build script snippet for use in all Gradle versions:
Groovy
buildscript {
repositories {
maven {
url "https://plugins.gradle.org/m2/"
}
}
dependencies {
classpath "org.jlleitschuh.gradle:ktlint-gradle:<current_version>"
}
}
repositories {
// Required to download KtLint
mavenCentral()
}
apply plugin: "org.jlleitschuh.gradle.ktlint"
Kotlin
buildscript {
repositories {
maven("https://plugins.gradle.org/m2/")
}
dependencies {
classpath("org.jlleitschuh.gradle:ktlint-gradle:<current_version>")
}
}
repositories {
// Required to download KtLint
mavenCentral()
}
apply(plugin = "org.jlleitschuh.gradle.ktlint")
Optionally apply plugin to all project modules:
Groovy
subprojects {
apply plugin: "org.jlleitschuh.gradle.ktlint" // Version should be inherited from parent
repositories {
// Required to download KtLint
mavenCentral()
}
// Optionally configure plugin
ktlint {
debug = true
}
}
Kotlin
subprojects {
apply(plugin = "org.jlleitschuh.gradle.ktlint") // Version should be inherited from parent
repositories {
// Required to download KtLint
mavenCentral()
}
// Optionally configure plugin
configure<org.jlleitschuh.gradle.ktlint.KtlintExtension> {
debug.set(true)
}
}
Plugin supports KtLint baseline with following limitations:
- Format tasks ignore baseline. See #1072 KtLint issue for more details.
- One baseline file is generated per one Gradle project (module).
Run task ktlintGenerateBaseline
to generate a new baseline.
To test KtLint snapshots add following configuration into project build script (latest KtLint snapshot version name you could find here):
Groovy
repositories {
maven {
url 'https://oss.sonatype.org/content/repositories/snapshots'
}
}
ktlint {
version = "0.41.0-SNAPSHOT"
}
Kotlin
repositories {
maven("https://oss.sonatype.org/content/repositories/snapshots")
}
ktlint {
version.set("0.41.0-SNAPSHOT")
}
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.
Build script snippet for new plugin mechanism introduced in Gradle 2.1:
plugins {
id("org.jlleitschuh.gradle.ktlint-idea") version "<current_version>"
}
For all Gradle versions:
Use the same buildscript
logic as above, but with this instead of the above suggested apply
line. If you also want the GIT pre-commit gradle tasks, keep both apply
variations.
apply plugin: "org.jlleitschuh.gradle.ktlint-idea"
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. Consult the ktlint release notes for more information about the differences between ktlint versions.
Groovy
import org.jlleitschuh.gradle.ktlint.reporter.ReporterType
ktlint {
version = "0.22.0"
debug = true
verbose = true
android = false
outputToConsole = true
outputColorName = "RED"
ignoreFailures = true
enableExperimentalRules = true
additionalEditorconfigFile = file("/some/additional/.editorconfig") // not supported with ktlint 0.47+
additionalEditorconfig = [ // not supported until ktlint 0.49
"max_line_length": "20"
]
disabledRules = ["final-newline"] // not supported with ktlint 0.48+
baseline = file("my-project-ktlint-baseline.xml")
reporters {
reporter "plain"
reporter "checkstyle"
reporter "sarif"
customReporters {
"csv" {
fileExtension = "csv"
dependency = project(":project-reporters:csv-reporter")
}
"yaml" {
fileExtension = "yml"
dependency = "com.example:ktlint-yaml-reporter:1.0.0"
}
}
}
kotlinScriptAdditionalPaths {
include fileTree("scripts/")
}
filter {
exclude("**/generated/**")
include("**/kotlin/**")
}
}
dependencies {
ktlintRuleset "com.github.username:rulseset:main-SNAPSHOT"
ktlintRuleset files("/path/to/custom/rulseset.jar")
ktlintRuleset project(":chore:project-ruleset")
}
or in kotlin script:
Kotlin
import org.jlleitschuh.gradle.ktlint.reporter.ReporterType
configure<org.jlleitschuh.gradle.ktlint.KtlintExtension> {
version.set("0.22.0")
debug.set(true)
verbose.set(true)
android.set(false)
outputToConsole.set(true)
outputColorName.set("RED")
ignoreFailures.set(true)
enableExperimentalRules.set(true)
additionalEditorconfigFile.set(file("/some/additional/.editorconfig")) // not supported with ktlint 0.47+
additionalEditorconfig.set( // not supported until ktlint 0.49
mapOf(
"max_line_length" to "20"
)
)
disabledRules.set(setOf("final-newline")) // not supported with ktlint 0.48+
baseline.set(file("my-project-ktlint-baseline.xml"))
reporters {
reporter(ReporterType.PLAIN)
reporter(ReporterType.CHECKSTYLE)
customReporters {
register("csv") {
fileExtension = "csv"
dependency = project(":project-reporters:csv-reporter")
}
register("yaml") {
fileExtension = "yml"
dependency = "com.example:ktlint-yaml-reporter:1.0.0"
}
}
}
kotlinScriptAdditionalPaths {
include(fileTree("scripts/"))
}
filter {
exclude("**/generated/**")
include("**/kotlin/**")
}
}
dependencies {
ktlintRuleset("com.github.username:rulseset:main-SNAPSHOT")
ktlintRuleset(files("/path/to/custom/rulseset.jar"))
ktlintRuleset(project(":chore:project-ruleset"))
}
It is possible also to define different from default output directory for generated reports (by default it is "build/reports/ktlint"):
Groovy
tasks.withType(org.jlleitschuh.gradle.ktlint.tasks.GenerateReportsTask) {
reportsOutputDirectory = project.layout.buildDirectory.dir("other/location/$name")
}
Kotlin script
tasks.withType<org.jlleitschuh.gradle.ktlint.tasks.GenerateReportsTask> {
reportsOutputDirectory.set(
project.layout.buildDirectory.dir("other/location/$name")
)
}
Note: If Ktlint custom reporter creates report output file internally, for example:
class CsvReporter(
private val out: PrintStream
) : Reporter {
override fun onLintError(file: String, err: LintError, corrected: Boolean) {
val line = "$file;${err.line};${err.col};${err.ruleId};${err.detail};$corrected"
out.println(line)
File("some_other_file.txt").write(line) // <-- Here!!!
}
}
"some_other_file.txt" won't be captured as task output. This may lead to the problem, that task will always be not "UP_TO_DATE" and caching will not work.
By default, KtLint Gradle workers will use at most 256mb of heap size. For some projects it may be not enough, but it is possible to change:
Groovy
tasks.withType(org.jlleitschuh.gradle.ktlint.tasks.BaseKtLintCheckTask).configureEach {
it.workerMaxHeapSize.set("512m")
}
Kotlin script
tasks.withType<org.jlleitschuh.gradle.ktlint.tasks.BaseKtLintCheckTask> {
workerMaxHeapSize.set("512m")
}
This repository provides the following examples of how to set up 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 - applies plugin to Kotlin common multiplatform module
- kotlin-multiplatform-android - applies plugin to Kotlin android multiplatform module
- kotlin-rulesets-using - adds custom example ruleset
- kotlin-reporter-using - adds custom example reporter
This plugin adds following tasks to every project:
loadKtlintReporters
- preloads KtLintReporter
srunKtlintCheckOverKotlinScripts
- runs actual lint check over project Kotlin script filesktlintKotlinScriptCheck
- generates reports and prints issues into Gradle console based on lint check found errors. This task execution depends onloadKtlintReporters
andrunKtlintCheckOverKotlinScripts
tasks execution outputsrunKtlintFormatOverKotlinScripts
- tries to format according to the code style project Kotlin script filesktlintKotlinScriptFormat
- generate reports and prints issues into Gradle console based on found non-formattable errors. This task execution depends onloadKtlintReporters
andrunKtlintFormatOverKotlinScripts
tasks execution outputsktlintCheck
- checks allSourceSet
s and project Kotlin script filesktlintFormat
- tries to format according to the code style allSourceSet
s Kotlin files and project Kotlin script files
Then for each SourceSet
plugin adds following tasks:
runKtlintCheckOver[source set name]SourceSet
- runs actual lint check on every Kotlin file in givenSourceSet
ktlint[source set name]SourceSetCheck
- generates reports and prints issues into Gradle console based on lint check found errors. This task execution depends onloadKtlintReporters
andrunKtlintCheckOver[source set name]SourceSet
tasks execution outputsrunKtlintFormatOver[source set name]SourceSet
- tries to format according to the code style every Kotlin file in givenSourceSet
ktlint[source set name]SourceSetFormat
- reformats files, generates reports and prints issues into Gradle console based on found non-formattable errors. This task execution depends onloadKtlintReporters
andrunKtlintFormatOver[source set name]SourceSet
tasks execution outputs
Following additional tasks are added:
ktlintApplyToIdea
- The task generates IntelliJ IDEA (or Android Studio) Kotlin style files in the project.idea/
folder. Note that this task will overwrite the existing style file.ktlintApplyToIdeaGlobally
- The task generates IntelliJ IDEA (or Android Studio) Kotlin style files in the user home IDEA (or Android Studio) settings folder. Note that this task will overwrite the existing style file.addKtlintCheckGitPreCommitHook
- adds Gitpre-commit
hook, that runs ktlint check over staged files.addKtlintFormatGitPreCommitHook
- adds Gitpre-commit
hook, that runs ktlint format over staged files and adds fixed files back to commit.
All these additional tasks are always added only to the root project.
- Is it possible to not stop task execution if some of the 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 legacy apply method)?
No. These approaches are not equivalent to how they work. The problem that the plugin may not find some of the kotlin plugins if both approaches are used in the project configuration. Especially it is related to the Android plugin.
- Does plugin check change files incrementally?
Yes, check tasks support it. On the first run, the task will check all files in the source set, on subsequent runs it will check only added/modified files.
Format tasks do not check files incrementally.
- I could not filter dynamically attached sources that are located outside of the project dir.
Gradle based filtering are only working for files located inside project (subproject) folder, see gradle/gradle#3417 To filter files outside project dir, use:
exclude { element -> element.file.path.contains("generated/") }
- Running KtLint fails with strange exception (for example, check #383)
Ensure you are not pinning Kotlin version for "ktlint*" configurations added by plugin.
KtLint relies on Kotlin compiler to parse source files. Each version of KtLint are build using specific Kotlin version.
To exclude "ktlint*" Gradle configurations from Kotlin version pinning - use following approach:
configurations.all {
if (!name.startsWith("ktlint")) {
resolutionStrategy {
eachDependency {
// Force Kotlin to our version
if (requested.group == "org.jetbrains.kotlin") {
useVersion("1.3.72")
}
}
}
}
}
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 the plugin: ./plugin/gradlew build
On how to run the current plugin snapshot check on sample projects: ./gradlew ktlintCheck
Running tests from IDEA IDE
To run tests in IDEA IDE, firstly you need to run following gradle task (or after any dependency change):
$ ./plugin/gradlew -p ./plugin pluginUnderTestMetadata
Optionally you can add this step test run configuration.