Kotlin linter in spirit of feross/standard (JavaScript) and gofmt (Go).
Features:
- No configuration. Which means no decisions to make, nothing to argue about and no special files to manage.
While this might sound extreme, keep in mind thatktlint
tries to capture (reflect) official code style from kotlinlang.org (+ we support additional 3rd party rulesets). - Built-in formatter. So that you wouldn't have to fix all style violations by hand.
- A single executable jar with all dependencies included.
Standard rules | Installation | Usage | Integration with Maven / Gradle / IntelliJ IDEA | Creating a ruleset | FAQ
- 4 spaces for indentation*.
- No semicolons (unless used to separate multiple statements on the same line).
- No wildcard / unused imports.
- No consecutive blank lines.
- No trailing whitespaces.
- No Unit returns;
- Consistent order of modifiers;
- Consistent spacing after keywords, commas; around colons, curly braces, infix operators, etc.
* Starting from 0.8.0 value of
indent_size
specified under[*{kt,kts}]
section in .editorconfig takes precedence (if any). Official recommendation is to use 4 spaces, though. (see #43 for details)
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/shyiko/ktlint/releases/download/0.8.1/ktlint &&
chmod a+x ktlint
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.
... or just download ktlint
from the "release(s)" 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
).
On Mac OS X (or Linux) one can also use brew -
brew install shyiko/ktlint/ktlint
.
# check the style of all Kotlin files inside the current dir (recursively)
# (hidden folders will be skipped)
$ ktlint
src/main/kotlin/Main.kt:10:10: Unused import
# check only certain locations (prepend ! to negate the pattern)
$ ktlint "src/**/*.kt" "!src/**/*Test.kt"
# auto-correct style violations
# (if some errors cannot be fixed automatically they will be printed to stderr)
$ ktlint -F "src/**/*.kt"
on Windows you'll have to use
java -jar ktlint ...
.
ktlint --help
for more.
... with Maven
pom.xml
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.7</version>
<executions>
<execution>
<id>ktlint</id>
<phase>verify</phase>
<configuration>
<target name="ktlint">
<java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true"
classname="com.github.shyiko.ktlint.Main" classpathref="maven.plugin.classpath">
<arg value="src/**/*.kt"/>
</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"
classname="com.github.shyiko.ktlint.Main" classpathref="maven.plugin.classpath">
<arg value="-F"/>
<arg value="src/**/*.kt"/>
</java>
</target>
</configuration>
<goals><goal>run</goal></goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.github.shyiko</groupId>
<artifactId>ktlint</artifactId>
<version>0.8.1</version>
</dependency>
<!-- additional 3rd party ruleset(s) can be specified here -->
</dependencies>
</plugin>
...
To check code style - mvn antrun:run@ktlint
(it's also bound to mvn verify
).
To run formatter - mvn antrun:run@ktlint-format
.
... with Gradle
build.gradle
apply plugin: 'java'
repositories {
mavenCentral()
}
configurations {
ktlint
}
dependencies {
ktlint 'com.github.shyiko:ktlint:0.8.1'
// additional 3rd party ruleset(s) can be specified here
// just add them to the classpath (ktlint 'groupId:artifactId:version') and
// ktlint will pick them up
}
task ktlint(type: JavaExec) {
main = "com.github.shyiko.ktlint.Main"
classpath = configurations.ktlint
args "src/**/*.kt"
}
check.dependsOn ktlint
task ktlintFormat(type: JavaExec) {
main = "com.github.shyiko.ktlint.Main"
classpath = configurations.ktlint
args "-F", "src/**/*.kt"
}
To check code style - gradle ktlint
(it's also bound to gradle check
).
To run formatter - gradle ktlintFormat
.
Another option is to use Gradle plugin (in order of appearance):
Each plugin has some unique features (like incremental build support in case of jeremymailen/kotlinter-gradle) so check them out.
You might also want to take a look at diffplug/spotless which has 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.
... with IntelliJ IDEA
While this is not strictly necessary it makes Intellij IDEA's built-in formatter produce 100% ktlint-compatible code.
curl -sSLO https://github.com/shyiko/ktlint/releases/download/0.8.1/ktlint-intellij-idea-integration
chmod a+x ktlint-intellij-idea-integration
# you can also download ktlint-intellij-idea-integration manually from
# https://github.com/shyiko/ktlint/releases
# inside project's root directory
ktlint-intellij-idea-integration apply
Go to File -> Settings... -> Editor
Code Style -> Manage... -> Import -> Intellij IDEA code style XML
, select codestyles/ktlint.xml.Inspections -> Manage -> Import
, select inspection/ktlint.xml.
Go to File -> Settings... -> Editor
Code Style -> Kotlin
- open
Imports
tab, select allUse single name import
options and removeimport java.util.*
fromPackages to Use Import with '*'
. - (optional but recommended) open
Wrapping and Braces
tab, uncheckMethod declaration parameters -> Align when multiline
. - (optional but recommended) open
Tabs and Indents
tab, changeContinuation indent
to 4.
- open
Inspections
- change
Severity
level ofUnused import directive
,Redundant semicolon
and (optional but recommended)Unused symbol
toERROR
.
- change
... with GNU Emacs
Integrated with something else? Send a PR.
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.github.shyiko.ktlint.core.RuleSetProvider
file
containing a fully qualified name of your RuleSetProvider implementation).
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).
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.
Once packaged in a JAR 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"
# you can also use <groupId>:<artifactId>:<version> triple in which case artifact is
# downloaded from Maven Central, JCenter or JitPack (depending on where it's located and
# whether or not it's already present in local Maven cache)
$ ktlint -R com.github.username:rulseset:master-SNAPSHOT
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
Make sure to read CONTRIBUTING.md.
git clone https://github.com/shyiko/ktlint && cd ktlint
./mvnw # shows how to build, test, etc. project
This project is not affiliated with or endorsed by the Jetbrains.
All code, unless specified otherwise, is licensed under the MIT license.
Copyright (c) 2016 Stanley Shyiko.