Command line
Note
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.
Download using curl¶
A particular version of ktlint
can be downloaded with next command which also changes the file to an executable in directory /usr/local/bin
:
curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.50.0/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/
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:
Verification of download¶
ktlint.asc
contains PGP signature which you can verify with:
curl -sS https://keybase.io/ktlint/pgp_keys.asc | 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
Install with SDKMAN! on macOS and Linux
On Arch Linux install package ktlint AUR.
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 (non-experimental) rules from the standard ruleset. Hidden folders will be skipped.
To validate with the standard ruleset including the experimental rules run command below:
Note
Instead of using this command line flag, it is advised to set .editorconfig
property ktlint_experimental = enabled
if you want the project always to be checked with the experimental rules.
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 (or command line parameter --experimental
is specified).
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:
ktlint generateEditorConfig
# or
ktlint --experimental generateEditorConfig
# or
ktlint --experimental --ruleset=/path/to/custom-ruleset.jar generateEditorConfig
Normally this 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.
!!! warning "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
:
Tip
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.
Git hooks¶
Predefined git hooks can be installed, to automatically validate lint errors before commit or push.
Miscellaneous flags and commands¶
-a
or --android
: Turn on Android Kotlin Style Guide compatibility. This flag is most likely to be removed in a future version. Use .editorconfig ktlint_code_style
.
--color
and --color-name=<colorName>
: Make output colorful and optionally set the color name to use.
--disabled_rules=<disabledRules>
: A comma-separated list of rules to globally disable. To disable the standard ktlint rule-set use --disabled_rules=standard
. This flag is most likely to be removed in a future version. Use .editorconfig disabled_rules
.
-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.
Microsoft Windows users¶
Microsoft Windows is not able to run the ktlint
command directly. Ktlint can be run in following ways on Microsoft Windows:
- 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 as
java -jar ktlint