Enum: Auto | Manual

Auto

A blank line is automatically inserted between adjacent import groups. All blank line markers (---) configured in the groups option are ignored.

Manual

A blank line is inserted at all the positions where blank line markers appear in the groups option.

The following two configurations are equivalent:

Auto

Auto

Configuration:

OrganizeImports {
  blankLines = Auto
  groups = [
    "re:javax?\\."
    "scala."
    "*"
  ]
}

Before:

import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext

After:

import java.time.Clock
import javax.annotation.Generated

import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext

import sun.misc.BASE64Encoder

Manual

Configuration:

OrganizeImports {
  blankLines = Manual
  groups = [
    "re:javax?\\."
    "scala."
    "---"
    "*"
  ]
}

Before:

import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext

After:

import java.time.Clock
import javax.annotation.Generated
import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext

import sun.misc.BASE64Encoder

Integer. Not setting it or setting it to null disables this feature.

null

Configuration:

Before:

After:

Boolean

false

Configuration:

Before:

After:

error: could not find implicit value for parameter i: Int
  def main() = f()
                ^

Boolean

false

Rationale

This option defaults to false due to the following reasons:

1. Although setting it to true avoids the aforementioned correctness issue, the result is unintuitive and confusing for many users since it looks like the groups option is not respected.

   E.g., why my scala.concurrent.ExecutionContext.Implicits.global import is moved to a separate group even if I have a scala. group defined in the groups option?

2. The concerned correctness issue is rarely seen in real life. When it really happens, it is usually a sign of bad coding style, and you may want to tweak your imports to eliminate the root cause.

Configuration:

Before:

After:

Enum: Explode | Merge | AggressiveMerge | Keep

Explode

Explode grouped imports into separate import statements.

Merge

Merge imports sharing the same prefix into a single grouped import statement.

💡	You may want to check the AggressiveMerge option for more concise results despite a relatively low risk of introducing compilation errors.

❗

OrganizeImports does not support cases where one name is renamed to multiple aliases within the same source file when groupedImports is set to Merge. (The IntelliJ IDEA Scala import optimizer does not support this either.) Scala allows a name to be renamed to multiple aliases within a single source file, which makes merging import statements tricky. For example: import java.lang.{Double => JDouble} import java.lang.{Double => JavaDouble} import java.lang.Integer The above three imports can be merged into: import java.lang.{Double => JDouble} import java.lang.{Double => JavaDouble, Integer} but not: import java.lang.{Double => JDouble, Double => JavaDouble, Integer} because Scala disallow a name (in this case, Double) to appear in one import multiple times. Here’s a more complicated example: import p.{A => A1} import p.{A => A2} import p.{A => A3} import p.{B => B1} import p.{B => B2} import p.{C => C1} import p.{C => C2} import p.{C => C3} import p.{C => C4} While merging these imports, we may want to "bin-pack" them to minimize the number of the result import statements: import p.{A => A1, B => B1, C => C1} import p.{A => A2, B => B2, C => C2} import p.{A => A3, C3 => C3} import p.{C => C4} However, in reality, renaming aliasing a name multiple times in the same source file is rarely a practical need. Therefore, OrganizeImports does not support this when groupedImports is set to Merge to avoid the extra complexity.

AggressiveMerge

Similar to Merge, but merges imports more aggressively and produces more concise results, despite a relatively low risk of introducing compilation errors.

The OrganizeImports rule tries hard to guarantee correctness in all cases. This forces it to be more conservative when merging imports, and may sometimes produce suboptimal output. Here is a concrete example about correctness:

import scala.collection.immutable._
import scala.collection.mutable.Map
import scala.collection.mutable._

object Example {
  val m: Map[Int, Int] = ???
}

At a first glance, it seems feasible to simply drop the second import since mutable._ already covers mutble.Map. However, similar to the example illustrated in the section about the coalesceToWildcardImportThreshold option, the type of Example.m above is mutable.Map, because the mutable Map explicitly imported in the second import takes higher precedence than the immutable Map imported via wildcard in the first import. If we merge the last two imports naively, we’ll get:

import scala.collection.immutable._
import scala.collection.mutable._

This triggers in a compilation error, because both immutable.Map and mutable.Map are now imported via wildcards with the same precedence. This makes the type of Example.m ambiguous. The correct result should be:

import scala.collection.immutable._
import scala.collection.mutable.{Map, _}

On the other hand, the case discussed above is rarely seen in practice. A more commonly seen case is something like:

import scala.collection.mutable.Map
import scala.collection.mutable._

Instead of being conservative and produce a suboptimal output like:

import scala.collection.mutable.{Map, _}

setting groupedImports to AggressiveMerge produces

import scala.collection.mutable._

Keep

Leave grouped imports and imports sharing the same prefix untouched.

