To run scalafix on your project, you must first install the Scalafix sbt plugin or command line interface. Currently, Scalafix does not provide any IDE integrations with IntelliJ/ENSIME.

sbt-scalafix

The sbt-plugin is the recommended integration to run semantic rules like RemoveUnusedImports or ExplicitResultTypes.

// ===> project/plugins.sbt
addSbtPlugin("ch.epfl.scala" % "sbt-scalafix" % "0.5.7")

// ===> sbt shell
> scalafixEnable // Setup scalafix for active session.
                 // Not needed if build.sbt is configured like below.
> scalafix                               // Run all rules configured in .scalafix.conf
> scalafix RemoveUnusedImports           // Run only RemoveUnusedImports rule
> myProject/scalafix RemoveUnusedImports // Run rule in one project only
> test:scalafix RemoveUnusedImports      // Run rule in single configuration
> scalafix ExplicitR<TAB>                // use tab completion
> scalafix replace:com.foobar/com.buzbaz // refactor (experimental)
> scalafix file:rules/MyRule.scala       // run local custom rule
> scalafix github:org/repo/v1            // run library migration rule

// (optional, to avoid need for scalafixEnable) permanently enable scalafix in build.sbt
// ===> build.sbt
scalaVersion := "2.12.4" // 2.11.11 is also supported.

// If you get "-Yrangepos is required" error or "Missing compiler plugin semanticdb",
// This setting must appear after scalacOptions and libraryDependencies.
scalafixSettings

// To configure for custom configurations like IntegrationTest
scalafixConfigure(Compile, Test, IntegrationTest)

Verify installation

To verify the installation, check that scalacOptions and libraryDependecies contain the values below.

> show scalacOptions
[info] * -Yrangepos                   // required
[info] * -Xplugin-require:semanticdb  // recommended
[info] * -P:semanticdb:sourceroot:/x  // recommended
> show libraryDependencies
[info] * org.scalameta:semanticdb-scalac:2.1.2:plugin->default(compile)

Example project

For a minimal example project using sbt-scalafix, see the scalacenter/scalafix-sbt-example repository.

git clone https://github.com/olafurpg/scalafix-sbt-example
cd scalafix-sbt-example
sbt "scalafix RemoveUnusedImports"
git diff // should produce a diff

Settings and tasks

