Creating Aliases in SBT

1. Introduction

SBT is the most popular build tool for Scala applications. It has many powerful features and customization to support any complex build structure.

In this tutorial, we’ll look at command aliases in sbt and how it streamlines the development flow.

2. SBT Alias

We can create aliases in sbt for complex commands like with Linux commands. Using aliases, we can create more straightforward shortcuts for complex operations.

2.1. Create a Simple Alias

We can create an alias by using the addCommandAlias() method in the build.sbt file(or any other .sbt files).

We’ll create a simple alias to understand the concept:

addCommandAlias("compileAndTest", "compile;test;")

Here, we defined an alias compileAndTest that executes the sbt commands compile and test sequentially. We can notice that a semicolon separates each command. We can use this just like any other sbt command:

sbt compileAndTest

This executes the commands compile and test within a single sbt session in the order in which we defined the commands. If one of the commands in the alias fails, then the entire alias command exits immediately.

If the build.sbt file gets bigger and has many aliases, it’s a good idea to move the alias commands to a separate file called alias.sbt for better readability.

2.2. Create Complex Alias

We can create aliases for any complex sequence of operations. This is useful in defining complex operations that can be executed very easily.

We’ll create a more complex version of the alias. Let’s assume that we’re using the following ScalaTest command to run a particular test:

testOnly com.baeldung.scala.scalatest.runner.ScalaTestRunnerTests -- -z "spaces" -n "BooleanTests"

The above command is very long to always type by hand. If it’s used many times, we can create an alias for it to make the usage easier:

addCommandAlias("specialTests", "testOnly com.baeldung.scala.scalatest.runner.ScalaTestRunnerTests -- -z \"spaces\" -n \"BooleanTests\"")

Now, we can execute the test by using the command:

sbt specialTests

This makes it much easier to run this complicated test command.

Additionally, we can create even more complex commands to set the sbt options through aliases. For example, we can create a complex command alias for running a set of tests in the CI pipeline:

addCommandAlias(
  "ciFull",
  """;compile;test; set ThisBuild/IntegrationTest/testOptions += Tests.Filter(t => !t.endsWith("ManualTest")); it:test""".stripMargin
)

Let’s execute this alias:

sbt ciFull

This alias command does a lot of operations, including compilation, unit test execution, and selection of a set of integration tests to execute. This way, the aliases make it easy for the developers to execute a complex set of sbt tasks.

Furthermore, another advantage is the ability to modify and enhance specific commands without requiring any changes at the alias’s call site. This means developers can update or introduce additional features to a command without modifying every instance where the alias is used.

Additionally, we can create aliases using existing alias commands:

addCommandAlias("compileAndRunSpecialTest","compile;specialTests")

This simplifies expanding build commands without modifying the command names themselves.

3. Managing Aliases in the SBT Shell

We created the aliases in the build configuration files in the previous section. Sometimes, we might need to list the aliases or modify an alias temporarily without changing the build configurations in the code. We can do such operations in the sbt shell with ease.

3.1. List Aliases

We can list all the configured aliases in a project using the command:

sbt alias

This lists all the aliases and the full command used in the alias. Here’s a sample output from the Baeldung https://github.com/Baeldung/scala-tutorials repository:

This list all the alias commands within the build across different .sbt files in the project. This is a constructive way to understand all the new project’s aliases quickly.

We can also see the details of a particular alias by providing the alias name:

alias ci

This prints the expansion of the alias ci in the sbt shell:

Alternatively, we can use the inspect command to view the details of an alias command:

inspect ci

This prints the information regarding the ci command to the console:

We can use the inspect command for both sbt tasks and alias commands.

3.2. Create an Alias

We can also define a temporary alias directly in the sbt shell without modifying the build files. We can define a temporary alias in the sbt shell:

alias tempAlias = clean;compile;test:compile;

Now, we can execute the command tempAlias within the sbt shell just like any other command. We should be aware that this alias is temporary and will cease to exist as soon as the sbt shell is closed.

3.3. Remove or Overwrite an Existing Alias

In addition to creating aliases, it’s also possible to temporarily delete or overwrite an existing command. For example, let’s overwrite the current ci alias:

alias ci=compile

The above command overrides the previous ci command with only compile operation. This way, we can slightly modify and test the existing commands without permanently changing the original command.

Similarly, we can remove a command by setting it with an empty value:

alias ci=

This removes the command ci from the current sbt shell. We can verify that by listing all the aliases in the shell.

4. Advantages of Aliases

Here are some of the advantages of using SBT aliases:

• Improved productivity and better readability
• Simplified execution of commands and ease of management
• Better automation and customization

5. Conclusion

In this article, we discussed the aliases in SBT. We looked at creating and using aliases to improve productivity and enhance readability.

By creating shortcuts,  developers can easily manage and execute frequent operations.