Explode

Rationale

Despite making the import section lengthier, exploding grouped imports into separate import statements is made the default behavior because it is more friendly to version control and less likely to create annoying merge conflicts caused by trivial import changes.

Explode

Configuration:

OrganizeImports.groupedImports = Explode

Before:

import scala.collection.mutable.{ArrayBuffer, Buffer, StringBuilder}

After:

import scala.collection.mutable.ArrayBuffer
import scala.collection.mutable.Buffer
import scala.collection.mutable.StringBuilder

Merge

Configuration:

OrganizeImports.groupedImports = Merge

Before:

import scala.collection.mutable.ArrayBuffer
import scala.collection.mutable.Buffer
import scala.collection.mutable.StringBuilder
import scala.collection.immutable.Set
import scala.collection.immutable._

After:

import scala.collection.mutable.{ArrayBuffer, Buffer, StringBuilder}
import scala.collection.immutable.{Set, _}

AggressiveMerge

Configuration:

OrganizeImports.groupedImports = AggressiveMerge

Before:

import scala.collection.mutable.ArrayBuffer
import scala.collection.mutable.Buffer
import scala.collection.mutable.StringBuilder
import scala.collection.immutable.Set
import scala.collection.immutable._

After:

import scala.collection.mutable.{ArrayBuffer, Buffer, StringBuilder}
import scala.collection.immutable._

An ordered list of import prefix pattern strings. A prefix pattern can be one of the following:

A plain-text pattern

For instance, "scala." is a plain-text pattern that matches imports referring the scala package. Please note that the trailing dot is necessary, otherwise you may have scalafix and scala imports in the same group, which is not what you want in most cases.

A regular expression pattern

A regular expression pattern starts with re:. For instance, "re:javax?\\." is such a pattern that matches both the java and the javax packages. Please refer to the java.util.regex.Pattern Javadoc page for the regular expression syntax. Note that special characters like backslashes must be escaped.

The wildcard pattern

The wildcard pattern, "*", defines the wildcard group, which matches all fully-qualified imports not belonging to any other groups. It can be omitted when it’s the last group. So the following two configurations are equivalent:

OrganizeImports.groups = ["re:javax?\\.", "scala.", "*"]
OrganizeImports.groups = ["re:javax?\\.", "scala."]

A blank line marker

Available since v0.5.0-alpha.1.

A blank line marker, "---", defines a blank line between two adjacent import groups when blankLines is set to Manual. It is ignored when blankLines is Auto. Leading and trailing blank line markers are always ignored. Multiple consecutive blank line markers are treated as a single one. So the following three configurations are all equivalent:

OrganizeImports {
  blankLines = Manual
  groups = [
    "---"
    "re:javax?\\."
    "---"
    "scala."
    "---"
    "---"
    "*"
    "---"
  ]
}

OrganizeImports {
  blankLines = Manual
  groups = [
    "re:javax?\\."
    "---"
    "scala."
    "---"
    "*"
  ]
}

OrganizeImports {
  blankLines = Auto
  groups = [
    "re:javax?\\."
    "scala."
    "*"
  ]
}

Rationale

This aligns with the default configuration of the IntelliJ Scala plugin version 2020.3.

Fully-qualified imports only

Configuration:

OrganizeImports.groups = ["re:javax?\\.", "scala.", "*"]

Before:

import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext

After:

import java.time.Clock
import javax.annotation.Generated

import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext

import sun.misc.BASE64Encoder

With relative imports

Configuration:

OrganizeImports.groups = ["re:javax?\\.", "scala.", "*"]

Before:

import scala.util
import util.control
import control.NonFatal
import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext

After:

import java.time.Clock
import javax.annotation.Generated

import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext
import scala.util

import sun.misc.BASE64Encoder

import util.control
import control.NonFatal

With relative imports and an explicitly imported implicit name

Configuration:

OrganizeImports {
  groups = ["re:javax?\\.", "scala.", "*"]
  groupExplicitlyImportedImplicitsSeparately = true
}

Before:

import scala.util
import util.control
import control.NonFatal
import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext.Implicits.global

After:

import java.time.Clock
import javax.annotation.Generated

import scala.collection.JavaConverters._
import scala.util

import sun.misc.BASE64Encoder

import util.control
import control.NonFatal
import scala.concurrent.ExecutionContext.Implicits.global

Regular expression

Defining import groups using regular expressions can be quite flexible. For instance, the scala.meta package is not part of the Scala standard library, but the default groups defined in the OrganizeImports.groups option move imports from this package into the scala. group. The following example illustrates how to move them into the wildcard group using regular expression.

Configuration:

OrganizeImports.groups = [
  "re:javax?\\."
  "re:scala.(?!meta\\.)"
  "*"
]

Before:

