-
+
Kotlin linter in spirit of feross/standard (JavaScript) and gofmt (Go).
-## Features -- **No configuration.**[*](https://github.com/pinterest/ktlint#how-do-i-globally-disable-a-rule) Which means no decisions to make, nothing to argue about and no special files to manage. -While this might sound extreme, keep in mind that `ktlint` tries to capture (reflect) **official code style**[*](https://github.com/pinterest/ktlint/issues/284#issuecomment-425177186) from [kotlinlang.org](https://kotlinlang.org/docs/reference/coding-conventions.html) and [Android Kotlin Style Guide](https://android.github.io/kotlin-guides/style.html) -(+ [we respect your .editorconfig](#editorconfig) and support additional [ruleset](#creating-a-ruleset)|s). -- **Built-in formatter.** So that you wouldn't have to fix all style violations by hand. -- **Customizable output.** `plain` (+ `plain?group_by_file`), `format`, `json`, `html` and `checkstyle` reporters are available out-of-the-box. -It's also [easy to create your own](#creating-a-reporter). -- **A single executable jar with all dependencies included.** +## Key features --Installation | Usage | Integration with Maven / Gradle / IntelliJ IDEA / Emacs / Continuous Integration | Creating a ruleset | a reporter | Badge | FAQ -
- -## Standard rules - -- `annotation`: Annotation formatting - multiple annotations should be on a separate line than the annotated declaration; annotations with parameters should each be on separate lines; annotations should be followed by a space -- `argument-list-wrapping`: Argument list wrapping -- `chain-wrapping`: When wrapping chained calls `.`, `?.` and `?:` should be placed on the next line -- `comment-spacing`: The end of line comment sign `//` should be preceded and followed by exactly a space -- `enum-entry-name-case`: Enum entry names should be uppercase underscore-separated names -- `filename`: Files containing only one toplevel domain should be named according to that element. -- `final-newline`: Newline at the end of each file (enabled by default) - (set `insert_final_newline=false` in .editorconfig to disable (see [EditorConfig](#editorconfig) section for more)). -- `import-ordering`: Imports ordered consistently (see [Custom ktlint EditorConfig properties](#custom-ktlint-specific-editorconfig-properties) for more) -- `indent`: Indentation formatting - respects `.editorconfig` `indent_size` with no continuation indent (see [EditorConfig](#editorconfig) section for more) -- `max-line-length`: Ensures that lines do not exceed the given length of `.editorconfig` property `max_line_length` (see [EditorConfig](#editorconfig) section for more). This rule does not apply in a number of situations. For example, in the case a line exceeds the maximum line length due to and comment that disables ktlint rules than that comment is being ignored when validating the length of the line. The `.editorconfig` property `ktlint_ignore_back_ticked_identifier` can be set to ignore identifiers which are enclosed in backticks, which for example is very useful when you want to allow longer names for unit tests. -- `modifier-order`: Consistent order of modifiers -- `multiline-if-else`: Braces required for multiline if/else statements -- `no-blank-line-before-rbrace`: No blank lines before `}` -- `no-blank-lines-in-chained-method-calls`: No blank lines in chained method expressions -- `no-consecutive-blank-lines`: No consecutive blank lines -- `no-empty-class-body`: No empty (`{}`) class bodies -- `no-empty-first-line-in-method-block`: No leading empty lines in method blocks -- `no-line-break-after-else`: Disallows line breaks after the else keyword if that could lead to confusion, for example: - ```kotlin - if (conditionA()) { - doSomething() - } else - if (conditionB()) { - doAnotherThing() - } - ``` -- `no-line-break-before-assignment`: When a line is broken at an assignment (`=`) operator the break comes after the symbol -- `no-multi-spaces`: Except in indentation and in KDoc's it is not allowed to have multiple consecutive spaces -- `no-semi`: No semicolons (unless used to separate multiple statements on the same line) -- `no-trailing-spaces`: No trailing whitespaces -- `no-unit-return`: No `Unit` returns (`fun fn {}` instead of `fun fn: Unit {}`) -- `no-unused-imports`: No unused `import`s -- `no-wildcard-imports`: No wildcard `import`s expect imports listed in `.editorconfig` property `ij_kotlin_packages_to_use_import_on_demand` -- `package-name`: No underscores in package names -- `parameter-list-wrapping`: When class/function signature doesn't fit on a single line, each parameter must be on a separate line -- `string-template`: Consistent string templates (`$v` instead of `${v}`, `${p.v}` instead of `${p.v.toString()}`) -- `trailing-comma-on-call-site`: Consistent removal (default) or adding of trailing comma's (on call site) -- `trailing-comma-on-declaration-site`: Consistent removal (default) or adding of trailing comma's (on declaration site) - -### Spacing -- `annotation-spacing`: Annotations should be separated by a single line break -- `colon-spacing`: Consistent spacing around colon -- `comma-spacing`: Consistent spacing around comma -- `curly-spacing`: Consistent spacing around curly braces -- `dot-spacing`: Consistent spacing around dots -- `double-colon-spacing`: No spaces around `::` -- `keyword-spacing`: Consistent spacing around keywords -- `op-spacing`: Consistent spacing around operators -- `paren-spacing`: Consistent spacing around parenthesis -- `range-spacing`: Consistent spacing around range operators -- `spacing-around-angle-brackets`: No spaces around angle brackets -- `spacing-between-declarations-with-annotations`: Declarations with annotations should be separated by a blank line -- `spacing-between-declarations-with-comments`: Declarations with comments should be separated by a blank line -- `unary-op-spacing`: No spaces around unary operators - -## Experimental rules -New rules will be added into the [experimental ruleset](https://github.com/pinterest/ktlint/tree/master/ktlint-ruleset-experimental), which can be enabled -by passing the `--experimental` flag to `ktlint`. - -- `experimental:block-comment-initial-star-alignment`: Lines in a block comment which (exclusive the indentation) start with a `*` should have this `*` aligned with the `*` in the opening of the block comment. -- `experimental:discouraged-comment-location`: Detect discouraged comment locations (no autocorrect) -- `experimental:unnecessary-parentheses-before-trailing-lambda`: An empty parentheses block before a lambda is redundant. For example `some-string".count() { it == '-' }` -- `function-signature`: rewrites the function signature to a single line when possible (e.g. when not exceeding the `max_line_length` property) or a multiline signature otherwise. In case of function with a body expression, the body expression is placed on the same line as the function signature when not exceeding the `max_line_length` property. Optionally the function signature can be forced to be written as a multiline signature in case the function has more than a specified number of parameters (`.editorconfig' property `ktlint_function_signature_wrapping_rule_always_with_minimum_parameters`) - -### Spacing -- `experimental:fun-keyword-spacing`: Consistent spacing after the fun keyword -- `experimental:function-return-type-spacing`: Consistent spacing around the function return type -- `experimental:function-start-of-body-spacing`: Consistent spacing before start of function body -- `experimental:function-type-reference-spacing`: Consistent spacing in the type reference before a function -- `experimental:modifier-list-spacing`: Consistent spacing between modifiers in and after the last modifier in a modifier list -- `experimental:nullable-type-spacing`: No spaces in a nullable type -- `experimental:parameter-list-spacing`: Consistent spacing inside the parameter list -- `experimental:spacing-between-function-name-and-opening-parenthesis`: Consistent spacing between function name and opening parenthesis -- `experimental:type-parameter-list-spacing`: Spacing after a type parameter list in function and class declarations - -### Wrapping -- `experimental:comment-wrapping`: A block comment should start and end on a line that does not contain any other element. A block comment should not be used as end of line comment. -- `experimental:kdoc-wrapping`: A KDoc comment should start and end on a line that does not contain any other element. - -## EditorConfig - -Ktlint uses a limited set of `.editorconfig` properties for additional configuration. A sensible default value is provided for each property when not explicitly defined. Properties can be overridden, provided they are specified under `[*.{kt,kts}]`. Ktlint uses some properties defined by [.editorconfig](https://editorconfig.org/), IntelliJ IDEA and custom properties. - -### Disable rules - -By default, no rules are disabled. The property `disabled_rules` holds a comma separated list (without spaces). Rules which are not defined in the `standard` ruleset have to be prefixed. - -Example: -```ini -[*.{kt,kts}] -disabled_rules = some-standard-rule,experimental:some-experimental-rule,my-custom-ruleset:my-custom-rule -``` - -### Trailing comma - -Trailing comma's (both on call and declaration site) are disabled (e.g. not allowed) by. When enabling the properties, the trailing becomes mandatory where applicable. - -Example: -```ini -[*.{kt,kts}] -ij_kotlin_allow_trailing_comma = false -ij_kotlin_allow_trailing_comma_on_call_site = false -``` - -### Import layouts - -By default, the same imports are allowed as in IntelliJ IDEA. The import path can be a full path, e.g. "java.util.List.*" as well as wildcard path, e.g. "kotlin.**". - -The layout can be composed by the following symbols: -* "*" - wildcard. There must be at least one entry of a single wildcard to match all other imports. Matches anything after a specified symbol/import as well. -* "|" - blank line. Supports only single blank lines between imports. No blank line is allowed in the beginning or end of the layout. -* "^" - alias import, e.g. "^android.*" will match all android alias imports, "^" will match all other alias imports. - -Examples: -```kotlin -ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines -ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list -ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout -``` - -Wildcard imports can be allowed for specific import paths (Comma-separated list, use "**" as wildcard for package and all subpackages). This setting overrides the no-wildcard-imports rule. This setting is best be used for allowing wildcard imports from libraries like Ktor where extension functions are used in a way that creates a lot of imports. - -```ini -[*.{kt,kts}] -ij_kotlin_packages_to_use_import_on_demand = java.util.*,kotlinx.android.synthetic.** -``` - -### Indent - -By default, indenting is done with 4 spaces per indent level. - -```ini -[*.{kt,kts}] -indent_size = 4 # possible values: number (e.g. 2), "unset" (makes ktlint ignore indentation completely) -indent_style = space # or "tab" -``` - -### Final newline - -By default, a final newline is required at the end of the file. - -```ini -[*.{kt,kts}] -insert_final_newline = true -``` - -### Code style - -By default, the `offical` Kotlin code style is applied. Alternatively, the code style can be set to `android`. Note that for the Android code style different default values might be applicable. - -```ini -[*.{kt,kts}] -ktlint_code_style = official # Or "android" -``` - -### Function signature - -By default, the number of parameters in a function signature is not relevant when rewriting the function signature. Only the maximum line length determines when a function signature should be written on a single line or with multiple lines. This setting can be used, to force a multiline function signature in case the function contain at least a number of parameters even in case the function signature would fit on a single line. - -```ini -[*.{kt,kts}] -ktlint_function_signature_rule_force_multiline_with_at_least_parameters= -1 # -1 to ignore the number of parameters or otherwise a positive number -``` - -### Ignore identifiers enclosed in backticks - -By default, the identifiers enclosed in backticks are not ignored. - -According to https://kotlinlang.org/docs/reference/coding-conventions.html#names-for-test-methods it is acceptable to write method names in natural language. When using natural language, the description tends to be longer. This property allows lines containing an identifier between backticks to be longer than the maximum line length. (Since 0.41.0) - -```kotlin -@Test -fun `Given a test with a very loooooooooooooooooooooong test description`() { - -} -``` - -```ini -[*.{kt,kts}] -ktlint_ignore_back_ticked_identifier = false -``` - -### Max line length - -By default, the maximum line length is not set. The `android` code style sets the max line length to 100 (per Android Kotlin Style Guide). - -```ini -[*.{kt,kts}] -max_line_length = -1 # Use "off" (or -1) to ignore max line length or a positive number to set max line length -``` - -### IntelliJ IDEA `.editorconfig` autoformat issue - -Unfortunately [IntelliJ IDEA](https://www.jetbrains.com/idea/) has `.editorconfig` [autoformat issue](https://youtrack.jetbrains.com/issue/IDEA-242506) -that adds additional space into glob statements. -For example, `[*{kt,kts}]` is formatted into `[*{kt, kts}]` ([original ktlint issue](https://github.com/pinterest/ktlint/issues/762)). -Such behaviour violates `.editorconfig` [specification](https://github.com/editorconfig/editorconfig/issues/148) and leads to ignoring this section when ktlint is parsing it. - -### Overriding Editorconfig properties for specific directories - -You could [override](https://editorconfig.org/#file-format-details) properties for specific directories inside your project: -```ini -[*.{kt,kts}] -disabled_rules=import-ordering - -# Note that in this case 'import-ordering' rule will be active and 'indent' will be disabled -[api/*.{kt,kts}] -disabled_rules=indent -``` - -## Online demo -You can try `ktlint` online [here](https://ktlint-demo.herokuapp.com/) using the standard or a custom ruleset without installing it to your PC. \ -To contribute or get more info, please visit the [GitHub repository](https://github.com/akuleshov7/diKTat-demo). - - -## Installation - -> Skip all the way to the "Integration" section if you don't plan to use `ktlint`'s command line interface. - -```sh -curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.46.1/ktlint && - chmod a+x ktlint && - sudo mv ktlint /usr/local/bin/ -``` - -... or just download `ktlint` from the [releases](https://github.com/pinterest/ktlint/releases) page - -* `ktlint.asc` contains PGP signature which you can verify with: - * (Releases up through 0.31.0) `curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc` - * (Releases from 0.32.0 on) `curl -sS https://keybase.io/ktlint/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc` - -On macOS ([or Linux](https://docs.brew.sh/Homebrew-on-Linux)) you can also use [brew](https://brew.sh/) - `brew install ktlint` - or [MacPorts](https://www.macports.org/) - `port install ktlint`. -On Arch Linux, you can install [ktlint](https://aur.archlinux.org/packages/ktlint/) AUR. - -> If you don't have curl installed - replace `curl -sL` with `wget -qO-`. - -> If you are behind a proxy see - -[curl](https://curl.haxx.se/docs/manpage.html#ENVIRONMENT) / -[wget](https://www.gnu.org/software/wget/manual/wget.html#Proxies) manpage. -Usually simple `http_proxy=http://proxy-server:port https_proxy=http://proxy-server:port curl -sL ...` is enough. - -## Command line usage - -```bash -# Get help about all available commands -$ ktlint --help - -# Check the style of all Kotlin files (ending with '.kt' or '.kts') inside the current dir (recursively). -# Hidden folders will be skipped. -$ ktlint - -# Check only certain locations starting from the current directory. -# -# Prepend ! to negate the pattern, KtLint uses .gitignore pattern style syntax. -# Globs are applied starting from the last one. -# -# 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/**" - -# Auto-correct style violations. -# If some errors cannot be fixed automatically they will be printed to stderr. -$ ktlint -F "src/**/*.kt" - -# Print style violations grouped by file. -$ ktlint --reporter=plain?group_by_file - -# Print style violations as usual + create report in checkstyle format, specifying report location. -$ ktlint --reporter=plain --reporter=checkstyle,output=ktlint-report-in-checkstyle-format.xml - -# Check against a baseline file. -$ ktlint --baseline=ktlint-baseline.xml - -# Install git hook to automatically check files for style violations on commit. -# Run "ktlint installGitPrePushHook" if you wish to run ktlint on push instead. -$ ktlint installGitPreCommitHook -``` - -> on Windows you'll have to use `java -jar ktlint ...`. - -`ktlint --help` for more. - -### Integration - -#### ... with [Maven](https://github.com/shyiko/mvnw) - -> pom.xml - -```xml -... -
-
+
Kotlin linter in spirit of feross/standard (JavaScript) and gofmt (Go).
diff --git a/docs/install/cli.md b/docs/install/cli.md
index cae9b9515f..249ef3a5a2 100644
--- a/docs/install/cli.md
+++ b/docs/install/cli.md
@@ -52,18 +52,40 @@ On Arch Linux install package [ktlint AUR](https://aur.archlinux.org/
## Command line usage
-A good starting point is to read the help page:
+### Rule set(s)
-```shell title="Get help about all available commands"
-ktlint --help
-```
-
-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](https://ktlint.github.io/rules/standard/). Hidden folders will be skipped.
+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](https://pinterest.github.io/ktlint/rules/standard/). Hidden folders will be skipped.
```shell title="Default validation with standard ruleset"
ktlint
```
+To validate with the [standard ruleset](https://pinterest.github.io/ktlint/rules/standard/) and the [experimental rulesset](https://pinterest.github.io/ktlint/rules/experimental/) run command below:
+
+```shell title="Validation with standard and experimental ruleset"
+ktlint --experimental
+```
+
+To validate with a [custom ruleset](https://pinterest.github.io/ktlint/extensions/custom-rule-set/) run command below:
+
+```shell title="Validation with standard and a custom ruleset"
+ktlint --ruleset=/path/to/custom-ruleset.jar
+# or
+ktlint -R /path/to/custom-ruleset.jar
+```
+
+### Format (autocorrect)
+
+Most style violations can be corrected automatically. Errors that can not be corrected, are printed to `stderr`.
+
+```shell title="Autocorrect style violations"
+ktlint --format
+# or
+ktlint -F
+```
+
+### 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](https://git-scm.com/docs/gitignore). Globs are processed from left to right. Prepend a glob with `!` to negate it. Hidden folders will be skipped.
```shell title="Check only certain locations starting from the current directory"
@@ -74,11 +96,7 @@ ktlint "src/**/*.kt" "!src/**/*Test.kt"
ktlint "src/**/*.kt" "!src/**/generated/**"
```
-Most style violations can be corrected automatically. Errors that can not be corrected, are printed to `stderr`.
-
-```shell title="Auto-correct style violations"
-$ ktlint -F
-```
+### Error reporting
`ktlint` supports different type of reporters. When not specified the `plain` reporter is used. Optionally the `plain` reporter can group the violations per file.
@@ -86,6 +104,8 @@ $ ktlint -F
$ ktlint --reporter=plain?group_by_file
```
+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:
```shell title="Multiple reporters"
@@ -98,6 +118,51 @@ If resolving all existing errors in a project is unwanted, it is possible to cre
ktlint --baseline=ktlint-baseline.xml # Baseline is created when not existing
```
+### Rule configuration (`.editorconfig`)
+
+Some rules can be tweaked via the [`editorconfig file`](https://pinterest.github.io/ktlint/rules/configuration/).
+
+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](#rule-sets):
+
+```shell title="Generate .editorconfig"
+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.
+
+With command below, an `editorconfig` file of an alternative location can be used to configure ktlint:
+
+```shell title="Override '.editorconfig'"
+ktlint --editorconfig=/path/to/.editorconfig
+```
+
+!!! warning "Overrides '.editorconfig' in project directory"
+ When specifying this option, all `.editorconfig` files in the project directory are being ignored.
+
+### Stdin && stdout
+
+With command below, the input is read from `stdin` and the violations are printed to `stderr`.
+
+```shell title="Lint from stdin"
+ktlint --stdin
+```
+
+When combined with the `--format` option, the formatted code is written to `stdout` and the violations are printed to `stderr`:
+
+```shell title="Format from stdin and write to stdout"
+ktlint --stdin -F
+```
+
+!!! tip Suppress error output
+ 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](#error-reporting) 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.
```shell title="Install git pre-commit hook"
@@ -108,5 +173,31 @@ ktlint installGitPreCommitHook
ktlint installGitPrePushHook
```
+### 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`(https://pinterest.github.io/ktlint/rules/configuration/#code-style).
+
+`applyToIDEA` or `--apply-to-idea`: Update Intellij IDEA Kotlin codestyle settings (global)
+
+`applyToIDEAProject` or `--apply-to-idea-project`: Update Intellij IDEA project settings
+
+`--color` and `--color-name=