go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-12-01 22:52:02 +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
7 changed files with 601 additions and 249 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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`.

230
website/docs/reference/schema.mdx Normal file
View File

@@ -0,0 +1,230 @@
---
slug: /reference/schema
sidebar_position: 2
toc_min_heading_level: 2
toc_max_heading_level: 5
---
# Schema Reference
| Attribute | Type | Default | Description |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `string` | | Version of the Taskfile. The current version is `3`. |
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overridden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
| `vars` | [`map[string]Variable`](#variable) | | A set of global variables. |
| `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. |
| `tasks` | [`map[string]Task`](#task) | | A set of task definitions. |
| `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overridden with `true` in a task by task basis. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `run` | `string` | `always` | Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`. |
| `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). |
| `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
| Attribute | Type | Default | Description |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. |
| `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
| `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
| `internal` | `bool` | `false` | Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`. |
| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |
:::info
Informing only a string like below is equivalent to setting that value to the
`taskfile` attribute.
```yaml
includes:
foo: ./path
```
:::
## Variable
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
| _itself_ | `string` | | A static value that will be set to the variable. |
| `sh` | `string` | | A shell command. The output (`STDOUT`) will be assigned to the variable. |
:::info
Static and dynamic variables have different syntaxes, like below:
```yaml
vars:
STATIC: static
DYNAMIC:
sh: echo "dynamic"
```
:::
:::info
In a variables map, variables defined later may reference variables defined
earlier (declaration order is respected):
```yaml
vars:
FIRST_VAR: "hello"
SECOND_VAR: "{{.FIRST_VAR}} world"
```
:::
## Task
| Attribute | Type | Default | Description |
| --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmds` | [`[]Command`](#command) | | A list of shell commands to be executed. |
| `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. |
| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. |
| `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. |
| `prompt` | `string` | | A prompt that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks. |
| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. |
| `aliases` | `[]string` | | A list of alternative names by which the task can be called. |
| `sources` | `[]string` | | A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. |
| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
| `requires` | [`Requires`](#requires) | | A list of required variables which should be set if this task is to run, if any variables listed are unset the task will error and not run. |
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. |
| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. |
| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `silent` | `bool` | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden. |
| `interactive` | `bool` | `false` | Tells task that the command is interactive. |
| `internal` | `bool` | `false` | Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`. |
| `method` | `string` | `checksum` | Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task. |
| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. |
| `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Task will be skipped otherwise. |
| `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). |
:::info
These alternative syntaxes are available. They will set the given values to
`cmds` and everything else will be set to their default values:
```yaml
tasks:
foo: echo "foo"
foobar:
- echo "foo"
- echo "bar"
baz:
cmd: echo "baz"
```
:::
### Command
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmd` | `string` | | The shell command to be executed. |
| `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. |
| `for` | [`For`](#for) | | Runs the command once for each given value. |
| `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. |
| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Command will be skipped otherwise. |
| `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). |
:::info
If given as a a string, the value will be assigned to `cmd`:
```yaml
tasks:
foo:
cmds:
- echo "foo"
- echo "bar"
```
:::
### Dependency
| Attribute | Type | Default | Description |
| --------- | ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `task` | `string` | | The task to be execute as a dependency. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to this task. |
| `silent` | `bool` | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. |
:::tip
If you don't want to set additional variables, it's enough to declare the
dependency as a list of strings (they will be assigned to `task`):
```yaml
tasks:
foo:
deps: [foo, bar]
```
:::
### 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:
- `source` - Will run the command for each source file defined on the task.
(Glob patterns will be resolved, so `*.go` will run for every Go file that
matches).
If it is defined as a list of strings, the command will be run for each value.
Finally, the `for` parameter can be defined as a map when you want to use a
variable to define the values to loop over:
| Attribute | Type | Default | Description |
| --------- | -------- | ---------------- | -------------------------------------------- |
| `var` | `string` | | The name of the variable to use as an input. |
| `split` | `string` | (any whitespace) | What string the variable should be split on. |
| `as` | `string` | `ITEM` | The name of the iterator variable. |
### Precondition
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `sh` | `string` | | Command to be executed. If a non-zero exit code is returned, the task errors without executing its commands. |
| `msg` | `string` | | Optional message to print if the precondition isn't met. |
:::tip
If you don't want to set a different message, you can declare a precondition
like this and the value will be assigned to `sh`:
```yaml
tasks:
foo:
precondition: test -f Taskfile.yml
```
:::
### 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/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 */}