Skip to content

Commit

Permalink
Improve documentation about prevent conflicts with Intellij IDEA form…
Browse files Browse the repository at this point in the history
…atting (#2642)

Closes #2639
  • Loading branch information
paul-dingemans authored Apr 23, 2024
1 parent fd083b6 commit dcec7ba
Show file tree
Hide file tree
Showing 4 changed files with 61 additions and 87 deletions.
Original file line number Diff line number Diff line change
@@ -1,36 +1,27 @@
!!! Warning
`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio. We recommend using either IDE formatting or `ktlint` formatting. However, if you persist on using both, then please ensure that the formatting settings are aligned as described below. This reduces the chance that code which is formatted by ktlint conflicts with formatting by the IntelliJ IDEA built-in formatter.

!!! Note
IntelliJ IDEA supports the [kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). As of version 0.47.x of ktlint, the support to overwrite some configuration files of IntelliJ IDEA has been dropped as it no longer fits the scope of the project.


Steps:

1. Go to your project directory
2. Create or replace file `.idea/codeStyles/codeStyleConfig.xml` with content below:
```xml
<component name="ProjectCodeStyleConfiguration">
<state>
<option name="USE_PER_PROJECT_SETTINGS" value="true" />
</state>
</component>
```
3. Create or replace file `.idea/codeStyles/Project.xml` with content below:
```xml
<component name="ProjectCodeStyleConfiguration">
<code_scheme name="Project" version="173">
<JetCodeStyleSettings>
<option name="PACKAGES_TO_USE_STAR_IMPORTS">
<value />
</option>
<option name="NAME_COUNT_TO_USE_STAR_IMPORT" value="2147483647" />
<option name="NAME_COUNT_TO_USE_STAR_IMPORT_FOR_MEMBERS" value="2147483647" />
<option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
</JetCodeStyleSettings>
<codeStyleSettings language="kotlin">
<option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
</codeStyleSettings>
</code_scheme>
</component>
```
# Intellij IDEA configuration

`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio as much as possible. In some cases, `ktlint` deliberately deviates from IDEA formatting.

## Preventing conflicts

Many conflicts can be prevented by setting following `.editorconfig` settings:
```
root = true
[*]
insert_final_newline = true
[{*.kt,*.kts}]
ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL
# Disable wildcard imports entirely
ij_kotlin_name_count_to_use_star_import = 2147483647
ij_kotlin_name_count_to_use_star_import_for_members = 2147483647
ij_kotlin_packages_to_use_import_on_demand = unset
```

Conflicts between `ktlint` and IDEA formatting can also be resolved by using the [ktlint-intellij-plugin](https://plugins.jetbrains.com/plugin/15057-ktlint) (or install via Intellij IDEA plugin marketplace) in `distract free` mode. In this mode, the plugin formats your code with `ktlint` while you're editing the code.

# Cleaning up old XML configuration settings

Projects which have been created with (old)er versions of Intellij IDEA might still contain XML configuration regarding code styling. It is advised to remove the directory `.idea/codeStyles` whenever it still exists in your project directory.
10 changes: 3 additions & 7 deletions documentation/release-latest/docs/rules/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -1282,15 +1282,11 @@ No wildcard imports except whitelisted imports.
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |
|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports as a comma separated list.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |

!!! warning
In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, it allows wildcards imports like `java.util.*` by default to keep in sync with IntelliJ IDEA behavior. To disallow *all* wildcard imports, add property below to your `.editorconfig`:
```editorconfig
[*.{kt,kts}]
ij_kotlin_packages_to_use_import_on_demand = unset
```
In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, Intellij IDEA allows wildcards imports like `java.util.*` which lead to conflicts with the `no-wildcard-imports` rule. See [Intellij IDEA configuration](configuration-intellij-idea.md) to prevent such conflicts.

Configuration setting `ij_kotlin_packages_to_use_import_on_demand` is a comma separated string of import paths. This can be a full path, e.g. "java.util.List.*", or a wildcard path, e.g. "kotlin.**". Use "**" as wildcard for package and all subpackages.

Expand Down
63 changes: 27 additions & 36 deletions documentation/snapshot/docs/rules/configuration-intellij-idea.md
Original file line number Diff line number Diff line change
@@ -1,36 +1,27 @@
!!! Warning
`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio. We recommend using either IDE formatting or `ktlint` formatting. However, if you persist on using both, then please ensure that the formatting settings are aligned as described below. This reduces the chance that code which is formatted by ktlint conflicts with formatting by the IntelliJ IDEA built-in formatter.

!!! Note
IntelliJ IDEA supports the [kotlin coding conventions](https://kotlinlang.org/docs/coding-conventions.html). As of version 0.47.x of ktlint, the support to overwrite some configuration files of IntelliJ IDEA has been dropped as it no longer fits the scope of the project.


Steps:

1. Go to your project directory
2. Create or replace file `.idea/codeStyles/codeStyleConfig.xml` with content below:
```xml
<component name="ProjectCodeStyleConfiguration">
<state>
<option name="USE_PER_PROJECT_SETTINGS" value="true" />
</state>
</component>
```
3. Create or replace file `.idea/codeStyles/Project.xml` with content below:
```xml
<component name="ProjectCodeStyleConfiguration">
<code_scheme name="Project" version="173">
<JetCodeStyleSettings>
<option name="PACKAGES_TO_USE_STAR_IMPORTS">
<value />
</option>
<option name="NAME_COUNT_TO_USE_STAR_IMPORT" value="2147483647" />
<option name="NAME_COUNT_TO_USE_STAR_IMPORT_FOR_MEMBERS" value="2147483647" />
<option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
</JetCodeStyleSettings>
<codeStyleSettings language="kotlin">
<option name="CODE_STYLE_DEFAULTS" value="KOTLIN_OFFICIAL" />
</codeStyleSettings>
</code_scheme>
</component>
```
# Intellij IDEA configuration

`ktlint` strives to prevent code formatting conflicts with IntelliJ IDEA / Android Studio as much as possible. In some cases, `ktlint` deliberately deviates from IDEA formatting.

## Preventing conflicts

Many conflicts can be prevented by setting following `.editorconfig` settings:
```
root = true
[*]
insert_final_newline = true
[{*.kt,*.kts}]
ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL
# Disable wildcard imports entirely
ij_kotlin_name_count_to_use_star_import = 2147483647
ij_kotlin_name_count_to_use_star_import_for_members = 2147483647
ij_kotlin_packages_to_use_import_on_demand = unset
```

Conflicts between `ktlint` and IDEA formatting can also be resolved by using the [ktlint-intellij-plugin](https://plugins.jetbrains.com/plugin/15057-ktlint) (or install via Intellij IDEA plugin marketplace) in `distract free` mode. In this mode, the plugin formats your code with `ktlint` while you're editing the code.

# Cleaning up old XML configuration settings

Projects which have been created with (old)er versions of Intellij IDEA might still contain XML configuration regarding code styling. It is advised to remove the directory `.idea/codeStyles` whenever it still exists in your project directory.
12 changes: 4 additions & 8 deletions documentation/snapshot/docs/rules/standard.md
Original file line number Diff line number Diff line change
Expand Up @@ -1281,16 +1281,12 @@ No wildcard imports except whitelisted imports.
import foobar.*
```

| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |
| Configuration setting | ktlint_official | intellij_idea | android_studio |
|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:------------------------------------------:|:-----------------------------------------------:|
| `ij_kotlin_packages_to_use_import_on_demand`<br/><i>Defines allowed wildcard imports as a comma separated list.</i> | - | `java.util.*,`<br/>`kotlinx.android.synthetic.**` | `java.util.*,`<br/>`kotlinx.android.synthetic.**` |

!!! warning
In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, it allows wildcards imports like `java.util.*` by default to keep in sync with IntelliJ IDEA behavior. To disallow *all* wildcard imports, add property below to your `.editorconfig`:
```editorconfig
[*.{kt,kts}]
ij_kotlin_packages_to_use_import_on_demand = unset
```
In case property `ij_kotlin_packages_to_use_import_on_demand` is not explicitly set, Intellij IDEA allows wildcards imports like `java.util.*` which lead to conflicts with the `no-wildcard-imports` rule. See [Intellij IDEA configuration](configuration-intellij-idea.md) to prevent such conflicts.

Configuration setting `ij_kotlin_packages_to_use_import_on_demand` is a comma separated string of import paths. This can be a full path, e.g. "java.util.List.*", or a wildcard path, e.g. "kotlin.**". Use "**" as wildcard for package and all subpackages.

Expand Down

0 comments on commit dcec7ba

Please sign in to comment.