Skip to content

z3d1k/ktlint-maven-plugin

Repository files navigation

Ktlint Maven Plugin

Build Status Maven Central ktlint

Plugin for running ktlint in maven projects.

Usage

Check code style

Just add this code inside <build><plugins>...</plugins></build> section of pom.xml in your project:

...
<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <executions>
        <execution>
            <goals>
                <goal>lint</goal>
            </goals>
        </execution>
    </executions>
</plugin>
...

By default, it would run code style check against standart ruleset before code compilation takes place - on validate phase (see Maven Build Lifecycle for more). Plugin will report violations in maven build log.

If you want to run check after code compilation - you can configure it to run on verify phase like this:

<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <executions>
        <execution>
            <id>ktlint-lint</id>
            <phase>verify</phase>
            <goals>
                <goal>lint</goal>
            </goals>
        </execution>
    </executions>
</plugin>

You also can run it manually by executing mvn ktlint:lint.

Format sources

To format kotlin source files in your project you could add format goal to plugin configuration:

<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <executions>
        <execution>
            <id>ktlint-format</id>
            <phase>validate</phase>
            <goals>
                <goal>format</goal>
            </goals>
        </execution>
    </executions>
</plugin>

to run it automatically on every build, or run it manually mvn ktlint:format.

Using baseline

Ktlint also provides baseline functionality to provide ability to run checks on new code, ignoring existing style violations. To generate baseline file add it's desired path to configuration

...
<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <configuration>
        <baseline>${project.basedir}/baseline.xml</baseline>
    </configuration>
</plugin>
...

and run mvn ktlint:generate-baseline. After this lint goal would use generated file to ignore known violations.

Configuration

Example configuration:

<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <configuration>
         <includes>src/**/*.kt</includes>
         <excludes>src/**/Generated*.kt</excludes>
         <enableExperimentalRules>true</enableExperimentalRules>
         <reporters>
             <checkstyle.output>${project.build.directory}/ktlint.xml</checkstyle.output>
             <json.output>${project.build.directory}/ktlint.json</json.output>
             <plain.output>${project.build.directory}/ktlint.txt</plain.output>
             <plain.color>true</plain.color>
             <plain.pad>false</plain.pad>
             <plain.group_by_file>true</plain.group_by_file>
         </reporters>
         <failOnError>true</failOnError>
     </configuration>
</plugin>

Some options also could be configured through EditorConfig file.

Goals parameters:

Parameter Default value Goals Description
baseline - lint, format, generate-baseline Path to baseline file
includes src/**/*.kt lint, format Use only files, location of which match specified pattern
excludes - lint, format Ignore files, location of which match specified pattern
enableExperimentalRules false lint, format Enable experimental ruleset
failOnError true lint Fail build if any violation found during execution
reporters - lint Configuration of additional reporters, see reporters configuration

Reporters configuration

To enable additional reporters you need to add it's configuration to the <configuration><reporters>...</reporters></configuration>. Parameters should be specified if following format:

<{reporter name}.{parameter name}>{value}</{reporter name}.{parameter name}>

e.g.

<checkstyle.output>${project.build.directory}/ktlint.xml</checkstyle.output>

Every reporter should have output parameter.

By default, following reporters are available: checkstyle, json, html and plain. For more information see ktlint documentation

Using 3rd party rulesets or reporters

To use rulesets or reporters not included in ktlint by default you should add them to plugin dependencies:

<plugin>
    <groupId>com.github.z3d1k</groupId>
    <artifactId>ktlint-maven-plugin</artifactId>
    <version>0.10.0</version>
    <executions>
        ...
    </executions>
    <configuration>
        ...
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>awesome-ktlint-ruleset</artifactId>
            <version>0.1.0</version>
        </dependency>
    </dependencies>
</plugin>

Legal

This project is not affiliated with nor endorsed by JetBrains or Pinterest.

All code, unless specified otherwise, is licensed under the MIT license.