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 and refs 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 and refs can also be referenced by syntax explained below.

 TASK_REFERENCE = [
                    [ // TASK_FILE_PATH ]
                    [ @USERNAME [ TASK_FILE_PATH ] ] |
                    [ %GROUP_NAME [ TASK_FILE_PATH ] ] |
                    [ %%GROUP_UUID [ TASK_FILE_PATH ] ] |
                    [ 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"]
    ...

To reference a task from a specific user ref (All-Users.git:refs/users/), specify the username with @.

when referencing from user refs, to get task from top level task.config on a user ref use @<username>^<task_name> and to get any task under the task directory use the relative path, like: @<username>/<relative path from task dir>^<task_name>. It doesn't matter which project, ref and file one is referencing from while using this syntax.

Example: Assumption: Account id of user_a is 1000000

All-Users:refs/users/00/1000000:task.config

    ...
    [task "top level task"]
    ...

All-Users:refs/users/00/1000000:/task/dir/common.config

    ...
    [task "common task"]
    ...

All-Projects:refs/meta/config:/task.config

    ...
    preload-task = @user_a_username^top level task
    preload-task = @user_a_username/dir/common.config^common task
    ...

To reference a task from root task.config on the All-Projects.git, prefix the task name with //^ and to reference a task from task dir on the All-Projects.git, use //<relative path from task dir>^<task_name>. It doesn't matter which project, ref and file one is referencing from while using this syntax.

Example:

All-Projects:refs/meta/config:task.config

    ...
    [task "root task"]
    ...

All-Projects:refs/meta/config:/task/dir/sample.config

    ...
    [task "sample task"]
    ...

All-Users:refs/users/00/1000000:task.config

    ...
    preload-task = //dir/sample.config^sample task
    preload-task = //^root task
    ...

To reference a task from a specific group ref (All-Users.git:refs/groups/), specify the group name with % or group uuid with %%.

When referencing from group refs, to get task from top level task.config on a group ref use %<group_name>^<task_name> or %%<group_uuid>^<task_name> and to get any task under the task directory use the relative path, like: %<group_name>/<relative path from task dir>^<task_name> or %%<group_uuid>/<relative path from task dir>^<task_name>. It doesn't matter which project, ref and file one is referencing from while using this syntax.

Example: Assumption: Group uuid of group_a is 720269095421a08a24889e29d092df1839a7a706

All-Users:refs/groups/72/720269095421a08a24889e29d092df1839a7a706:task.config

    ...
    [task "top level task"]
    ...

All-Users:refs/groups/72/720269095421a08a24889e29d092df1839a7a706:/task/dir/common.config

    ...
    [task "common task"]
    ...

All-Projects:refs/meta/config:/task.config

    ...
    preload-task = %group_a^top level task
    preload-task = %%720269095421a08a24889e29d092df1839a7a706/dir/common.config^common task
    ...