Name Type Description
scalafix <rule>.. Unit Run scalafix on project sources. See Rules or use tab completion to explore supported rules.
sbtfix <rule>.. Unit Run scalafix on the build sources, *.sbt and project/*. Note: Only supports syntactic rules.
scalafixSourceRoot File The root directory of this project.
scalafixScalacOptions Seq[String] Necessary Scala compiler settings for scalafix to work.
scalafixVersion String Which version of scalafix-cli to run.
scalafixScalaVersion String Which Scala version of scalafix-cli to run.
scalafixSemanticdbVersion String Which version of org.scalameta:semanticdb-scalac to run.
scalafixVerbose Boolean If true, print out debug information.

semanticdb-sbt

⚠️ Experimental

semanticdb-sbt is a Scala 2.10 compiler plugin that extracts semantic information from the sbt compiler. Note. semanticdb-sbt only works for *.scala files, it does not support *.sbt files.

// project/plugins.sbt
addCompilerPlugin("org.scalameta" % "semanticdb-sbt" % "0.4.0" cross CrossVersion.full)

Once enabled, you can run scalafix rules against project/*.scala:

> reload // rebuild semanticdb for project/*.scala sources
> sbtfix Sbt1

scalafix-cli

The recommended way to install the scalafix command-line interface is with coursier.

Coursier

// coursier
coursier bootstrap ch.epfl.scala:scalafix-cli_2.12.4:0.5.7 -f --main scalafix.cli.Cli -o scalafix
./scalafix --help

Homebrew

// homebrew
brew install --HEAD olafurpg/scalafmt/scalafix
scalafix --help

wget

// wget
wget -O scalafix https://github.com/scalacenter/scalafix/blob/master/scalafix?raw=true
./scalafix --help

Once the scalafix cli is installed, consult the –help page for further usage instructions.

–help

scalafix 0.5.7-13-e4a5c35d
Usage: scalafix [options] [<file>...]
  --usage  
        Print usage and exit
  --help | -h  
        Print help message and exit
  --version | -v  
        Print version number and exit
  --verbose  
        If set, print out debugging inforation to stderr.
  --config | -c  <.scalafix.conf>
        File path to a .scalafix.conf configuration file.
  --config-str | -c  <imports.organize=false>
        String representing scalafix configuration
  --sourceroot  </foo/myproject>
        Absolute path passed to semanticdb with
	-P:semanticdb:sourceroot:<path>. Relative filenames persisted in the
	Semantic DB are absolutized by the sourceroot. Defaults to current
	working directory if not provided.
  --classpath  <entry1.jar:entry2.jar:target/scala-2.12/classes/>
        java.io.File.pathSeparator separated list of directories or jars
	containing '.semanticdb' files. The 'semanticdb' files are emitted by
	the semanticdb-scalac compiler plugin and are necessary for semantic
	rules like ExplicitResultTypes to function.
  --classpath-auto-roots  <value>
        Automatically infer --classpath starting from these directories.
	Ignored if --classpath is provided.
  --tool-classpath  <entry1.jar:entry2.jar:target/scala-2.12/classes/>
        Additional classpath to use when classloading/compiling rules
  --no-strict-semanticdb  
        Disable validation when loading semanticdb files.
  --rules | -r  <ProcedureSyntax OR file:LocalFile.scala OR scala:full.Name OR https://gist.com/.../Rule.scala>
        Scalafix rules to run.
  --stdout  
        If set, print fix to stdout instead of writing to file.
  --test  
        Exit non-zero code if files have not been fixed. Won't write to files.
  --out-from  </shared/>
        Regex that is passed as first argument to
	fileToFix.replaceAll(outFrom, outTo)
  --out-to  </custom/>
        Replacement string that is passed as second argument to
	fileToFix.replaceAll(outFrom, outTo)
  --exclude  <core Foobar.scala>
        Space separated list of regexes to exclude which files to fix. If a
	file match one of the exclude regexes, then it will not get fixed.
	Defaults to excluding no files.
  --single-thread  
        If true, run on single thread. If false (default), use all available
	cores
  --no-sys-exit  
        If true, does not sys.exit at the end. Useful for example in
	sbt-scalafix
  --quiet-parse-errors  
        Don't report parse errors for non-explictly passed filepaths.
  --bash  
        Print out bash completion file for scalafix. To install on scalafix
	--bash > /usr/local/etc/bash_completion.d/scalafix # Mac scalafix
	--bash > /etc/bash_completion.d/scalafix # Linux
  --zsh  
        Print out zsh completion file for scalafix. To install: scalafix --zsh
	> /usr/local/share/zsh/site-functions/_scalafix
  --non-interactive  
        Don't use fancy progress bar.
  --project-id  <value>
        String ID to prefix reported messages with
  --diff  
        If set, only apply scalafix to added and edited files in git diff
	against master.
  --diff-base  <value>
        If set, only apply scalafix to added and edited files in git diff
	against a provided branch, commit or tag. (defaults to master)
Available rules: DottyKeywords, DisableSyntax, NoFinalize, NoValInForComprehension, RemoveXmlLiterals, VolatileLazyVal, ProcedureSyntax, ExplicitUnit, DottyVolatileLazyVal, DottyVarArgPattern, NoInfer, Sbt1, ExplicitResultTypes, ExplicitReturnTypes, RemoveUnusedImports, RemoveUnusedTerms, NoAutoTupling, Disable

NOTE. The command line tool is mostly intended to be invoked programmatically
from build-tool integrations such as sbt-scalafix. The necessary fixture to run
semantic rules is tricky to setup manually.

Scalafix chooses which files to fix according to the following rules:
- scalafix <directory> <rule> finds *.scala files in <directory>
- when <rule> is semantic
  - if --classpath and --sourceroot are provided, then those are used to find .semanticdb files
  - otherwise, Scalafix will automatically look for META-INF/semanticdb directories from the
    current working directory.
- when --diff or --diff-branch is set it will parse the git diff and only
  apply on modified or added lines

  Those command will have the same effect:
    scalafix --diff
    scalafix --diff-branch=master

Examples (semantic):
  $ scalafix # automatically finds .semanticdb files and runs rule configured in .scalafix.conf.
  $ scalafix <directory> # same as above except only run on files in <directory>
  $ scalafix --rules RemoveUnusedImports # same as above but run RemoveUnusedImports.
  $ scalafix --classpath <foo.jar:target/classes> # explicitly pass classpath, --sourceroot is cwd.
  $ scalafix --classpath <foo.jar:target/classes> --sourceroot <directory>
  $ cat .scalafix.conf
  rules = [ProcedureSyntax]
  $ scalafix Code.scala # Same as --rules ProcedureSyntax

Exit status codes:
 Ok=0
 UnexpectedError=1
 ParseError=2
 ScalafixError=4
 InvalidCommandLineOption=8
 MissingSemanticApi=16
 StaleSemanticDB=32
 TestFailed=64
 LinterError=128

Maven

It is possible to use scalafix with scala-maven-plugin but it requires a custom setup since there is no scalafix specific Maven plugin.

Install semanticdb compiler plugin

First, download the semanticdb-scalac compiler plugin which corresponds to your exact scala version of your project, down to the patch number.

To begin with, it’s recommended to install the coursier command line interface https://github.com/coursier/coursier.

wget https://github.com/coursier/coursier/raw/master/coursier && chmod +x coursier && ./coursier --help

Coursier is a tool to download and launch library artifacts. Once you have coursier installed, assuming you are on 2.12.4:

coursier fetch --intransitive org.scalameta:semanticdb-scalac_2.12.4:2.1.2

You can also use wget or a simalar tool to retrieve the jar from https://repo1.maven.org/maven2/org/scalameta/semanticdb-scalac_2.12.4/2.1.2/semanticdb-scalac_2.12.4-2.1.2-javadoc.jar.

Compile sources with semanticdb

Let’s say the semanticdb-scalac_2.12.4-2.1.2.jar is available in PLUGINS/semanticdb-scalac_2.12.4-2.1.2.jar path on your file system.

Recompile your project using -DaddScalacArgs as follow:

mvn clean test -DskipTests=true -DaddScalacArgs="-Yrangepos|-Xplugin-require:semanticdb|-Xplugin:PLUGIN/semanticdb-scalac_2.12.4-2.1.2.jar|-Ywarn-unused-import"

Here, we compile both main sources and tests to have semantic information generated for all of them, but we skip test execution because it is not the point of that compilation. The added flags for scala are given with the addScalaArgs option (see http://davidb.github.io/scala-maven-plugin/help-mojo.html#addScalacArgs):

  • -Yrangepos is required for semanticdb to function properly,
  • -Xplugin:PLUGIN/semanticdb-scalac_2.12.4-2.1.2.jar give the path where the semanticdb jar can be found,
  • (optional) -Xplugin-require:semanticdb tells scalac to fails if it can’t load the semanticdb plugin,
  • (optional) -Ywarn-unused-import is required for the RemoveUnusedImports rule. If you don’t run RemoveUnusedImports you can skip this flag. Consult the scalafix documentation for each rule to see which flags it requires.
  • (optional) Customize the –sourceroot with -P:semanticdb:sourceroot:/path/to/sourceroot (more details below)

After compilation, double check that there exists a directory target/classes/META-INF/semanticdb/ containing files with the .semanticdb extension.

Important note: you will need to recompile to get up-to-date semanticdb information after each modification.

Run scalafix-cli

Install and use scalafix as explained above. One important note is that you need to give --sourceroot with the root path the same as the path where you ran your mvn clent test command. This may be confusing when you are on a multi-module project. For example, if your project is:

somepath/scalaProject
 |- moduleA
 |    |- src/{main, test}/scala
 |    `- target
 `- moduleB
      |- src/{main, test}/scala
      `- target

If you compile at scalaProject level, you will need to invoke scalafix with:

scalafix --rules RemoveUnusedImports --sourceroot /path/to/somepath/scalaProject

But if you compiled at moduleA level only, you will need to use:

scalafix --rules RemoveUnusedImports --sourceroot /path/to/somepath/scalaProject/moduleA

scalafix-core

Scalafix can be used as a library to run custom rules.

// ===> build.sbt
libraryDependencies += "ch.epfl.scala" %% "scalafix-core" % "0.5.7"
// (optional) Scala.js is also supported
libraryDependencies += "ch.epfl.scala" %%% "scalafix-core" % "0.5.7"

Example usage of the syntactic API.

import scalafix._
import scala.meta._

case object Uppercase extends Rule("Uppercase") {
  override def fix(ctx: RuleCtx): Patch =
    ctx.tree.collect {
      case name @ Name(value) => ctx.replaceTree(name, value.toUpperCase())
    }.asPatch
}

println(Uppercase("object Hello { println('world) }"))
// object HELLO { PRINTLN('world) }

The semantic API requires a more complicated setup. Please see Rule Authors.