README.md

Ktlint Maven Plugin

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.