import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import scala.meta.Tree
import javax.annotation.Generated
import scala.concurrent.ExecutionContext
import scala.meta.Import
import scala.meta.Pkg

After:

import java.time.Clock
import javax.annotation.Generated

import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext

import scala.meta.Import
import scala.meta.Pkg
import scala.meta.Tree
import sun.misc.BASE64Encoder

With manually configured blank lines

Configuration:

OrganizeImports {
  blankLines = Manual
  groups = [
    "*"
    "---"
    "re:javax?\\."
    "scala."
  ]
}

Before:

import scala.collection.JavaConverters._
import java.time.Clock
import sun.misc.BASE64Encoder
import javax.annotation.Generated
import scala.concurrent.ExecutionContext

After:

import sun.misc.BASE64Encoder

import java.time.Clock
import javax.annotation.Generated
import scala.collection.JavaConverters._
import scala.concurrent.ExecutionContext

Enum: Ascii | SymbolsFirst | Keep

Ascii

Sort import selectors by ASCII codes, equivalent to the AsciiSortImports rewriting rule in Scalafmt.

SymbolsFirst

Sort import selectors by the groups: symbols, lower-case, upper-case, equivalent to the SortImports rewriting rule in Scalafmt.

Keep

Keep the original order.

Ascii

Ascii

Configuration:

OrganizeImports {
  groupedImports = Keep
  importSelectorsOrder = Ascii
}

Before:

import foo.{~>, `symbol`, bar, Random}

After:

import foo.{Random, `symbol`, bar, ~>}

SymbolsFirst

Configuration:

OrganizeImports {
  groupedImports = Keep
  importSelectorsOrder = SymbolsFirst
}

Before:

import foo.{Random, `symbol`, bar, ~>}

After:

import foo.{~>, `symbol`, bar, Random}

Enum: Ascii | SymbolsFirst | Keep

Ascii

Sort import statements by ASCII codes. This is the default sorting order that the IntelliJ IDEA Scala import optimizer picks ("lexicographically" option).

SymbolsFirst

Put wildcard imports and grouped imports with braces first, otherwise same as Ascii. This replicates IntelliJ IDEA Scala’s "scalastyle consistent" option.

Keep

Keep the original order.

Ascii

Ascii

Configuration:

OrganizeImports {
  groupedImports = Keep
  importsOrder = Ascii
}

Before:

import scala.concurrent._
import scala.concurrent.{Future, Promise}
import scala.concurrent.ExecutionContext.Implicits._
import scala.concurrent.duration

After:

import scala.concurrent.ExecutionContext.Implicits._
import scala.concurrent._
import scala.concurrent.duration
import scala.concurrent.{Promise, Future}

SymbolsFirst

Configuration:

OrganizeImports {
  groupedImports = Keep
  importsOrder = SymbolsFirst
}

Before:

import scala.concurrent.ExecutionContext.Implicits._
import scala.concurrent._
import scala.concurrent.duration
import scala.concurrent.{Promise, Future}

After:

import scala.concurrent._
import scala.concurrent.{Future, Promise}
import scala.concurrent.ExecutionContext.Implicits._
import scala.concurrent.duration

Enum: DEFAULT | INTELLIJ_2020_3

DEFAULT

An opinionated style recommended for new projects. The OrganizeImports rule tries its best to ensure correctness in all cases when possible. This default style aligns with this principal. In addition, by setting groupedImports to Explode, this style is also more friendly to version control and less likely to create annoying merge conflicts caused by trivial import changes.

OrganizeImports {
  blankLines = Auto
  coalesceToWildcardImportThreshold = null
  expandRelative = false
  groupExplicitlyImportedImplicitsSeparately = false
  groupedImports = Explode
  groups = [
    "*"
    "re:(javax?|scala)\\."
  ]
  importSelectorsOrder = Ascii
  importsOrder = Ascii
  preset = DEFAULT
  removeUnused = true
}

INTELLIJ_2020_3

A style that is compatible with the default configuration of the IntelliJ Scala 2020.3 import optimizer. It is mostly useful for adding OrganizeImports to existing projects developed using the IntelliJ Scala plugin. However, the configuration of this style may introduce subtle correctness issues (so does the default configuration of the IntelliJ Scala plugin). Please see the coalesceToWildcardImportThreshold option for more details.

OrganizeImports {
  blankLines = Auto
  coalesceToWildcardImportThreshold = 5
  expandRelative = false
  groupExplicitlyImportedImplicitsSeparately = false
  groupedImports = Merge
  groups = [
    "*"
    "re:(javax?|scala)\\."
  ]
  importSelectorsOrder = Ascii
  importsOrder = Ascii
  preset = INTELLIJ_2020_3
  removeUnused = true
}

DEFAULT

Boolean

true

Configuration:

Before:

After: