go/task
go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2024-12-12 10:45:49 +02:00
Code Issues Releases Activity

docs: template reference (#1653)

Browse Source 
* chore: deprecation warnings for template functions

* docs: update reference pages
This commit is contained in:
Pete Davison 2024-05-16 11:11:52 +01:00 committed by GitHub
parent 30e9c7d4cd
commit b0efbad591
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 601 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
website/docs/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` |

2
website/docs/reference/_category_.yml Normal file
View File

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

118
website/docs/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 `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"
}
```

37
website/docs/reference/environment.mdx Normal file
View File

@ -0,0 +1,37 @@
---
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`. |
| `FORCE_COLOR` | | Force color output usage. |
## Custom Colors
| ENV | Default | Description |
| -------------------- | ------- | ----------------------- |
| `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. |
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`.

183
website/docs/api_reference.mdx → website/docs/reference/schema.mdx
View File

@ -1,172 +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. |
| `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:`. |
## 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 |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -184,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 |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -207,7 +46,7 @@ includes:
:::
### Variable
## Variable
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
@ -240,7 +79,7 @@ vars:
:::
### Task
## Task
| Attribute | Type | Default | Description |
| --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -290,7 +129,7 @@ tasks:
:::
#### Command
### Command
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@ -319,7 +158,7 @@ tasks:
:::
#### Dependency
### Dependency
| Attribute | Type | Default | Description |
| --------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
@ -340,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:
@ -360,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 |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
@ -380,7 +219,7 @@ tasks:
:::
#### Requires
### Requires
| Attribute | Type | Default | Description |
| --------- | ---------- | ------- | -------------------------------------------------------------------------------------------------- |

406
website/docs/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 astrix (\*) 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
descroption 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` | |
#### [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 indentarion. |
| `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 extention 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 extention 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 */}

81
website/docs/usage.mdx
View File

@ -966,8 +966,9 @@ you're interested in this functionality, we would appreciate your feedback.
:::
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
@ -1383,81 +1384,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 +1922,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 */}