go/task
go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-01-04 03:48:02 +02:00
Code Issues Releases Activity

v3.38.0

Browse Source
This commit is contained in:
Pete Davison 2024-06-30 14:50:47 +00:00
parent cc14996b71
commit 88b095020e
No known key found for this signature in database
17 changed files with 991 additions and 659 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -1,6 +1,6 @@
# Changelog
## Unreleased
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).
- Some YAML parsing errors will now show in a more user friendly way (#1619 by

2
package-lock.json generated
View File

@ -1,6 +1,6 @@
{
"name": "@go-task/cli",
"version": "3.37.2",
"version": "3.38.0",
"lockfileVersion": 2,
"requires": true,
"packages": {

2
package.json
View File

@ -1,6 +1,6 @@
{
"name": "@go-task/cli",
"version": "3.37.2",
"version": "3.38.0",
"description": "A task runner / simpler Make alternative written in Go",
"scripts": {
"postinstall": "go-npm install",

40
website/docs/changelog.mdx
View File

@ -5,6 +5,44 @@ sidebar_position: 14
# Changelog
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).
- Some YAML parsing errors will now show in a more user friendly way (#1619 by
@pd93).
- Prefixed outputs will now be colorized by default (#1572 by
@AlexanderArvidsson)
- [References](https://taskfile.dev/usage/#referencing-other-variables) are now
generally available (no experiments required) (#1654 by @pd93).
- Templating functions can now be used in references (#1645, #1654 by @pd93).
- Added a new
[templating reference page](https://taskfile.dev/reference/templating/) to the
documentation (#1614, #1653 by @pd93).
- If using the
[Map Variables experiment (1)](https://taskfile.dev/experiments/map-variables/?proposal=1),
references are available by
[prefixing a string with a `#`](https://taskfile.dev/experiments/map-variables/?proposal=1#references)
(#1654 by @pd93).
- If using the
[Map Variables experiment (2)](https://taskfile.dev/experiments/map-variables/?proposal=2),
the `yaml` and `json` keys are no longer available (#1654 by @pd93).
- Added a new `TASK_REMOTE_DIR` environment variable to configure where cached
remote Taskfiles are stored (#1661 by @vmaerten).
- Added a new `--clear-cache` flag to clear the cache of remote Taskfiles (#1639
by @vmaerten).
- Improved the readability of cached remote Taskfile filenames (#1636 by
@vmaerten).
- Starting releasing a binary for the `riscv64` architecture on Linux (#1699 by
@mengzhuo).
- Added `CLI_SILENT` and `CLI_VERBOSE` variables (#1480, #1669 by @Vince-Smith).
- Fixed a couple of bugs with the `prompt:` feature (#1657 by @pd93).
- Fixed JSON Schema to disallow invalid properties (#1657 by @pd93).
- Fixed version checks not working as intended (#872, #1663 by @vmaerten).
- Fixed a bug where included tasks were run multiple times even if `run: once`
was set (#852, #1655 by @pd93).
- Fixed some bugs related to column formatting in the terminal (#1350, #1637,
#1656 by @vmaerten).
## v3.37.2 - 2024-05-12
- Fixed a bug where an empty Taskfile would cause a panic (#1648 by @pd93).
@ -25,7 +63,7 @@ sidebar_position: 14
- Refactored how Task reads, parses and merges Taskfiles using a DAG (#1563,
#1607 by @pd93).
- Fix a bug which stopped tasks from using `stdin` as input (#1593, #1623 by
@pd03).
@pd93).
- Fix error when a file or directory in the project contained a special char
like `&`, `(` or `)` (#1551, #1584 by @andreynering).
- Added alias `q` for template function `shellQuote` (#1601, #1603 by @vergenzt)

40
website/versioned_docs/version-latest/changelog.mdx
View File

@ -5,6 +5,44 @@ sidebar_position: 14
# Changelog
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).
- Some YAML parsing errors will now show in a more user friendly way (#1619 by
@pd93).
- Prefixed outputs will now be colorized by default (#1572 by
@AlexanderArvidsson)
- [References](https://taskfile.dev/usage/#referencing-other-variables) are now
generally available (no experiments required) (#1654 by @pd93).
- Templating functions can now be used in references (#1645, #1654 by @pd93).
- Added a new
[templating reference page](https://taskfile.dev/reference/templating/) to the
documentation (#1614, #1653 by @pd93).
- If using the
[Map Variables experiment (1)](https://taskfile.dev/experiments/map-variables/?proposal=1),
references are available by
[prefixing a string with a `#`](https://taskfile.dev/experiments/map-variables/?proposal=1#references)
(#1654 by @pd93).
- If using the
[Map Variables experiment (2)](https://taskfile.dev/experiments/map-variables/?proposal=2),
the `yaml` and `json` keys are no longer available (#1654 by @pd93).
- Added a new `TASK_REMOTE_DIR` environment variable to configure where cached
remote Taskfiles are stored (#1661 by @vmaerten).
- Added a new `--clear-cache` flag to clear the cache of remote Taskfiles (#1639
by @vmaerten).
- Improved the readability of cached remote Taskfile filenames (#1636 by
@vmaerten).
- Starting releasing a binary for the `riscv64` architecture on Linux (#1699 by
@mengzhuo).
- Added `CLI_SILENT` and `CLI_VERBOSE` variables (#1480, #1669 by @Vince-Smith).
- Fixed a couple of bugs with the `prompt:` feature (#1657 by @pd93).
- Fixed JSON Schema to disallow invalid properties (#1657 by @pd93).
- Fixed version checks not working as intended (#872, #1663 by @vmaerten).
- Fixed a bug where included tasks were run multiple times even if `run: once`
was set (#852, #1655 by @pd93).
- Fixed some bugs related to column formatting in the terminal (#1350, #1637,
#1656 by @vmaerten).
## v3.37.2 - 2024-05-12
- Fixed a bug where an empty Taskfile would cause a panic (#1648 by @pd93).
@ -25,7 +63,7 @@ sidebar_position: 14
- Refactored how Task reads, parses and merges Taskfiles using a DAG (#1563,
#1607 by @pd93).
- Fix a bug which stopped tasks from using `stdin` as input (#1593, #1623 by
@pd03).
@pd93).
- Fix error when a file or directory in the project contained a special char
like `&`, `(` or `)` (#1551, #1584 by @andreynering).
- Added alias `q` for template function `shellQuote` (#1601, #1603 by @vergenzt)

23
website/versioned_docs/version-latest/deprecations/template_functions.mdx Normal file
View File

@ -0,0 +1,23 @@
---
slug: /deprecations/template-functions/
---
# Template Functions
:::warning
This deprecation breaks the following functionality:
- A small set of templating functions
:::
The following templating functions are deprecated. Any replacement functions are
listed besides the function being removed.
| Deprecated function | Replaced by |
| ------------------- | ----------- |
| `IsSH` | - |
| `FromSlash` | `fromSlash` |
| `ToSlash` | `toSlash` |
| `ExeExt` | `exeExt` |

234
website/versioned_docs/version-latest/experiments/map_variables.mdx
View File

@ -43,9 +43,9 @@ To enable this experiment, set the environment variable:
:::
This proposal removes support for the `sh` keyword in favour of a new syntax for
dynamically defined variables, This allows you to define a map directly as you
would for any other type:
This proposal removes support for the `sh` and `ref` keywords in favour of a new
syntax for dynamically defined variables and references. This allows you to
define a map directly as you would for any other type:
```yaml
version: 3
@ -60,11 +60,26 @@ tasks:
## Migration
Taskfiles with dynamically defined variables via the `sh` subkey will no longer
work with this experiment enabled. In order to keep using dynamically defined
variables, you will need to migrate your Taskfile to use the new syntax.
Taskfiles with dynamically defined variables via the `sh` subkey or references
defined with `ref` will no longer work with this experiment enabled. In order to
keep using these features, you will need to migrate your Taskfile to use the new
syntax.
Previously, you might have defined a dynamic variable like this:
### Dynamic Variables
Previously, you had to define dynamic variables using the `sh` subkey. With this
experiment enabled, you will need to remove the `sh` subkey and define your
command as a string that begins with a `$`. This will instruct Task to interpret
the string as a command instead of a literal value and the variable will be
populated with the output of the command. For example:
<Tabs defaultValue="2"
values={[
{label: 'Before', value: '1'},
{label: 'After', value: '2'}
]}>
<TabItem value="1">
```yaml
version: 3
@ -78,10 +93,8 @@ tasks:
- 'echo {{.CALCULATED_VAR}}'
```
With this experiment enabled, you will need to remove the `sh` subkey and define
your command as a string that begins with a `$`. This will instruct Task to
interpret the string as a command instead of a literal value and the variable
will be populated with the output of the command. For example:
</TabItem>
<TabItem value="2">
```yaml
version: 3
@ -89,14 +102,56 @@ version: 3
tasks:
foo:
vars:
CALCULATED_VAR: '$echo hello'
CALCULATED_VAR: '$echo hello' # <-- Prefix dynamic variable with a `$`
cmds:
- 'echo {{.CALCULATED_VAR}}'
```
If your current Taskfile contains a string variable that begins with a `$`, you
will now need to escape the `$` with a backslash (`\`) to stop Task from
executing it as a command.
</TabItem></Tabs>
### References
<Tabs defaultValue="2"
values={[
{label: 'Before', value: '1'},
{label: 'After', value: '2'}
]}>
<TabItem value="1">
```yaml
version: 3
tasks:
foo:
vars:
VAR: 42
VAR_REF:
ref: '.FOO'
cmds:
- 'echo {{.VAR_REF}}'
```
</TabItem>
<TabItem value="2">
```yaml
version: 3
tasks:
foo:
vars:
VAR: 42
VAR_REF: '#.FOO' # <-- Prefix reference with a `#`
cmds:
- 'echo {{.VAR_REF}}'
```
</TabItem></Tabs>
If your current Taskfile contains a string variable that begins with a `$` or a
`#`, you will now need to escape it with a backslash (`\`) to stop Task from
interpreting it as a command or reference.
</TabItem>
<TabItem value="2">
@ -123,157 +178,12 @@ tasks:
BAR: true # <-- Other types of variables are still defined directly on the key
BAZ:
sh: 'echo Hello Task' # <-- The `sh` subkey is still supported
QUX:
ref: '.BAZ' # <-- The `ref` subkey is still supported
cmds:
- 'echo {{.FOO.a}}'
```
## Parsing JSON and YAML
In addition to the new `map` keyword, this proposal also adds support for the
`json` and `yaml` keywords for parsing JSON and YAML strings into real
objects/arrays. This is similar to the `fromJSON` template function, but means
that you only have to parse the JSON/YAML once when you declare the variable,
instead of every time you want to access a value.
<Tabs defaultValue="2"
values={[
{label: 'Before', value: '1'},
{label: 'After', value: '2'}
]}>
<TabItem value="1">
```yaml
version: 3
tasks:
foo:
vars:
FOO: '{"a": 1, "b": 2, "c": 3}' # <-- JSON string
cmds:
- 'echo {{(fromJSON .FOO).a}}' # <-- Parse JSON string every time you want to access a value
- 'echo {{(fromJSON .FOO).b}}'
```
</TabItem>
<TabItem value="2">
```yaml
version: 3
tasks:
foo:
vars:
FOO:
json: '{"a": 1, "b": 2, "c": 3}' # <-- JSON string parsed once
cmds:
- 'echo {{.FOO.a}}' # <-- Access values directly
- 'echo {{.FOO.b}}'
```
</TabItem></Tabs>
## Variables by reference
Lastly, this proposal adds support for defining and passing variables by
reference. This is really important now that variables can be types other than a
string.
Previously, to send a variable from one task to another, you would have to use
the templating system. Unfortunately, the templater _always_ outputs a string
and operations on the passed variable may not have behaved as expected. With
this proposal, you can now pass variables by reference using the `ref` subkey:
<Tabs defaultValue="2"
values={[
{label: 'Before', value: '1'},
{label: 'After', value: '2'}
]}>
<TabItem value="1">
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO: '{{.FOO}}' # <-- FOO gets converted to a string when passed to bar
bar:
cmds:
- 'echo {{index .FOO 0}}' # <-- FOO is a string so the task outputs '91' which is the ASCII code for '[' instead of the expected 'A'
```
</TabItem>
<TabItem value="2">
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO:
ref: .FOO # <-- FOO gets passed by reference to bar and maintains its type
bar:
cmds:
- 'echo {{index .FOO 0}}' # <-- FOO is still a map so the task outputs 'A' as expected
```
</TabItem></Tabs>
This means that the type of the variable is maintained when it is passed to
another Task. This also works the same way when calling `deps` and when defining
a variable and can be used in any combination:
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
BAR:
ref: .FOO # <-- BAR is defined as a reference to FOO
deps:
- task: bar
vars:
BAR:
ref: .BAR # <-- BAR gets passed by reference to bar and maintains its type
bar:
cmds:
- 'echo {{index .BAR 0}}' # <-- BAR still refers to FOO so the task outputs 'A'
```
All references use the same templating syntax as regular templates, so in
addition to simply calling `.FOO`, you can also pass subkeys (`.FOO.BAR`) or
indexes (`index .FOO 0`) and use functions (`len .FOO`):
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO:
ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar
bar:
cmds:
- 'echo {{.MYVAR}}' # <-- FOO is just the letter 'A'
```
</TabItem></Tabs>
## Looping over maps

9
website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx
View File

@ -105,13 +105,20 @@ internet and cached locally. If for whatever reason, you lose access to the
internet, you will still be able to run your tasks by specifying the `--offline`
flag. This will tell Task to use the latest cached version of the file instead
of trying to download it. You are able to use the `--download` flag to update
the cached version of the remote files without running any tasks.
the cached version of the remote files without running any tasks. You are able
to use the `--clear-cache` flag to clear all cached version of the remote files
without running any tasks.
By default, Task will timeout requests to download remote files after 10 seconds
and look for a cached copy instead. This timeout can be configured by setting
the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will
set the timeout to 5 seconds.
By default, the cache is stored in the Task temp directory, represented by the
`TASK_TEMP_DIR` [environment variable](../reference/environment.mdx) You can
override the location of the cache by setting the `TASK_REMOTE_DIR` environment
variable. This way, you can share the cache between different projects.
{/* prettier-ignore-start */}
[enabling-experiments]: ./experiments.mdx#enabling-experiments
[man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack

19
website/versioned_docs/version-latest/faq.mdx
View File

@ -7,6 +7,25 @@ sidebar_position: 15
This page contains a list of frequently asked questions about Task.
## When will \<feature\> be released? / ETAs
Task is _free_ and _open source_ project maintained by a small group of
volunteers with full time jobs and lives outside of the project. Because of
this, it is difficult to predict how much time we will be able to dedicate to
the project in advance and we don't want to make any promises that we can't
keep. For this reason, we are unable to provide ETAs for new features or
releases. We make a "best effort" to provide regular releases and fix bugs in a
timely fashion, but sometimes our personal lives must take priority.
ETAs are probably the number one question we (and maintainers of other open
source projects) get asked. We understand that you are passionate about the
project, but it can be overwhelming to be asked this question so often. Please
be patient and avoid asking for ETAs.
The best way to speed things up is to contribute to the project yourself. We
always appreciate new contributors. If you are interested in contributing, check
out the [contributing guide](./contributing.mdx).
## Why won't my task update my shell environment?
This is a limitation of how shells work. Task runs as a subprocess of your

17
website/versioned_docs/version-latest/installation.mdx
View File

@ -146,6 +146,15 @@ can install Task from [winget-pkgs](https://github.com/microsoft/winget-pkgs).
winget install Task.Task
```
### Pacstall
If you are using Debian or Ubuntu, and have [Pacstall](https://pacstall.dev/) installed, you can install Task by running:
```shell
pacstall -I go-task-deb
```
This installation method is community owned. After a new release of Task, it may take some time until it's available in [Pacstall](https://pacstall.dev/packages/go-task-deb).
## Get The Binary
### Binary
@ -185,6 +194,14 @@ default.
:::
By default, it installs the latest version available.
You can also specify a tag (available in [releases](https://github.com/go-task/task/releases))
to install a specific version:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d v3.36.0
```
### GitHub Actions
If you want to install Task in GitHub Actions you can try using

2
website/versioned_docs/version-latest/reference/_category_.yml Normal file
View File

@ -0,0 +1,2 @@
position: 4
label: Reference

118
website/versioned_docs/version-latest/reference/cli.mdx Normal file
View File

@ -0,0 +1,118 @@
---
slug: /reference/cli
sidebar_position: 1
---
# CLI Reference
Task CLI commands have the following syntax:
```shell
task [--flags] [tasks...] [-- CLI_ARGS...]
```
:::tip
If `--` is given, all remaining arguments will be assigned to a special
`CLI_ARGS` variable
## Flags
:::
| Short | Flag | Type | Default | Description |
| ----- | --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed.<br />`default` - Alphanumeric with root tasks first<br />`alphanumeric` - Alphanumeric<br />`none` - No sorting (As they appear in the Taskfile) |
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
| `-o` | `--output` | `string` | Default set in the Taskfile or `interleaved` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| `-y` | `--yes` | `bool` | `false` | Assume "yes" as answer to all prompts. |
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
| | `--summary` | `bool` | `false` | Show summary about a task. |
| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
| | `--version` | `bool` | `false` | Show Task version. |
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task.
## Exit Codes
Task will sometimes exit with specific exit codes. These codes are split into
three groups with the following ranges:
- General errors (0-99)
- Taskfile errors (100-199)
- Task errors (200-299)
A full list of the exit codes and their descriptions can be found below:
| Code | Description |
| ---- | ------------------------------------------------------------ |
| 0 | Success |
| 1 | An unknown error occurred |
| 100 | No Taskfile was found |
| 101 | A Taskfile already exists when trying to initialize one |
| 102 | The Taskfile is invalid or cannot be parsed |
| 103 | A remote Taskfile could not be downloaded |
| 104 | A remote Taskfile was not trusted by the user |
| 105 | A remote Taskfile was could not be fetched securely |
| 106 | No cache was found for a remote Taskfile in offline mode |
| 107 | No schema version was defined in the Taskfile |
| 200 | The specified task could not be found |
| 201 | An error occurred while executing a command inside of a task |
| 202 | The user tried to invoke a task that is internal |
| 203 | There a multiple tasks with the same name or alias |
| 204 | A task was called too many times |
| 205 | A task was cancelled by the user |
| 206 | A task was not executed due to missing required variables |
These codes can also be found in the repository in
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
:::info
When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed
commands will be passed through to the user instead.
:::
## JSON Output
When using the `--json` flag in combination with either the `--list` or
`--list-all` flags, the output will be a JSON object with the following
structure:
```json
{
"tasks": [
{
"name": "",
"desc": "",
"summary": "",
"up_to_date": false,
"location": {
"line": 54,
"column": 3,
"taskfile": "/path/to/Taskfile.yml"
}
}
// ...
],
"location": "/path/to/Taskfile.yml"
}
```

48
website/versioned_docs/version-latest/reference/environment.mdx Normal file
View File

@ -0,0 +1,48 @@
---
slug: /reference/environment
sidebar_position: 4
---
# Environment Reference
Task allows you to configure some behavior using environment variables. This
page lists all the environment variables that Task supports.
| ENV | Default | Description |
| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
| `TASK_REMOTE_DIR` | `TASK_TEMP_DIR` | Location of the remote temp dir (used for caching). Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
| `FORCE_COLOR` | | Force color output usage. |
## Custom Colors
| ENV | Default | Description |
| --------------------------- | ------- | ----------------------- |
| `TASK_COLOR_RESET` | `0` | Color used for white. |
| `TASK_COLOR_RED` | `31` | Color used for red. |
| `TASK_COLOR_GREEN` | `32` | Color used for green. |
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
| `TASK_COLOR_BRIGHT_RED` | `91` | Color used for red. |
| `TASK_COLOR_BRIGHT_GREEN` | `92` | Color used for green. |
| `TASK_COLOR_BRIGHT_YELLOW` | `93` | Color used for yellow. |
| `TASK_COLOR_BRIGHT_BLUE` | `94` | Color used for blue. |
| `TASK_COLOR_BRIGHT_MAGENTA` | `95` | Color used for magenta. |
| `TASK_COLOR_BRIGHT_CYAN` | `96` | Color used for cyan. |
All color variables are [ANSI color codes][ansi]. You can specify multiple codes
separated by a semicolon. For example: `31;1` will make the text bold and red.
Task also supports 8-bit color (256 colors). You can specify these colors by
using the sequence `38;2;R:G:B` for foreground colors and `48;2;R:G:B` for
background colors where `R`, `G` and `B` should be replaced with values between
0 and 255.
For convenience, we allow foreground colors to be specified using shorthand,
comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
`38;2;255:0:0`.
{/* prettier-ignore-start */}
[ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
{/* prettier-ignore-end */}

188
website/versioned_docs/version-latest/api_reference.mdx → website/versioned_docs/version-latest/reference/schema.mdx
View File

@ -1,173 +1,11 @@
---
slug: /api/
sidebar_position: 4
slug: /reference/schema
sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 5
---
# API Reference
## CLI
Task command line tool has the following syntax:
```shell
task [--flags] [tasks...] [-- CLI_ARGS...]
```
:::tip
If `--` is given, all remaining arguments will be assigned to a special
`CLI_ARGS` variable
:::
| Short | Flag | Type | Default | Description |
| ----- | --------------------------- | -------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed.<br />`default` - Alphanumeric with root tasks first<br />`alphanumeric` - Alphanumeric<br />`none` - No sorting (As they appear in the Taskfile) |
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| `-y` | `--yes` | `bool` | `false` | Assume "yes" as answer to all prompts. |
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
| | `--summary` | `bool` | `false` | Show summary about a task. |
| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
| | `--version` | `bool` | `false` | Show Task version. |
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. |
## Exit Codes
Task will sometimes exit with specific exit codes. These codes are split into
three groups with the following ranges:
- General errors (0-99)
- Taskfile errors (100-199)
- Task errors (200-299)
A full list of the exit codes and their descriptions can be found below:
| Code | Description |
| ---- | ------------------------------------------------------------ |
| 0 | Success |
| 1 | An unknown error occurred |
| 100 | No Taskfile was found |
| 101 | A Taskfile already exists when trying to initialize one |
| 102 | The Taskfile is invalid or cannot be parsed |
| 103 | A remote Taskfile could not be downloaded |
| 104 | A remote Taskfile was not trusted by the user |
| 105 | A remote Taskfile was could not be fetched securely |
| 106 | No cache was found for a remote Taskfile in offline mode |
| 107 | No schema version was defined in the Taskfile |
| 200 | The specified task could not be found |
| 201 | An error occurred while executing a command inside of a task |
| 202 | The user tried to invoke a task that is internal |
| 203 | There a multiple tasks with the same name or alias |
| 204 | A task was called too many times |
| 205 | A task was cancelled by the user |
| 206 | A task was not executed due to missing required variables |
These codes can also be found in the repository in
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
:::info
When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed
commands will be passed through to the user instead.
:::
## JSON Output
When using the `--json` flag in combination with either the `--list` or
`--list-all` flags, the output will be a JSON object with the following
structure:
```json
{
"tasks": [
{
"name": "",
"desc": "",
"summary": "",
"up_to_date": false,
"location": {
"line": 54,
"column": 3,
"taskfile": "/path/to/Taskfile.yml"
}
}
// ...
],
"location": "/path/to/Taskfile.yml"
}
```
## Special Variables
There are some special variables that is available on the templating system:
| Var | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. |
| `CLI_SILENT` | A boolean containing whether the `--silent` flag was set. |
| `CLI_VERBOSE` | A boolean containing whether the `--verbose` flag was set. |
| `TASK` | The name of the current task. |
| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
| `TASKFILE` | The absolute path of the included Taskfile. |
| `TASKFILE_DIR` | The absolute path of the included Taskfile directory. |
| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
| `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. |
| `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. |
## ENV
Some environment variables can be overridden to adjust Task behavior.
| ENV | Default | Description |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
| `TASK_COLOR_RESET` | `0` | Color used for white. |
| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
| `TASK_COLOR_GREEN` | `32` | Color used for green. |
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
| `TASK_COLOR_RED` | `31` | Color used for red. |
| `FORCE_COLOR` | | Force color output usage. |
All color variables are [ANSI color codes][ansi]. You can specify multiple codes
separated by a semicolon. For example: `31;1` will make the text bold and red.
Task also supports 8-bit color (256 colors). You can specify these colors by
using the sequence `38;2;R:G:B` for foreground colors and `48;2;R:G:B` for
background colors where `R`, `G` and `B` should be replaced with values between
0 and 255.
For convenience, we allow foreground colors to be specified using shorthand,
comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
`38;2;255:0:0`.
## Taskfile Schema
# Schema Reference
| Attribute | Type | Default | Description |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -185,7 +23,7 @@ comma-separated syntax: `R,G,B`. For example, `255,0,0` is equivalent to
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
### Include
## Include
| Attribute | Type | Default | Description |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -208,7 +46,7 @@ includes:
:::
### Variable
## Variable
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
@ -241,7 +79,7 @@ vars:
:::
### Task
## Task
| Attribute | Type | Default | Description |
| --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -291,7 +129,7 @@ tasks:
:::
#### Command
### Command
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -320,7 +158,7 @@ tasks:
:::
#### Dependency
### Dependency
| Attribute | Type | Default | Description |
| --------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
@ -341,7 +179,7 @@ tasks:
:::
#### For
### For
The `for` parameter can be defined as a string, a list of strings or a map. If
it is defined as a string, you can give it any of the following values:
@ -361,7 +199,7 @@ variable to define the values to loop over:
| `split` | `string` | (any whitespace) | What string the variable should be split on. |
| `as` | `string` | `ITEM` | The name of the iterator variable. |
#### Precondition
### Precondition
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
@ -381,12 +219,8 @@ tasks:
:::
#### Requires
### Requires
| Attribute | Type | Default | Description |
| --------- | ---------- | ------- | -------------------------------------------------------------------------------------------------- |
| `vars` | `[]string` | | List of variable or environment variable names that must be set if this task is to execute and run |
{/* prettier-ignore-start */}
[ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code
{/* prettier-ignore-end */}

406
website/versioned_docs/version-latest/reference/templating.mdx Normal file
View File

@ -0,0 +1,406 @@
---
slug: /reference/templating/
sidebar_position: 3
toc_min_heading_level: 2
toc_max_heading_level: 5
---
# Templating Reference
Task's templating engine uses Go's [text/template][text/template] package to
interpolate values. For detailed information about the usage of Go's templating
engine, we recommend reading [the official documentation][text/template].
However, we will provide a basic overview of the main features here.
## Basic Usage
Most string values in Task (though, not all) can be templated. The templating
engine uses double curly braces `{{` and `}}` to denote a template. Anything
inside the curly braces will be executed as a Go template and the result will be
inserted into the resulting string. For example:
```yaml
version: '3'
tasks:
hello:
vars:
MESSAGE: 'Hello, World!'
cmds:
- 'echo {{.MESSAGE}}'
```
In this example, we have a task called `hello` with a single variable, `MESSAGE`
defined. When the command is run, the templating engine will evaluate the
variable and replace `{{.MESSAGE}}` with the variable's contents. This task will
output `Hello, World!` to the terminal. Note that when referring to a variable,
you must use dot notation.
You are also able to do more complex things in templates, such as conditional
logic:
```yaml
version: '3'
tasks:
maybe-happy:
vars:
SMILE: ':\)'
FROWN: ':\('
HAPPY: true
cmds:
- 'echo {{if .HAPPY}}{{.SMILE}}{{else}}{{.FROWN}}{{end}}'
```
```txt
:)
```
...calling functions and piping values:
```yaml
version: '3'
tasks:
uniq:
vars:
NUMBERS: '0,1,1,1,2,2,3'
cmds:
- 'echo {{splitList "," .NUMBERS | uniq | join ", " }}!'
```
```txt
0, 1, 2, 3
```
...looping over values with control flow operators:
```yaml
version: '3'
tasks:
loop:
vars:
NUMBERS: [0, 1, 1, 1, 2, 2, 3]
cmds:
# Ranges over NUMBERS and prints the index and value of each number until it finds a number greater than 1
- "{{range $index, $num := .NUMBERS}}{{if gt $num 1 }}{{break}}{{end}}echo {{$index}}: {{$num}}\n{{end}}"
```
```txt
0: 0
1: 1
2: 1
3: 1
```
## Special Variables
Task defines some special variables that are always available to the templating
engine. If you define a variable with the same name as a special variable, the
special variable will be overridden.
| Var | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. |
| `TASK` | The name of the current task. |
| `TASK_EXE` | The Task executable name or path. |
| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
| `TASKFILE` | The absolute path of the included Taskfile. |
| `TASKFILE_DIR` | The absolute path of the included Taskfile directory. |
| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
| `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. |
| `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. |
## Functions
Functions are provided at a few different levels in Task. Below, we list all the
functions available for use in Task.
:::note
Functions marked with an asterisk (\*) also have `must` variants that will panic
rather than erroring.
:::
### Built-in Functions
The first set of functions are [provided by Golang
itself][go-template-functions]:
| Function | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `and` | Returns the boolean AND of its arguments by returning the first empty argument or the last argument. That is, `and x y` behaves as `if x then y else x`. Evaluation proceeds through the arguments left to right and returns when the result is determined. |
| `call` | Returns the result of calling the first argument, which must be a function, with the remaining arguments as parameters. Thus `call .X.Y 1 2` is, in Go notation, `dot.X.Y(1, 2)` where `Y` is a func-valued field, map entry, or the like. The first argument must be the result of an evaluation that yields a value of function type (as distinct from a predefined function such as print). The function must return either one or two result values, the second of which is of type error. If the arguments don't match the function or the returned error value is non-nil, execution stops. |
| `html` | Returns the escaped HTML equivalent of the textual representation of its arguments. This function is unavailable in [html/template][html/template], with a few exceptions. |
| `index` | Returns the result of indexing its first argument by the following arguments. Thus `index x 1 2 3` is, in Go syntax, `x[1][2][3]`. Each indexed item must be a map, slice, or array. |
| `slice` | slice returns the result of slicing its first argument by the remaining arguments. Thus `slice x 1 2` is, in Go syntax, `x[1:2]`, while `slice x` is `x[:]`, `slice x 1` is `x[1:]`, and `slice x 1 2 3` is `x[1:2:3]`. The first argument must be a string, slice, or array. |
| `js` | Returns the escaped JavaScript equivalent of the textual representation of its arguments. |
| `len` | Returns the integer length of its argument. |
| `not` | Returns the boolean negation of its single argument. |
| `or` | Returns the boolean OR of its arguments by returning the first non-empty argument or the last argument, that is, `or x y` behaves as `if x then x else y`. Evaluation proceeds through the arguments left to right and returns when the result is determined. |
| `print` | An alias for `fmt.Sprint`. |
| `printf` | An alias for `fmt.Sprintf`. |
| `println` | An alias for `fmt.Sprintln`. |
| `urlquery` | Returns the escaped value of the textual representation of its arguments in a form suitable for embedding in a URL query. This function is unavailable in [html/template][html/template], with a few exceptions. |
### Slim-Sprig Functions
In addition to the built-in functions, Task also provides a set of functions
imported via the [slim-sprig][slim-sprig] package. We only provide a very basic
description here for completeness. For detailed usage, please refer to the
[slim-sprig documentation][slim-sprig]:
#### [String Functions][string-functions]
| Function | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `trim` | Removes space from either side of a string. |
| `trimAll` | Removes given characters from the front or back of a string. |
| `trimSuffix` | Trims just the suffix from a string. |
| `trimPrefix` | Trims just the prefix from a string. |
| `upper` | Converts the entire string to uppercase. |
| `lower` | Converts the entire string to lowercase. |
| `title` | Converts to title case. |
| `repeat` | Repeats a string multiple times. |
| `substr` | Gets a substring from a string. |
| `trunc` | Truncates a string. |
| `contains` | Tests to see if one string is contained inside of another. |
| `hasPrefix` | Tests whether a string has a given prefix. |
| `hasSuffix` | Tests whether a string has a given suffix. |
| `quote` | Wraps a string in double quotes. |
| `squote` | Wraps a string in single quotes. |
| `cat` | Concatenates multiple strings together into one, separating them with spaces. |
| `indent` | Indents every line in a given string to the specified indent width. |
| `nindent` | Identical to `indent`, but prepends a new line to the beginning of the string. |
| `replace` | Replaces a string. |
| `plural` | Pluralizes a string. |
| `regexMatch`\* | Returns true if the input string contains any match of the regular expression. |
| `regexFindAll`\* | Returns a slice of all matches of the regular expression in the input string. |
| `regexFind`\* | Returns the first (left most) match of the regular expression in the input string. |
| `regexReplaceAll`\* | Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement. |
| `regexReplaceAllLiteral`\* | Returns a copy of the input string, replacing matches of the Regexp with the replacement string replacement without expanding `$`. |
| `regexSplit`\* | Slices the input string into substrings separated by the expression and returns a slice of the substrings between those expression matches. |
| `regexQuoteMeta`\* | Returns a string that escapes all regular expression metacharacters inside the argument text. |
#### [String Slice Functions][string-list-functions]
| Function | Description |
| ----------- | ----------------------------------------------------------------------- |
| `join` | Joins a list of strings into a single string, with the given separator. |
| `splitList` | Splits a string into a list of strings. |
| `split` | Splits a string into a map of strings where each key is an index. |
| `splitn` | Identical to `split`, but stops splitting after `n` values. |
| `sortAlpha` | Sorts a list of strings into alphabetical (lexicographical) order. |
#### [Integer Functions][math-functions]
| Function | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `add` | Sum a set of numbers. |
| `add1` | Increments a number by 1. |
| `sub` | Subtracts one number from another. |
| `div` | Performs integer division. |
| `mod` | Modulo. |
| `mul` | Multiplies a set of numbers. |
| `max` | Returns the largest of a set of integers. |
| `min` | Returns the smallest of a set of integers. |
| `floor` | Returns the greatest float value less than or equal to input value |
| `ceil` | Returns the greatest float value greater than or equal to input value |
| `round` | Returns a float value with the remainder rounded to the given number to digits after the decimal point. |
| `randInt` | Returns a random integer value from min (inclusive) to max (exclusive). |
#### [Integer Slice Functions][integer-list-functions]
| Function | Description |
| ----------- | --------------------------------------------------------------------------- |
| `until` | Builds a range of integers. |
| `untilStep` | Builds a range of integers, but allows you to define a start, stop and step |
| `seq` | Works like the bash `seq` command. |
#### [Date Functions][date-functions]
| Function | Description |
| ---------------- | ------------------------------------------------------------------------------ |
| `now` | Gets the current date/time. |
| `ago` | Returns the duration since the given date/time. |
| `date` | Formats a date. |
| `dateInZone` | Identical to `date`, but with the given timezone. |
| `duration` | Formats the number of seconds into a string. |
| `durationRound` | Identical to `duration`, but rounds the duration to the most significant unit. |
| `unixEpoch` | Returns the seconds since the unix epoch for the given date/time. |
| `dateModify`\* | Modifies a date using the given input string. |
| `htmlDate` | Formats a date for inserting into an HTML date picker input field. |
| `htmlDateInZone` | Identical to `htmlDate`, but with the given timezone. |
| `toDate`\* | Converts a string to a date/time. |
#### [Default Functions][default-functions]
| Function | Description |
| ---------- | ------------------------------------------------------------------------ |
| `default` | Uses a default value if the given value is considered "zero" or "empty". |
| `empty` | Returns true if a value is considered "zero" or "empty". |
| `coalesce` | Takes a list of values and returns the first non-empty one. |
| `all` | Returns true if all values are non-empty. |
| `any` | Returns true if any value is non-empty. |
| `ternary` | The ternary function takes two values, and a test value. If the test value is true, the first value will be returned. If the test value is empty, the second value will be returned. |
#### [Encoding Functions][encoding-functions]
| Function | Description |
| ---------------- | ------------------------------------------------------------------ |
| `fromJson`\* | Decodes a JSON string into an object. |
| `toJson`\* | Encodes an object as a JSON string. |
| `toPrettyJson`\* | Encodes an object as a JSON string with new lines and indentation. |
| `toRawJson`\* | Encodes an object as a JSON string with HTML characters unescaped. |
| `b64enc` | Encodes a string into base 64. |
| `b64dec` | Decodes a string from base 64. |
| `b32enc` | Encodes a string into base 32. |
| `b32dec` | Decodes a string from base 32. |
#### [List Functions][list-functions]
| Function | Description |
| ----------- | ---------------------------------------------------------------- |
| `list` | Creates a list from a set of values. |
| `first`\* | Gets the first value in a list. |
| `rest`\* | Gets all values except the first value in the list. |
| `last`\* | Gets the last value in the list. |
| `initial`\* | Get all values except the last value in the list. |
| `append`\* | Adds a new value to the end of the list. |
| `prepend`\* | Adds a new value to the start of the list. |
| `concat` | Joins two or more lists together. |
| `reverse`\* | Reverses the order of a list. |
| `uniq`\* | Generate a list with all of the duplicates removed. |
| `without`\* | Filters matching items out of a list. |
| `has`\* | Tests to see if a list has a particular element. |
| `compact`\* | Removes entries with empty values. |
| `slice`\* | Returns a partial copy of a list given start and end parameters. |
| `chunk` | Splits a list into chunks of given size. |
#### [Dictionary Functions][dictionary-functions]
| Function | Description |
| ------------------ | ------------------------------------------------------------------------------------------ |
| `dict` | Creates a dictionary from a set of key/value pairs. |
| `get` | Gets the value from the dictionary with the given key. |
| `set` | Adds a new key/value pair to a dictionary. |
| `unset` | Deletes a key from a dictionary. |
| `hasKey` | Returns true if a dictionary contains the given key. |
| `pluck` | Gets a list of all of the matching values in a set of maps given a key. |
| `dig` | Returns the value in a nested map given a path of keys. |
| `merge`\* | Merges two or more dictionaries into one. |
| `mergeOverwrite`\* | Identical to `merge`, but giving precedence from right to left. |
| `keys` | Returns a list of all of the keys in a dictionary. |
| `pick` | Creates a new dictionary containing only the given keys of an existing map. |
| `omit` | Creates a new dictionary containing all the keys of an existing map except the ones given. |
| `values` | Returns a list of all the values in a dictionary. |
#### [Type Conversion Functions][type-conversion-functions]
| Function | Description |
| ----------- | ------------------------------------------------------ |
| `atoi` | Converts a string to an integer. |
| `float64` | Converts to a float64. |
| `int` | Converts to an int at the system's width. |
| `int64` | Converts to an int64. |
| `toDecimal` | Converts a unix octal to a int64. |
| `toString` | Converts to a string. |
| `toStrings` | Converts a list, slice, or array to a list of strings. |
| `toStrings` | Produces a slice of strings from any list. |
| `toDecimal` | Given a unix octal permission, produce a decimal. |
#### [Path and Filepath Functions][path-functions]
| Function | Description |
| --------- | ----------------------------------------- |
| `base` | Returns the last element of a path. |
| `dir` | Returns the directory of a path. |
| `clean` | Cleans up a path. |
| `ext` | Returns the file extension of a path. |
| `isAbs` | Checks if a path is absolute. |
| `osBase` | Returns the last element of a filepath. |
| `osDir` | Returns the directory of a filepath. |
| `osClean` | Cleans up a filepath. |
| `osExt` | Returns the file extension of a filepath. |
| `osIsAbs` | Checks if a filepath is absolute. |
#### [Flow Control Functions][flow-control-functions]
| Function | Description |
| -------- | ----------------------------------------------------------------------------- |
| `fail` | Unconditionally returns an empty string and an error with the specified text. |
#### [OS Functions][os-functions]
| Function | Description |
| ----------- | --------------------------------------------- |
| `env` | Reads an environment variable. |
| `expandenv` | Substitutes environment variables in a string |
#### [Reflection Functions][reflection-functions]
| Function | Description |
| ------------ | ------------------------------------------------------ |
| `kindOf` | Returns the kind of a value. |
| `kindIs` | Verifies that a value is a particular kind. |
| `typeOf` | Returns the underlying type of a value. |
| `typeIs` | Verifies that a value is of a particular type. |
| `typeIsLike` | Identical to `typeIs`, but also dereferences pointers. |
| `deepEqual` | Returns true if two values are "deeply equal". |
#### [Cryptographic and Security Functions][crypto-functions]
| Function | Description |
| ------------ | -------------------------------------- |
| `sha1sum` | Computes a string's SHA1 digest. |
| `sha256sum` | Computes a string's SHA256 digest. |
| `adler32sum` | Computes a string's Adler-32 checksum. |
### Task Functions
Lastly, Task itself provides a few functions:
| Function | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OS` | Returns the operating system. Possible values are `windows`, `linux`, `darwin` (macOS) and `freebsd`. |
| `ARCH` | return the architecture Task was compiled to: `386`, `amd64`, `arm` or `s390x`. |
| `splitLines` | Splits Unix (`\n`) and Windows (`\r\n`) styled newlines. |
| `catLines` | Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a space. |
| `toSlash` | Does nothing on Unix, but on Windows converts a string from `\` path format to `/`. |
| `fromSlash` | Opposite of `toSlash`. Does nothing on Unix, but on Windows converts a string from `/` path format to `\`. |
| `exeExt` | Returns the right executable extension for the current OS (`".exe"` for Windows, `""` for others). |
| `shellQuote` | (aliased to `q`): Quotes a string to make it safe for use in shell scripts. Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote) for this. The Bash dialect is assumed. |
| `splitArgs` | Splits a string as if it were a command's arguments. Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields). |
| `joinPath` | Joins any number of arguments into a path. The same as Go's [filepath.Join](https://pkg.go.dev/path/filepath#Join). |
| `relPath` | Converts an absolute path (second argument) into a relative path, based on a base path (first argument). The same as Go's [filepath.Rel](https://pkg.go.dev/path/filepath#Rel). |
| `merge` | Creates a new map that is a copy of the first map with the keys of each subsequent map merged into it. If there is a duplicate key, the value of the last map with that key is used. |
| `spew` | Returns the Go representation of a specific variable. Useful for debugging. Uses the [davecgh/go-spew](https://github.com/davecgh/go-spew) package. |
{/* prettier-ignore-start */}
[text/template]: https://pkg.go.dev/text/template
[html/template]: https://pkg.go.dev/html/template
[go-template-functions]: https://pkg.go.dev/text/template#hdr-Functions
[slim-sprig]: https://go-task.github.io/slim-sprig/
[os-functions]: https://go-task.github.io/slim-sprig/os.html
[string-functions]: https://go-task.github.io/slim-sprig/strings.html
[string-list-functions]: https://go-task.github.io/slim-sprig/string_slice.html
[math-functions]: https://go-task.github.io/slim-sprig/math.html
[integer-list-functions]: https://go-task.github.io/slim-sprig/integer_slice.html
[date-functions]: https://go-task.github.io/slim-sprig/date.html
[default-functions]: https://go-task.github.io/slim-sprig/defaults.html
[encoding-functions]: https://go-task.github.io/slim-sprig/encoding.html
[list-functions]: https://go-task.github.io/slim-sprig/lists.html
[dictionary-functions]: https://go-task.github.io/slim-sprig/dicts.html
[type-conversion-functions]: https://go-task.github.io/slim-sprig/conversion.html
[path-functions]: https://go-task.github.io/slim-sprig/paths.html
[flow-control-functions]: https://go-task.github.io/slim-sprig/flow_control.html
[os-functions]: https://go-task.github.io/slim-sprig/os.html
[reflection-functions]: https://go-task.github.io/slim-sprig/reflection.html
[crypto-functions]: https://go-task.github.io/slim-sprig/crypto.html
{/* prettier-ignore-end */}

279
website/versioned_docs/version-latest/taskfile_versions.mdx
View File

@ -5,259 +5,68 @@ sidebar_position: 5
# Taskfile Versions
The Taskfile syntax and features changed with time. This document explains what
changed on each version and how to upgrade your Taskfile.
The Taskfile schema slowly changes as new features are added and old ones are
removed. This document explains how to use a Taskfile's schema version to ensure
that the users of your Taskfile are using the correct versions of Task.
## What the Taskfile version mean
## What the Taskfile version means
The Taskfile version follows the Task version. E.g. the change to Taskfile
version `2` means that Task `v2.0.0` should be release to support it.
The `version:` key on Taskfile accepts a semver string, so either `2`, `2.0` or
`2.0.0` is accepted. If you choose to use `2.0` Task will not enable future
`2.1` features, but if you choose to use `2`, then any `2.x.x` features will be
available, but not `3.0.0+`.
## Version 3 ![latest](https://img.shields.io/badge/latest-brightgreen)
These are some major changes done on `v3`:
- Task's output will now be colored
- Added support for `.env` like files
- Added `label:` setting to task so one can override how the task name appear in
the logs
- A global `method:` was added to allow setting the default method, and Task's
default changed to `checksum`
- Two magic variables were added when using `status:`: `CHECKSUM` and
`TIMESTAMP` which contains, respectively, the XXH3 checksum and greatest
modification timestamp of the files listed on `sources:`
- Also, the `TASK` variable is always available with the current task name
- CLI variables are always treated as global variables
- Added `dir:` option to `includes` to allow choosing on which directory an
included Taskfile will run:
The schema version at the top of every Taskfile corresponds to a version of the
Task CLI, and by extension, the features that are provided by that version. When
creating a Taskfile, you should specify the _minimum_ version of Task that
supports the features you require. If you try to run a Taskfile with a version
of Task that does not meet this minimum required version, it will exit with an
error. For example, given a Taskfile that starts with:
```yaml
includes:
docs:
taskfile: ./docs
dir: ./docs
version: '3.2.1'
```
- Implemented short task syntax. All below syntaxes are equivalent:
When executed with Task `v3.2.0`, it will exit with an error. Running with
version `v3.2.1` or higher will work as expected.
Task accepts any [SemVer][semver] compatible string including versions which
omit the minor or patch numbers. For example, `3`, `3.0`, and `3.0.0` all mean
the same thing and are all valid. Most Taskfiles only specify the major version
number. However it can be useful to be more specific when you intend to share a
Taskfile with others.
For example, the Taskfile below makes use of aliases:
```yaml
version: '3'
tasks:
print:
hello:
aliases:
- hi
- hey
cmds:
- echo "Hello, World!"
- echo "Hello, world!"
```
Aliases were introduced in Task `v3.17.0`, but the Taskfile only specifies `3`
as the version. This means that a user who has `v3.16.0` or lower installed will
get a potentially confusing error message when trying to run the Task as the
Taskfile specifies that any version greater or equal to `v3.0.0` is fine.
Instead, we should start the file like this:
```yaml
version: '3'
tasks:
print:
- echo "Hello, World!"
version: '3.17'
```
```yaml
version: '3'
Now when someone tries to run the Taskfile with an older version of Task, they
will receive an error prompting them to upgrade their version of Task to
`v3.17.0` or greater.
tasks:
print: echo "Hello, World!"
```
## Versions 1 & 2
- There was a major refactor on how variables are handled. They're now easier to
understand. The `expansions:` setting was removed as it became unnecessary.
This is the order in which Task will process variables, each level can see the
variables set by the previous one and override those.
- Environment variables
- Global + CLI variables
- Call variables
- Task variables
Version 1 and 2 of Task are no longer officially supported and anyone still
using them is strongly encouraged to upgrade to the latest version of Task.
## Version 2.6
While `version: 2` of Task did support schema versions, the behavior did not
work in quite the same way and cannot be relied upon for the purposes discussed
above.
:::caution
v2 schemas are [no longer supported by the latest version of
Task][deprecate-version-2-schema].
:::
Version 2.6 comes with `preconditions` stanza in tasks.
```yaml
version: '2'
tasks:
upload_environment:
preconditions:
- test -f .env
cmds:
- aws s3 cp .env s3://myenvironment
```
Please check the [documentation][includes]
## Version 2.2
:::caution
v2 schemas are [no longer supported by the latest version of
Task][deprecate-version-2-schema].
:::
Version 2.2 comes with a global `includes` options to include other Taskfiles:
```yaml
version: '2'
includes:
docs: ./documentation # will look for ./documentation/Taskfile.yml
docker: ./DockerTasks.yml
```
## Version 2.1
:::caution
v2 schemas are [no longer supported by the latest version of
Task][deprecate-version-2-schema].
:::
Version 2.1 includes a global `output` option, to allow having more control over
how commands output are printed to the console (see [documentation][output] for
more info):
```yaml
version: '2'
output: prefixed
tasks:
server:
cmds:
- go run main.go
prefix: server
```
From this version it's also possible to ignore errors of a command or task
(check documentation [here][ignore_errors]):
```yaml
version: '2'
tasks:
example-1:
cmds:
- cmd: exit 1
ignore_error: true
- echo "This will be print"
example-2:
cmds:
- exit 1
- echo "This will be print"
ignore_error: true
```
## Version 2.0
:::caution
v2 schemas are [no longer supported by the latest version of
Task][deprecate-version-2-schema].
:::
At version 2, we introduced the `version:` key, to allow us to evolve Task with
new features without breaking existing Taskfiles. The new syntax is as follows:
```yaml
version: '2'
tasks:
echo:
cmds:
- echo "Hello, World!"
```
Version 2 allows you to write global variables directly in the Taskfile, if you
don't want to create a `Taskvars.yml`:
```yaml
version: '2'
vars:
GREETING: Hello, World!
tasks:
greet:
cmds:
- echo "{{.GREETING}}"
```
The variable priority order changed to the following:
1. Task variables
2. Call variables
3. Taskfile variables
4. Taskvars file variables
5. Environment variables
A new global option was added to configure the number of variables expansions
(which default to 2):
```yaml
version: '2'
expansions: 3
vars:
FOO: foo
BAR: bar
BAZ: baz
FOOBAR: '{{.FOO}}{{.BAR}}'
FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
tasks:
default:
cmds:
- echo "{{.FOOBARBAZ}}"
```
## Version 1
:::caution
v1 schema support was removed in Task >= v3.0.0.
:::
In the first version of the `Taskfile`, the `version:` key was not available,
because the tasks was in the root of the YAML document. Like this:
```yaml
echo:
cmds:
- echo "Hello, World!"
```
The variable priority order was also different:
1. Call variables
2. Environment
3. Task variables
4. `Taskvars.yml` variables
{/* prettier-ignore-start */}
[deprecate-version-2-schema]: ./deprecations/version_2_schema.mdx
[output]: ./usage.mdx#output-syntax
[ignore_errors]: ./usage.mdx#ignore-errors
[includes]: ./usage.mdx#including-other-taskfiles
{/* prettier-ignore-end */}
[semver]: https://semver.org/

221
website/versioned_docs/version-latest/usage.mdx
View File

@ -3,6 +3,9 @@ slug: /usage/
sidebar_position: 3
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Usage
## Getting started
@ -964,10 +967,48 @@ Maps are not supported by default, but there is an
you're interested in this functionality, we would appreciate your feedback.
:pray:
In the meantime, it is technically possible to define a map using a `ref` resolver and a templating function. For example:
```yaml
version: '3'
tasks:
task-with-map:
vars:
FOO:
ref: dict "a" "1" "b" "2" "c" "3"
cmds:
- echo {{.FOO}}
```
```txt
map[a:1 b:2 c:3]
```
OR by using the same technique with JSON:
```yaml
version: '3'
tasks:
task-with-map:
vars:
JSON: '{"a": 1, "b": 2, "c": 3}'
FOO:
ref: "fromJson .JSON"
cmds:
- echo {{.FOO}}
```
```txt
map[a:1 b:2 c:3]
```
:::
Variables can be set in many places in a Taskfile. When executing templates,
Task will look for variables in the order listed below (most important first):
Variables can be set in many places in a Taskfile. When executing
[templates][templating-reference], Task will look for variables in the order
listed below (most important first):
- Variables declared in the task definition
- Variables given while calling a task from another (See
@ -1046,6 +1087,103 @@ tasks:
This works for all types of variables.
### Referencing other variables
Templating is great for referencing string values if you want to pass
a value from one task to another. However, the templating engine is only able to
output strings. If you want to pass something other than a string to another
task then you will need to use a reference (`ref`) instead.
<Tabs defaultValue="2"
values={[
{ label: 'Templating Engine', value: '1' },
{ label: 'Reference', value: '2' }
]}>
<TabItem value="1">
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO: '{{.FOO}}' # <-- FOO gets converted to a string when passed to bar
bar:
cmds:
- 'echo {{index .FOO 0}}' # <-- FOO is a string so the task outputs '91' which is the ASCII code for '[' instead of the expected 'A'
```
</TabItem>
<TabItem value="2">
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO:
ref: .FOO # <-- FOO gets passed by reference to bar and maintains its type
bar:
cmds:
- 'echo {{index .FOO 0}}' # <-- FOO is still a map so the task outputs 'A' as expected
```
</TabItem></Tabs>
This also works the same way when calling `deps` and when defining
a variable and can be used in any combination:
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
BAR:
ref: .FOO # <-- BAR is defined as a reference to FOO
deps:
- task: bar
vars:
BAR:
ref: .BAR # <-- BAR gets passed by reference to bar and maintains its type
bar:
cmds:
- 'echo {{index .BAR 0}}' # <-- BAR still refers to FOO so the task outputs 'A'
```
All references use the same templating syntax as regular templates, so in
addition to simply calling `.FOO`, you can also pass subkeys (`.FOO.BAR`) or
indexes (`index .FOO 0`) and use functions (`len .FOO`) as described in the
[templating-reference][templating-reference]:
```yaml
version: 3
tasks:
foo:
vars:
FOO: [A, B, C] # <-- FOO is defined as an array
cmds:
- task: bar
vars:
FOO:
ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar
bar:
cmds:
- 'echo {{.MYVAR}}' # <-- FOO is just the letter 'A'
```
## Looping over values
As of v3.28.0, Task allows you to loop over certain values and execute a command
@ -1142,8 +1280,7 @@ tasks:
cmd: cat {{.ITEM}}
```
You can also loop over arrays directly (and maps if you have the
[maps experiment](/experiments/map-variables) enabled):
You can also loop over arrays directly and maps:
```yaml
version: 3
@ -1383,81 +1520,6 @@ commands are executed in the reverse order if you schedule multiple of them.
:::
## Go's template engine
Task parse commands as [Go's template engine][gotemplate] before executing them.
Variables are accessible through dot syntax (`.VARNAME`).
All functions by the Go's
[slim-sprig lib](https://go-task.github.io/slim-sprig/) are available. The
following example gets the current date in a given format:
```yaml
version: '3'
tasks:
print-date:
cmds:
- echo {{now | date "2006-01-02"}}
```
Task also adds the following functions:
- `OS`: Returns the operating system. Possible values are `windows`, `linux`,
`darwin` (macOS) and `freebsd`.
- `ARCH`: return the architecture Task was compiled to: `386`, `amd64`, `arm` or
`s390x`.
- `splitLines`: Splits Unix (`\n`) and Windows (`\r\n`) styled newlines.
- `catLines`: Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a
space.
- `toSlash`: Does nothing on Unix, but on Windows converts a string from `\`
path format to `/`.
- `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows
converts a string from `/` path format to `\`.
- `exeExt`: Returns the right executable extension for the current OS (`".exe"`
for Windows, `""` for others).
- `shellQuote` (aliased to `q`): Quotes a string to make it safe for use in shell scripts. Task
uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote)
for this. The Bash dialect is assumed.
- `splitArgs`: Splits a string as if it were a command's arguments. Task uses
[this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields)
- `joinPath`: Joins any number of arguments into a path. The same as Go's
[filepath.Join](https://pkg.go.dev/path/filepath#Join).
- `relPath`: Converts an absolute path (second argument) into a relative path,
based on a base path (first argument). The same as Go's
[filepath.Rel](https://pkg.go.dev/path/filepath#Rel).
- `merge`: Creates a new map that is a copy of the first map with the keys of
each subsequent map merged into it. If there is a duplicate key, the value of
the last map with that key is used.
- `spew`: Returns the Go representation of a specific variable. Useful for
debugging. Uses the [davecgh/go-spew](https://github.com/davecgh/go-spew)
package.
Example:
```yaml
version: '3'
tasks:
print-os:
cmds:
- echo '{{OS}} {{ARCH}}'
- echo '{{if eq OS "windows"}}windows-command{{else}}unix-command{{end}}'
# This will be path/to/file on Unix but path\to\file on Windows
- echo '{{fromSlash "path/to/file"}}'
enumerated-file:
vars:
CONTENT: |
foo
bar
cmds:
- |
cat << EOF > output.txt
{{range $i, $line := .CONTENT | splitLines -}}
{{printf "%3d" $i}}: {{$line}}
{{end}}EOF
```
## Help
Running `task --list` (or `task -l`) lists all tasks with a description. The
@ -1996,4 +2058,5 @@ if called by another task, either directly or as a dependency.
{/* prettier-ignore-start */}
[gotemplate]: https://golang.org/pkg/text/template/
[map-variables]: ./experiments/map_variables.mdx
[templating-reference]: ./reference/templating.mdx
{/* prettier-ignore-end */}