From f2a8f8ad8fcc447b8c4a5790e35853ed5d2ef8d3 Mon Sep 17 00:00:00 2001 From: Pete Davison Date: Sun, 2 Oct 2022 06:59:49 +0000 Subject: [PATCH] docs: update usage and api reference --- docs/docs/api_reference.md | 8 +++++--- docs/docs/usage.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 3 deletions(-) diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md index e67b721a..50cc0aec 100644 --- a/docs/docs/api_reference.md +++ b/docs/docs/api_reference.md @@ -89,7 +89,6 @@ Some environment variables can be overriden to adjust Task behavior. | `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. | | `tasks` | [`map[string]Task`](#task) | | The task definitions. | - ### Include | Attribute | Type | Default | Description | @@ -97,7 +96,8 @@ Some environment variables can be overriden to adjust Task behavior. | `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. | | `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. | | `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. | -| `internal` | `bool` | `false` | If `true`, tasks will be omitted from both `--list` and `--list-all`. | +| `internal` | `bool` | `false` | If `true`, tasks will not be callable from the command line and will be omitted from both `--list` and `--list-all`. | +| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. | :::info @@ -116,11 +116,13 @@ includes: | - | - | - | - | | `desc` | `string` | | A short description of the task. This is listed when calling `task --list`. | | `summary` | `string` | | A longer description of the task. This is listed when calling `task --summary [task]`. | +| `aliases` | `[]string` | | Alternative names for the task. | +| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. | | `sources` | `[]string` | | List of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. | | `dir` | `string` | | The current directory which this task should run. | | `method` | `string` | `checksum` | Method used by this task. Default to the one declared globally or `checksum`. Available options: `checksum`, `timestamp` and `none` | | `silent` | `bool` | `false` | Skips some output for this task. Note that STDOUT and STDERR of the commands will still be redirected. | -| `internal` | `bool` | `false` | If `true`, omit this task from both `--list` and `--list-all`. | +| `internal` | `bool` | `false` | If `true`, this task will not be callable from the command line and will be omitted from both `--list` and `--list-all`. | | `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. | | `prefix` | `string` | | Allows to override the prefix print before the STDOUT. Only relevant when using the `prefixed` output mode. | | `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the commands. | diff --git a/docs/docs/usage.md b/docs/docs/usage.md index a36f97e1..d96b4454 100644 --- a/docs/docs/usage.md +++ b/docs/docs/usage.md @@ -230,6 +230,19 @@ includes: DOCKER_IMAGE: frontend_image ``` +### Namespace aliases + +When including a taskfile, you can give the namespace a list of `aliases`. This works in the same way as [task aliases](#task-aliases) and can be used together to create shorter and easier-to-type commands. + +```yaml +version: '3' + +includes: + generate: + taskfile: ./taskfiles/Generate.yml + aliases: [gen] +``` + :::info Vars declared in the included Taskfile have preference over the @@ -965,6 +978,30 @@ If the task does not have a summary or a description, a warning is printed. Please note: *showing the summary will not execute the command*. +## Task aliases + +Aliases are alternative names for tasks. They can be used to make it easier and +quicker to run tasks with long or hard-to-type names. You can use them on the +command line, when [calling sub-tasks](#calling-another-task) in your Taskfile +and when [including tasks](#including-other-taskfiles) with aliases from another +Taskfile. They can also be used together with [namespace +aliases](#namespace-aliases). + +```yaml +version: '3' + +tasks: + generate: + aliases: [gen] + cmds: + - task: gen-mocks + + generate-mocks: + aliases: [gen-mocks] + cmds: + - echo "generating..." +``` + ## Overriding task name Sometimes you may want to override the task name printed on the summary, up-to-date