Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jeremymailen/kotlinter-gradle
Painless, fast ktlint plugin for Gradle
https://github.com/jeremymailen/kotlinter-gradle
Last synced: about 1 month ago
JSON representation
Painless, fast ktlint plugin for Gradle
- Host: GitHub
- URL: https://github.com/jeremymailen/kotlinter-gradle
- Owner: jeremymailen
- License: apache-2.0
- Created: 2017-05-09T07:31:48.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T22:28:49.000Z (about 2 months ago)
- Last Synced: 2024-10-22T18:42:50.162Z (about 2 months ago)
- Language: Kotlin
- Homepage:
- Size: 945 KB
- Stars: 612
- Watchers: 9
- Forks: 50
- Open Issues: 24
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ccamel - jeremymailen/kotlinter-gradle - Painless, fast ktlint plugin for Gradle (Kotlin)
README
# Kotlinter Gradle
[](https://github.com/jeremymailen/kotlinter-gradle/actions)
[](https://plugins.gradle.org/plugin/org.jmailen.kotlinter)
Painless Gradle plugin for linting and formatting Kotlin source files using the awesome [ktlint](https://ktlint.github.io) 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.
### Installation
Available on the Gradle Plugins Portal: https://plugins.gradle.org/plugin/org.jmailen.kotlinter
#### Single module
Kotlin
```kotlin
plugins {
id("org.jmailen.kotlinter") version "4.4.1"
}
```
Groovy
```groovy
plugins {
id "org.jmailen.kotlinter" version "4.4.1"
}
```
#### Multi-module and Android
Kotlin
Root `build.gradle.kts`
```kotlin
plugins {
id("org.jmailen.kotlinter") version "4.4.1" apply false
}
```
Each module `build.gradle.kts` with Kotlin source
```kotlin
plugins {
id("org.jmailen.kotlinter")
}
```
Groovy
Root `build.gradle`
```groovy
plugins {
id 'org.jmailen.kotlinter' version "4.4.1" apply false
}
```
Each module `build.gradle` with Kotlin source
```groovy
plugins {
id 'org.jmailen.kotlinter'
}
```
### Compatibility
| 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 | - |
### Features
- Supports Kotlin Gradle plugins:
- [JVM](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.jvm)
- [Multiplatform](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.multiplatform)
- [Android](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.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: `formatKotlin`*`SourceSet`* and `lintKotlin`*`SourceSet`*.
### 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
```kotlin
tasks.check {
dependsOn("installKotlinterPrePushHook")
}
```
Groovy
```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 these defaults).
Kotlin
```kotlin
kotlinter {
failBuildWhenCannotAutoFormat = false
ignoreFailures = false
reporters = arrayOf("checkstyle", "plain")
}
```
Groovy
```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
### Editorconfig
Kotlinter will configure itself using an `.editorconfig` file if one is present.
This configuration includes code style and linting rules.
See [KtLint configuration](https://pinterest.github.io/ktlint/latest/rules/configuration-ktlint/) for details.
### Customizing Tasks
The `formatKotlin`*`SourceSet`* and `lintKotlin`*`SourceSet`* tasks inherit from [SourceTask](https://docs.gradle.org/current/dsl/org.gradle.api.tasks.SourceTask.html)
so you can customize includes, excludes, and source.
Kotlin
```kotlin
tasks.withType {
this.source = this.source.minus(fileTree("src/generated")).asFileTree
}
tasks.withType {
this.source = this.source.minus(fileTree("src/generated")).asFileTree
}
```
Groovy
```groovy
tasks.named("lintKotlinMain") {
source = source - fileTree("$buildDir/generated")
}
```
Note that exclude paths are relative to the package root.
### 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
```kotlin
import org.jmailen.gradle.kotlinter.tasks.LintTask
import org.jmailen.gradle.kotlinter.tasks.FormatTask
tasks.register("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("ktFormat") {
group = "formatting"
source(files("src"))
report.set(file("build/format-report.txt"))
}
```
Groovy
```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 ktlint version
If you need to use a different version of `ktlint` you can override the dependency.
Kotlin or Groovy
```kotlin
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
```kotlin
dependencies {
implementation(platform("com.pinterest.ktlint:ktlint-bom:1.2.1"))
implementation("org.jmailen.gradle:kotlinter-gradle:4.4.1")
}
```
### Custom Rules
You can add custom ktlint RuleSets using the `buildscript` classpath:
Kotlin
```kotlin
buildscript {
dependencies {
classpath(files("libs/my-custom-ktlint-rules.jar"))
classpath("org.other.ktlint:custom-rules:1.0")
}
}
```
Groovy
```groovy
buildscript {
dependencies {
classpath files('libs/my-custom-ktlint-rules.jar')
classpath 'org.other.ktlint:custom-rules:1.0'
}
}
```