| <a id="task_expression"/> | |
| Task Expression | |
| -------------- | |
| 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_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! | |
| ``` | |
| <a id="task_reference"/> | |
| Task Reference | |
| --------- | |
| 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/.../<any>.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/<user>), 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/<sharded-group-uuid>), | |
| 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 | |
| ... | |
| ``` |