Task Query Syntax

When interacting with Mill from the CLI, you often need to select tasks or modules. In most places, where Mill accepts a task, it really accepts a task selector query, which is the name of a task in its simplest form, but it can also contain wildcards, type pattern and other special syntax, making it a powerful tool to select specific tasks.

Selecting dedicated tasks

When invoking Mill, the simplest way to run a task is to give it with a fully qualified names.

Examples:

> mill for.compile
> mill for.run hello world
> mill foo.testCached
Understanding task paths and path segments

Each Mill module and task has a unique path. Each part of the path is called segment. Segments are separated with a dot (.). They look like regular Scala class name qualifiers.

There are two kind of segments: label segments and cross segments.

Label segments are the components of a task path and have the same restriction as Scala identifiers. They must start with a letter and may contain letters, numbers and a limited set of special characters - (dash), _ (underscore). They are used to denote Mill modules, tasks, but in the case of external modules their Scala package names.

Cross segments start with a label segment but contain additional square brackets ([, ]]) and are used to denote cross module and their parameters.

Segments can be surrounded by parentheses ((, ))). When combined with qualified type filter which contain dots (.), the parentheses need to be used, to avoid the dots to being interpreted as path separators.

Selecting multiple tasks

If you want to select more than one task, you have multiple options:

You can also combine these techniques to properly select your tasks

Enumerations

Enumeration are denoted by curly braces ({, }). Inside the curly braces you can place two or more selector paths, separated with a comma (,).

Examples:

  • {foo,bar} simple enumerates two tasks, foo and bar

  • foo.{compile,run} expands to foo.compile and foo.run

  • {_,foo.bar}.baz expands to _.baz and foo.bar.baz

Some Shells like bash support curly braces expansion. Make sure to properly mask the selector path, e.g. by putting it in quotes.

mill "foo.{compile.run}"

Wildcard selections

There are two wildcards, you can use as path segment.

  • _ The single underscore acts as a placeholder for a single segment.

  • __ The double underscore acts as a placeholder for many segments. In particular, it can represent an empty segment.

With wildcards, you can get explicit control over the position of a task in the build tree.

E.g. the filter _._._.jar will match all jar tasks, that are on the third-level of the build tree.

Type filters for wildcard selections

Type filters are always combined with wildcard. They are used to limit the scope of the wildcard to only match path segments of the specified types. For module paths this means, the represented module needs to be an instance of the specified type.

A type filter always starts with a wildcard (_, __) followed by a colon (:) and finally the type qualifier.

The type is matched by its name and optionally by its enclosing types and packages, separated by a . sign. Since this is also used to separate task path segments, a type selector segment containing a . needs to be enclosed in parentheses. A fully qualified type can be denoted with the _root_ package.

> mill resolve __:TestModule.jar
> mill resolve "(__:scalalib.TestModule).jar"
> mill resolve "(__:mill.scalalib.TestModule).jar"
> mill resolve "(__:_root_.mill.scalalib.TestModule).jar"

If the type qualifier starts with a ^ or !, it’s only matching types which are not instances of the specified type.

> mill resolve __:^TestModule.jar

You can also add more than one type filters to a wildcard.

> mill resolve "__:JavaModule:^ScalaModule:^TestModule.jar"
Type filter are currently only supported for module selections, but not for task selections. That means, you can’t filter based on the result type of a task.

Start a new task selector with +

On the Mill CLI you can also start a complete new task selector with the + sign.

There is a subtle difference between the expansion of enumerations, wildcards and wildcards with type filters in contrast to the start of a new selector with +.

For all the former versions, Mill parses them into a complex but single task selector path and subsequent parameters are used for all resolved tasks.

Whereas the + start a completely new selector path to which you can also provide a different parameter list. This is important when using command tasks which can accept their own parameters. The JavaModule.run command is an example.

> mill foo.run hello                         (1)
> mill {foo,bar}.run hello                   (2)
> mill __:JavaModule:^TestModule.run hello   (3)
> mill foo.run hello + bar.run world         (4)
1 Runs foo.run with the parameter hello
2 Expands to foo.run and bar.run and runs both with the parameter hello.
3 Selects the run command of all Java modules, but not test modules, and runs them with the parameter hello.
4 Runs fun.run with the parameter hello and bar.run with the parameter world.