Step 1. Add the JitPack repository to your build file
Add it in your root build.gradle at the end of repositories:
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
mavenCentral()
maven { url 'https://jitpack.io' }
}
}
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Add it in your build.sbt at the end of resolvers:
resolvers += "jitpack" at "https://jitpack.io"
Add it in your project.clj at the end of repositories:
:repositories [["jitpack" "https://jitpack.io"]]
Step 2. Add the dependency
dependencies {
implementation 'com.github.jeremymailen:ktlint:0.8.3'
}
<dependency>
<groupId>com.github.jeremymailen</groupId>
<artifactId>ktlint</artifactId>
<version>0.8.3</version>
</dependency>
libraryDependencies += "com.github.jeremymailen" % "ktlint" % "0.8.3"
:dependencies [[com.github.jeremymailen/ktlint "0.8.3"]]
ktlint
tries to capture (reflect) official code style* from kotlinlang.org and Android Kotlin Style Guide
(+ we respect your .editorconfig and support additional ruleset|s).plain
(+ plain?group_by_file
), json
and checkstyle
reporters are available out-of-the-box.
It's also easy to create your own..editorconfig
indent_size
with no continuation indent (see EditorConfig section for more) (id: indent
)no-semi
)import
s (id: no-unused-imports
)no-consecutive-blank-lines
)}
(id: no-blank-line-before-rbrace
)no-trailing-spaces
)Unit
returns (fun fn {}
instead of fun fn: Unit {}
) (id: no-unit-return
){}
) class bodies (id: no-empty-class-body
)import
s (id: no-wildcard-imports
).
, ?.
and ?:
should be placed on the next line (id: chain-wrapping
)=
) operator the break comes after the symbol (id: no-line-break-before-assignment
)$v
instead of ${v}
, ${p.v}
instead of ${p.v.toString()}
) (id: string-template
)modifier-order
)colon-spacing
, comma-spacing
, curly-spacing
, dot-spacing
, double-colon-spacing
, keyword-spacing
, op-spacing
, paren-spacing
, range-spacing
)insert_final_newline=false
in .editorconfig to disable (see EditorConfig section for more)). (id: final-newline
)import-ordering
)New rules will be added into the experimental ruleset, which can be enabled
by passing the --experimental
flag to ktlint
.
experimental:annotation
)experimental:annotation-spacing
)experimental:argument-list-wrapping
)experimental:enum-entry-name-case
)experimental:multiline-if-else
)experimental:no-empty-first-line-in-method-block
)experimental:package-name
)experimental:spacing-around-angle-brackets
)::
(id: experimental:double-colon-spacing
)experimental:unary-op-spacing
)experimental:spacing-between-declarations-with-annotations
)experimental:spacing-between-declarations-with-comments
)ktlint recognizes the following .editorconfig properties (provided they are specified under [*.{kt,kts}]
):
(values shown below are the defaults and do not need to be specified explicitly)
[*.{kt,kts}]
# possible values: number (e.g. 2), "unset" (makes ktlint ignore indentation completely)
indent_size=4
# true (recommended) / false
insert_final_newline=true
# possible values: number (e.g. 120) (package name, imports & comments are ignored), "off"
# it's automatically set to 100 on `ktlint --android ...` (per Android Kotlin Style Guide)
max_line_length=off
.editorconfig
autoformat issueUnfortunately IntelliJ IDEA has .editorconfig
autoformat issue
that adds additional space into glob statements.
For example, [*{kt,kts}]
is formatted into [*{kt, kts}]
(original ktlint issue).
Such behaviour violates .editorconfig
specification and leads to ignoring this section when ktlint is parsing it.
# Comma-separated list of rules to disable (Since 0.34.0)
# Note that rules in any ruleset other than the standard ruleset will need to be prefixed
# by the ruleset identifier.
disabled_rules=no-wildcard-imports,experimental:annotation,my-custom-ruleset:my-custom-rule
# Defines the imports layout. The layout can be composed by the following symbols:
# "*" - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well.
# "|" - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout.
# "^" - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports.
# import paths - these can be full paths, e.g. "java.util.List.*" as well as wildcard paths, e.g. "kotlin.**"
# Examples (we use ij_kotlin_imports_layout to set an imports layout for both ktlint and IDEA via a single property):
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
# According to https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods it is acceptable to write method names
# in natural language. When using natural language, the description tends to be longer. Allow lines containing an identifier between
# backticks to be longer than the maximum line length. (Since 0.41.0)
[**/test/**.kt]
ktlint_ignore_back_ticked_identifier=true
You could override properties for specific directories inside your project:
[*.{kt,kts}]
disabled_rules=import-ordering
# Note that in this case 'import-ordering' rule will be active and 'indent' will be disabled
[api/*.{kt,kts}]
disabled_rules=indent
You can try ktlint
online here using the standard or a custom ruleset without installing it to your PC.
To contribute or get more info, please visit the GitHub repository.
Skip all the way to the "Integration" section if you don't plan to use
ktlint
's command line interface.
curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.42.1/ktlint &&
chmod a+x ktlint &&
sudo mv ktlint /usr/local/bin/
... or just download ktlint
from the releases page
ktlint.asc
contains PGP signature which you can verify with:
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc
curl -sS https://keybase.io/ktlint/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc
On macOS (or Linux) you can also use brew - brew install ktlint
- or MacPorts - port install ktlint
.
On Arch Linux, you can install ktlint <sup>AUR</sup>.
If you don't have curl installed - replace
curl -sL
withwget -qO-
.If you are behind a proxy see - curl / wget manpage. Usually simple
http_proxy=http://proxy-server:port https_proxy=http://proxy-server:port curl -sL ...
is enough.
# Get help about all available commands
$ ktlint --help
# Check the style of all Kotlin files (ending with '.kt' or '.kts') inside the current dir (recursively).
# Hidden folders will be skipped.
$ ktlint
# Check only certain locations starting from the current directory.
#
# Prepend ! to negate the pattern, KtLint uses .gitignore pattern style syntax.
# Globs are applied starting from the last one.
#
# Hidden folders will be skipped.
# Check all '.kt' files in 'src/' directory, but ignore files ending with 'Test.kt':
ktlint "src/**/*.kt" "!src/**/*Test.kt"
# Check all '.kt' files in 'src/' directory, but ignore 'generated' directory and its subdirectories:
ktlint "src/**/*.kt" "!src/**/generated/**"
# Auto-correct style violations.
# If some errors cannot be fixed automatically they will be printed to stderr.
$ ktlint -F "src/**/*.kt"
# Print style violations grouped by file.
$ ktlint --reporter=plain?group_by_file
# Print style violations as usual + create report in checkstyle format, specifying report location.
$ ktlint --reporter=plain --reporter=checkstyle,output=ktlint-report-in-checkstyle-format.xml
# Check against a baseline file.
$ ktlint --baseline=ktlint-baseline.xml
# Install git hook to automatically check files for style violations on commit.
# Run "ktlint installGitPrePushHook" if you wish to run ktlint on push instead.
$ ktlint installGitPreCommitHook
on Windows you'll have to use
java -jar ktlint ...
.
ktlint --help
for more.
pom.xml
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
<executions>
<execution>
<id>ktlint</id>
<phase>verify</phase>
<configuration>
<target name="ktlint">
<java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true"
classpathref="maven.plugin.classpath" classname="com.pinterest.ktlint.Main">
<arg value="src/**/*.kt"/>
<!-- to generate report in checkstyle format prepend following args: -->
<!--
<arg value="--reporter=plain"/>
<arg value="--reporter=checkstyle,output=${project.build.directory}/ktlint.xml"/>
-->
<!-- see https://github.com/pinterest/ktlint#usage for more -->
</java>
</target>
</configuration>
<goals><goal>run</goal></goals>
</execution>
<execution>
<id>ktlint-format</id>
<configuration>
<target name="ktlint">
<java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true"
classpathref="maven.plugin.classpath" classname="com.pinterest.ktlint.Main">
<arg value="-F"/>
<arg value="src/**/*.kt"/>
</java>
</target>
</configuration>
<goals><goal>run</goal></goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.pinterest</groupId>
<artifactId>ktlint</artifactId>
<version>0.42.1</version>
</dependency>
<!-- additional 3rd party ruleset(s) can be specified here -->
</dependencies>
</plugin>
...
If you want ktlint to run before code compilation takes place - change
<phase>verify</phase>
to<phase>validate</phase>
(see Maven Build Lifecycle for more).
To check code style - mvn antrun:run@ktlint
(it's also bound to mvn verify
).
To run formatter - mvn antrun:run@ktlint-format
.
Another option is to use a dedicated Maven plugin - gantsign/ktlint-maven-plugin.
Gradle plugins (in order of appearance):
jlleitschuh/ktlint-gradle
Gradle plugin that automatically creates check and format tasks for project Kotlin sources,
supports different kotlin plugins and Gradle build caching.
jeremymailen/kotlinter-gradle
Gradle plugin featuring incremental build support, file reports, and *.kts
source support.
You might also want to take a look at diffplug/spotless or autostyle/autostyle that have a built-in support for ktlint. In addition to linting/formatting kotlin code it allows you to keep license headers, markdown documentation, etc. in check.
build.gradle
// kotlin-gradle-plugin must be applied for configuration below to work
// (see https://kotlinlang.org/docs/reference/using-gradle.html)
apply plugin: 'java'
repositories {
mavenCentral()
}
configurations {
ktlint
}
dependencies {
ktlint("com.pinterest:ktlint:0.42.1") {
attributes {
attribute(Bundling.BUNDLING_ATTRIBUTE, getObjects().named(Bundling, Bundling.EXTERNAL))
}
}
// additional 3rd party ruleset(s) can be specified here
// just add them to the classpath (e.g. ktlint 'groupId:artifactId:version') and
// ktlint will pick them up
}
task ktlint(type: JavaExec, group: "verification") {
description = "Check Kotlin code style."
classpath = configurations.ktlint
main = "com.pinterest.ktlint.Main"
args "src/**/*.kt"
// to generate report in checkstyle format prepend following args:
// "--reporter=plain", "--reporter=checkstyle,output=${buildDir}/ktlint.xml"
// to add a baseline to check against prepend following args:
// "--baseline=ktlint-baseline.xml"
// see https://github.com/pinterest/ktlint#usage for more
}
check.dependsOn ktlint
task ktlintFormat(type: JavaExec, group: "formatting") {
description = "Fix Kotlin code style deviations."
classpath = configurations.ktlint
main = "com.pinterest.ktlint.Main"
args "-F", "src/**/*.kt"
}
To check code style - gradle ktlint
(it's also bound to gradle check
).
To run formatter - gradle ktlintFormat
.
See Making your Gradle tasks incremental by Niklas Baudy on how to make tasks above incremental.
build.gradle.kts
val ktlint by configurations.creating
dependencies {
ktlint("com.pinterest:ktlint:0.42.1") {
attributes {
attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL))
}
}
// ktlint(project(":custom-ktlint-ruleset")) // in case of custom ruleset
}
val outputDir = "${project.buildDir}/reports/ktlint/"
val inputFiles = project.fileTree(mapOf("dir" to "src", "include" to "**/*.kt"))
val ktlintCheck by tasks.creating(JavaExec::class) {
inputs.files(inputFiles)
outputs.dir(outputDir)
description = "Check Kotlin code style."
classpath = ktlint
main = "com.pinterest.ktlint.Main"
args = listOf("src/**/*.kt")
}
val ktlintFormat by tasks.creating(JavaExec::class) {
inputs.files(inputFiles)
outputs.dir(outputDir)
description = "Fix Kotlin code style deviations."
classpath = ktlint
main = "com.pinterest.ktlint.Main"
args = listOf("-F", "src/**/*.kt")
}
While this is not strictly necessary it makes Intellij IDEA's built-in formatter produce 100% ktlint-compatible code.
To change the code style config files in a single IDEA project
Run ktlint executable with the appropriate flag:
(inside project's root directory)
ktlint applyToIDEAProject
# or if you want to be compliant with Android Kotlin Style Guide
ktlint --android applyToIDEAProject
To change the code style config files for all IDEA projects
Run ktlint executable with the appropriate flag:
ktlint applyToIDEA
Or if you want to use android specific code style:
ktlint --android applyToIDEA
Go to <kbd>File</kbd> -> <kbd>Settings...</kbd> -> <kbd>Editor</kbd>
Kotlin
/ Optimize imports on the fly (for current project)
.Line comment at first column
;Add a space at comment start
.Use single name import
(all of them);import java.util.*
from Packages to Use Import with '*'
.Keep Maximum Blank Lines
/ In declarations
& In code
to 1 and Before '}'
to 0.Function declaration parameters
(OR Methods declartion parameters
for older version) / Align when multiline
.Continuation indent
to the same value as Indent
(4 by default).Severity
level of Unused import directive
and Redundant semicolon
under Kotlin
-> Redundant constructs
to ERROR
.See w0rp/ale.
Integrated with something else? Send a PR.
See Mega-Linter: 70+ linters aggregated in a single tool for CI, including ktlint activated out of the box
See also Writing your first ktlint rule by Niklas Baudy.
In a nutshell: "ruleset" is a JAR containing one or more Rules gathered together in a RuleSet. ktlint
is relying on
ServiceLoader to discover all available "RuleSet"s
on the classpath (as a ruleset author, all you need to do is to include a META-INF/services/com.pinterest.ktlint.core.RuleSetProvider
file
containing a fully qualified name of your RuleSetProvider implementation).
Once packaged in a JAR <sup>e.g. via ./gradlew build
</sup> you can load it with
# enable additional 3rd party ruleset by pointing ktlint to its location on the file system
$ ktlint -R /path/to/custom/rulseset.jar "src/test/**/*.kt"
Loading custom (3rd party) ruleset via built-in maven dependency resolver is deprecated, see https://github.com/pinterest/ktlint/issues/451.
A complete sample project (with tests and build files) is included in this repo under the ktlint-ruleset-template directory (make sure to check NoVarRuleTest as it contains some useful information).
While writing/debugging Rules it's often helpful to have an AST
printed out to see the structure rules have to work with. ktlint >= 0.15.0 has a printAST
subcommand (or --print-ast
flag for ktlint < 0.34.0) specifically for this purpose
(usage: ktlint --color printAST <file>
).
An example of the output is shown below.
$ printf "fun main() {}" | ktlint --color printAST --stdin
1: ~.psi.KtFile (~.psi.stubs.elements.KtFileElementType.kotlin.FILE)
1: ~.psi.KtPackageDirective (~.psi.stubs.elements.KtPlaceHolderStubElementType.PACKAGE_DIRECTIVE) ""
1: ~.psi.KtImportList (~.psi.stubs.elements.KtPlaceHolderStubElementType.IMPORT_LIST) ""
1: ~.psi.KtScript (~.psi.stubs.elements.KtScriptElementType.SCRIPT)
1: ~.psi.KtBlockExpression (~.KtNodeType.BLOCK)
1: ~.psi.KtNamedFunction (~.psi.stubs.elements.KtFunctionElementType.FUN)
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtKeywordToken.fun) "fun"
1: ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (~.c.i.p.tree.IElementType.WHITE_SPACE) " "
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtToken.IDENTIFIER) "main"
1: ~.psi.KtParameterList
(~.psi.stubs.elements.KtPlaceHolderStubElementType.VALUE_PARAMETER_LIST)
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtSingleValueToken.LPAR) "("
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtSingleValueToken.RPAR) ")"
1: ~.c.i.p.impl.source.tree.PsiWhiteSpaceImpl (~.c.i.p.tree.IElementType.WHITE_SPACE) " "
1: ~.psi.KtBlockExpression (~.KtNodeType.BLOCK)
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtSingleValueToken.LBRACE) "{"
1: ~.c.i.p.impl.source.tree.LeafPsiElement (~.lexer.KtSingleValueToken.RBRACE) "}"
format: <line_number:> <node.psi::class> (<node.elementType>) "<node.text>"
legend: ~ = org.jetbrains.kotlin, c.i.p = com.intellij.psi
Take a look at ktlint-reporter-plain.
In short, all you need to do is to implement a
Reporter and make it available by registering
a custom ReporterProvider using
META-INF/services/com.pinterest.ktlint.core.ReporterProvider
. Pack all of that into a JAR and you're done.
To load a custom (3rd party) reporter use ktlint --reporter=name,artifact=/path/to/custom-ktlint-reporter.jar
(see ktlint --help
for more).
Loading custom (3rd party) reporter via built-in maven dependency resolver is deprecated, see https://github.com/pinterest/ktlint/issues/451.
Third-party:
[![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)
Simplicity.
Spending time on configuration (& maintenance down the road) of hundred-line long style config file(s) is counter-productive. Instead of wasting your energy on something that has no business value - focus on what really matters (not debating whether to use tabs or spaces).
By using ktlint you put the importance of code clarity and community conventions over personal preferences. This makes things easier for people reading your code as well as frees you from having to document & explain what style potential contributor(s) have to follow.
ktlint is a single binary with both linter & formatter included. All you need is to drop it in (no need to get overwhelmed while choosing among dozens of code style options).
Absolutely, "no configuration" doesn't mean "no extensibility". You can add your own ruleset(s) to discover potential bugs, check for anti-patterns, etc.
See Creating A Ruleset.
This is meant primarily as an escape latch for the rare cases when ktlint is not able to produce the correct result (please report any such instances using GitHub Issues).
To disable a specific rule you'll need to turn on the verbose mode (ktlint --verbose ...
). At the end of each line
you'll see an error code. Use it as an argument for ktlint-disable
directive (shown below).
import package.* // ktlint-disable no-wildcard-imports
/* ktlint-disable no-wildcard-imports */
import package.a.*
import package.b.*
/* ktlint-enable no-wildcard-imports */
To disable all checks:
import package.* // ktlint-disable
See the EditorConfig section for details on how to use the disabled_rules
property.
You may also pass a list of disabled rules via the --disabled_rules
command line flag. It has the same syntax as the EditorConfig property.
Make sure to read CONTRIBUTING.md.
git clone https://github.com/pinterest/ktlint && cd ktlint
./mvnw # shows how to build, test, run, etc. project
To open ktlint in Intellij IDEA:
<kbd>File</kbd> -> <kbd>Open...</kbd> (you may need to right-click onpom.xml
(in the project dir) and then <kbd>Maven</kbd> -> <kbd>Reimport</kbd>).
You'll also need to set "Project SDK" to 1.8, "Project language level" to 8 in "Project Settings" (<kbd>File</kbd> -> <kbd>Project Structure...</kbd>).
To runktlint
- right-click onktlint/src/main/kotlin/com/pinterest/ktlint/Main.kt
-> <kbd>Run</kbd>.
master
snapshotWhenever a commit is added to the master
branch a snapshot build is automatically uploaded to Sonatype's snapshots repository.
If you are eager to try upcoming changes (that might or might not be included in the next stable release) you can do
so by changing version of ktlint to <latest-version>-SNAPSHOT
+ adding a repo:
...
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
<releases>
<enabled>false</enabled>
</releases>
</repository>
...
repositories {
maven {
url "https://oss.sonatype.org/content/repositories/snapshots"
}
}
Additionally, project publishes snapshots build against latest kotlin development version. To use them, change version
of ktlint to <latest-version>-kotlin-dev-SNAPSHOT
.
This project is not affiliated with nor endorsed by JetBrains.
All code, unless specified otherwise, is licensed under the MIT license.
Copyright (c) 2019 Pinterest, Inc.
Copyright (c) 2016-2019 Stanley Shyiko.