The tasks in subtask and preload-task can be defined using a Task Expression. Each task expression can contain multiple tasks (all can be optional). Tasks from other files can be referenced using Task Reference.
TASK_EXPR = TASK_REFERENCE [ WHITE_SPACE * '|' [ WHITE_SPACE * TASK_EXPR ] ]
To define a task that may not exist and that will not cause the task referencing it to be INVALID, follow the task name with pipe (|
) character. This feature is particularly useful when a property is used in the task name.
preload-task = Optional task {$_name} |
To define an alternate task to load when an optional task does not exist, list the alternate task name after the pipe (|
) character. This feature may be chained together as many times as needed.
subtask = Optional Subtask {$_name} | Backup Optional Subtask {$_name} Backup | Default Subtask # Must exist if the above two don't!
Tasks reference can be a simple task name when the defined task is intended to be in the same file, tasks from other files can also be referenced by syntax explained below.
TASK_REFERENCE = [ [ TASK_FILE_PATH ] '^' ] TASK_NAME
To reference a task from root task.config (top level task.config file of a repository) on the current ref, prefix the task name with ^
.
Example:
task/.../.config
... preload-task = ^Task in root task config ...
task.config
... [task "Task in root task config"] ...
To provide an absolute reference to a task under the task
folder, provide the subpath starting from task
directory with a leading /
followed by a ^
and then task name.
Example:
task.config
... subtask = /foo/bar/baz.config^Absolute Example Task ...
task/foo/bar/baz.config
... [task "Absolute Example Task"] ...
Similarly, to provide reference to tasks which are in a subdirectory of the file containing the current task avoid the leading /
.
Example:
task/foo/file.config
... subtask = bar/baz.config^Relative Example Task ...
task/foo/bar/baz.config
... [task "Relative Example Task"] ...
Relative tasks specified in a root task.config would look for a file path under the task directory.
Example:
task.config
... subtask = foo/bar.config^Relative from Root Example Task ...
task/foo/bar.config
... [task "Relative from Root Example Task"] ...