Command line
Command Line usage
If you don't plan to use ktlint's command line interface then you can skip this section.
Download and verification¶
Download manually from GitHub¶
All releases of ktlint can be downloaded from the releases page.
Each release contains multiple ways to run ktlint:
ktlintis the executable JAR and requires a JVM.ktlint_linux-x86-64is a native executable for Linux x86-64.ktlint_darwin-arm64is a native executable for macOS Apple Silicon.ktlint_windows-x86-64.exeis a native executable for Windows x86-64.ktlint.batstarts the executable JAR on Windows.
Native executables and custom rulesets/reporters
The native executables (ktlint_linux-x86-64, ktlint_darwin-arm64, ktlint_windows-x86-64.exe) are ahead-of-time compiled with GraalVM native-image and cannot load ruleset or reporter JARs supplied at runtime via the command line. Only the built-in rulesets and reporters are available. If you need custom or third-party rulesets/reporters, use the executable JAR (ktlint) instead.
Download using curl (Linux or macOS)¶
A particular version of ktlint can be downloaded with the commands below. Each command uses curl for downloading. The downloaded file will be renamed to /usr/local/bin/ktlint and changed to an executable file.
Curl not installed or behind proxy
If you don't have curl installed - replace curl -sL with wget -qO-.
If you are behind a proxy see - curl / wget manpage. Usually simple:
curl -sSLO https://github.com/ktlint/ktlint/releases/download/2.0.0-ALPHA-4/ktlint_linux-x86-64 && chmod a+x ktlint_linux-x86-64 && sudo mv ktlint_linux-x86-64 /usr/local/bin/ktlint
curl -sSLO https://github.com/ktlint/ktlint/releases/download/2.0.0-ALPHA-4/ktlint_darwin-arm64 && chmod a+x ktlint_darwin-arm64 && sudo mv ktlint_darwin-arm64 /usr/local/bin/ktlint
curl -sSLO https://github.com/ktlint/ktlint/releases/download/2.0.0-ALPHA-4/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/
Download on Windows¶
Download ktlint_windows-x86-64.exe from the release and add the directory containing it to your %PATH%.
Invoke-WebRequest -Uri https://github.com/ktlint/ktlint/releases/download/2.0.0-ALPHA-4/ktlint_windows-x86-64.exe -OutFile ktlint.exe
Run ktlint on Microsoft Windows
Ktlint can be run in following ways on Microsoft Windows:
* Use the native executable ktlint_windows-x86-64.exe provided as part of the release
* Use the ktlint.bat batch file provided as part of the release. Add the batch file to your %PATH% environment variable for easy access
* Run ktlint using Git Bash
* Run the executable JAR as java -jar ktlint
Verification of download¶
ktlint.asc contains PGP signature which you can verify with:
Note
Ktlint 2.x has been moved to a separate organization, and no longer affiliated with Pinterest open source projects. Our public signature can be downloaded from the Unbuntu Key Server.
curl -sS "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x0F631C1DD2A656869B1F47350FDF10E71780F7FD" | gpg --import && gpg --verify ktlint.asc
Note
As reported in this issue the https://keybase.io/ktlint/pgp_keys.asc is no longer available. Our public signature can be downloaded from the Unbuntu Key Server.
curl -sS "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xadbc987d1a7b91db6b0aaa81995efbf4a3d20beb" | gpg --import && gpg --verify ktlint.asc
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc
Package managers¶
ktlint can be installed via several OS specific package managers.
Install with brew on macOS or Homebrew on Linux
Install with MacPorts
Command line usage¶
Rule set(s)¶
When no arguments are specified, the style of all Kotlin files (ending with '.kt' or '.kts') inside the current dir (recursively) are validated with the rules from the standard ruleset. Hidden folders will be skipped.
Note
The experimental rules in the standard rule set will only be run when .editorconfig property ktlint_experimental = enabled is set.
To validate with a custom ruleset run command below:
ktlint --ruleset=/path/to/custom-ruleset.jar
# or
ktlint -R /path/to/custom-ruleset.jar
Note
If the custom rule set contains rules that are marked as experimental, those rule will only be run when .editorconfig property ktlint_experimental = enabled is set.
Format (autocorrect)¶
Most style violations can be corrected automatically. Errors that can not be corrected, are printed to stderr.
Globs¶
Globs can be used to specify more exactly what files and directories are to be validated. ktlint uses the .gitignore pattern style syntax for globs. Globs are processed from left to right. Prepend a glob with ! to negate it. 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/**'
Violation reporting¶
ktlint supports different type of reporters for lint violations. When not specified the plain reporter is used. Optionally the plain reporter can group the violations per file.
When using ktlint on an existing project, the number of violations can be huge. To get more insights in which rules are causing the most violations, the plain-summary reporter can be used.
Other built-in reporters are: json, sarif, checkstyle, and html
Style violations can be written to an output file which is convenient when multiple reporters are specified. In example below, the plain reporter is used to write to the console while the checkstyle reports is written to a file:
ktlint --reporter=plain --reporter=checkstyle,output=ktlint-report-in-checkstyle-format.xml
If resolving all existing errors in a project is unwanted, it is possible to create a baseline and in following invocations compare violations against this baseline. Violations that are registered in the baseline, will be ignored silently. Remove the baseline file in case you want to reset it.
ktlint --baseline=ktlint-baseline.xml # Baseline is created when not existing
Logging¶
Logging information is written to stdout. The amount of logging can be influenced by setting the minimal log level using option --log-level or -l to one of values trace, debug, info, warn, error, or none to suppress all logging.
By default, the info log level is used meaning that all log lines at level info, warn and error are shown while suppressing log lines at level debug or trace.
Rule configuration (.editorconfig)¶
Some rules can be tweaked via the editorconfig file.
A scaffold of the .editorconfig file can be generated with command below. Note: that the generated file only contains configuration settings which are actively used by the rules which are loaded:
# Specify the code style (ktlint_official, intellij_idea or android_studio) to be used when generating the .editorconfig
ktlint generateEditorConfig --code-style ktlint_official
# or
ktlint --ruleset=/path/to/custom-ruleset.jar generateEditorConfig --code-style android_studio
Normally the .editorconfig file is located in the root of your project directory. In case the file is located in a sub folder of the project, the settings of that file only applies to that subdirectory and its folders (recursively). Ktlint automatically detects and reads all .editorconfig files in your project.
Use command below, to specify a default editorconfig. In case a property is not defined in any .editorconfig file on the path to the file, the value from the default file is used. The path may point to any valid file or directory. The path can be relative or absolute. Depending on your OS, the "~" at the beginning of a path is replaced by the user home directory.
Overrides '.editorconfig' in project directory" in KtLint 0.46 and older
When specifying this option using ktlint 0.46 or older, all .editorconfig files in the project directory are being ignored. Starting from KtLint 0.47 the properties in this file are used as fallback.
Stdin && stdout¶
With command below, the input is read from stdin and the violations are printed to stderr. Logging is written to stdout.
When combined with the --format option, the formatted code is written to stdout and the violations are printed to stderr:
Suppress logging and error output
Logging output printed to stdout can be suppressed by setting --log-level=none (see logging).
Output printed to stderr can be suppressed in different ways. To ignore all error output, add 2> /dev/null to the end of the command line. Otherwise, specify a reporter to write the error output to a file.
If input from stdin represents the contents of a file, the file path can be supplied with stdin-path. This path is made available for rules to use, the --format option will not modify this file.
Git hooks¶
Predefined git hooks can be installed, to automatically validate lint errors before commit or push.
Exit codes¶
When integrating with Ktlint CLI with another tool it is important to take the exit codes below into account.
| Exit code | Description |
|---|---|
| 0 | The command has been executed succesfully. If the command included the option to format the code then no violations were found, or all violations have been autocorrected. |
| 1 | The input has been reformatted succesfully but at least one violation remains to be fixed. Usually this is a violation which cannot be autocorrected. After autocorrecting the error, rerun ktlint again. However, in some occasions it might happen that some violations remain that will be autocorrected in the next run. Note that Ktlint automatically reruns format a couple of times automatically. Inspect the logging output to verify that no cyclic behavior occurs where the fix of one rule is reverted by another rule in the next run as this might result in an endless loop. |
| 2 | An IO Exception has occurred. Check the logging output. |
| 3 | Input provided via stdin is not valid Kotlin (Script) code. Ensure that the input can be compiled before invoking Ktlint. |
| 4 | Input provided via stdin resulted in an exception. In case the |
| 5 | A command line option refers to an invalid path. See logging output. |
| 6 | The rule set jar provided is not supported. See logging output. |
| 7 | The reporter configuration is invalid. See logging output. |
| 123 | When using option --force-lint-after-format, a parse exception occurs when trying to lint the formatted output. This means that Ktlint changes resulted in a file which no longer can be compiled. This option is merely used for regression testing only. |
Miscellaneous flags and commands¶
--color and --color-name=<colorName>: Make output colorful and optionally set the color name to use.
-h or --help: Prints help information.
--limit=<limit>: Maximum number of errors to show (default: show all)
--relative: Print files relative to the working directory (e.g. dir/file.kt instead of /home/user/project/dir/file.kt)
--patterns-from-stdin[=<delimiter>]: Reads additional patterns from stdin, where the patterns are separated by <delimiter>. If =<delimiter> is omitted, newline is used as fallback delimiter. If an empty string is given, the NUL byte is used as delimiter instead.
If this option is given, then the default patterns are disabled.
Options --stdin and --patterns-from-stdin are mutually exclusive, only one of them can be given at a time.
-V or --version: Prints version information and exit.