To use Kotlinter, apply the org.jmailen.kotlinter plugin. For multi-module projects, it is recommended to define the plugin in the root build.gradle.kts with apply false and then apply it to each specific module that contains Kotlin source code.

### Single module (Kotlin)
```kotlin
plugins {
    id("org.jmailen.kotlinter") version "<release>"
}

Multi-module (Kotlin)

Root build.gradle.kts

plugins {
    id("org.jmailen.kotlinter") version "<release>" apply false
}

Module build.gradle.kts

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

You can install a git pre-push hook using the installKotlinterPrePushHook task. This hook runs lintKotlin and, if errors are found, attempts to run formatKotlin before exiting.

Requirements:

1. You must apply the kotlinter plugin to your root project.
2. If using git worktree, install the hook from the parent git directory.

To ensure the hook is installed automatically during builds, make the check task depend on it.

tasks.check {
    dependsOn("installKotlinterPrePushHook")
}

Use the kotlinter extension block to customize plugin behavior.

Available options:

• ktlintVersion: String. Overrides the default ktlint version.
• ignoreFormatFailures: Boolean. If false, the formatKotlin task will fail the build when auto-format cannot fix a lint error.
• ignoreLintFailures: Boolean. If true, the lintKotlin task will not fail the build on lint errors.
• reporters: Array of Strings. Specifies the output formats. Supported values: checkstyle, html, json, plain, sarif.

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

The lintKotlin and formatKotlin tasks inherit from SourceTask, allowing you to customize includes and excludes.

Because exclude paths are relative to the package root, to exclude files at the src directory level, use a predicate on the file path.

tasks.withType<LintTask> {
    exclude { it.file.path.contains("/src/generated") }
}

tasks.withType<FormatTask> {
    exclude { it.file.path.contains("/src/generated") }
}

If you need to lint or format custom source sets not covered by autoconfiguration, you can manually register LintTask and FormatTask.

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"))
}

To use custom ktlint rules, add them to the ktlint dependency configuration.

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

When applied to a supported Kotlin plugin (JVM, Multiplatform, or Android), Kotlinter provides the following tasks:

• formatKotlin: Formats Kotlin source code according to ktlint rules (or warns if auto-format is not possible).
• lintKotlin: Reports Kotlin lint errors and fails the build by default.
• check: Automatically becomes dependent on lintKotlin.

Tasks are also available per source set, following the pattern formatKotlin<SourceSet> and lintKotlin<SourceSet> (e.g., lintKotlinMain).

If you are using Kotlin plugins (JVM, Multiplatform, JS) or Android, Kotlinter registers individual lint tasks for each source set. These tasks follow the naming convention lintKotlin<SourceSet> (e.g., lintKotlinMain or lintKotlinTest).

# Example for a standard Kotlin project with a 'main' source set
./gradlew lintKotlinMain

The formatKotlin task automatically formats Kotlin source files according to the configured ktlint rules.

./gradlew formatKotlin

Similar to linting, Kotlinter registers individual formatting tasks for each source set using the convention formatKotlin<SourceSet> (e.g., formatKotlinMain).

# Example for a standard Kotlin project with a 'main' source set
./gradlew formatKotlinMain

The lintKotlin task runs linting on all Kotlin source files in the project. This task is automatically added as a dependency to the standard Gradle check task, so running ./gradlew check will also execute linting.

./gradlew lintKotlin