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

feat: add "latest" version

Browse Source
This commit is contained in:
Pete Davison 2024-03-03 19:57:46 +00:00
parent 96f13e5f2c
commit d2e26e2328
25 changed files with 5313 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
docs/docusaurus.config.ts
View File

@ -92,7 +92,19 @@ const config: Config = {
docs: {
routeBasePath: '/',
sidebarPath: './sidebars.ts',
remarkPlugins: [remarkGithub, remarkGfm]
remarkPlugins: [remarkGithub, remarkGfm],
includeCurrentVersion: true,
versions: {
current: {
label: `Next 🚧`,
path: 'next',
badge: false
},
latest: {
label: 'Latest',
badge: false
}
}
},
blog: {},
theme: {
@ -174,6 +186,11 @@ const config: Config = {
}
]
},
{
type: 'docsVersionDropdown',
position: 'right',
dropdownActiveClassDisabled: true,
},
{
href: GITHUB_URL,
label: 'GitHub',

374
docs/versioned_docs/version-latest/api_reference.md Normal file
View File

@ -0,0 +1,374 @@
---
slug: /api/
sidebar_position: 4
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. |
| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
| `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. |
## Taskfile Schema
| 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/main/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/main/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 |

841
docs/versioned_docs/version-latest/changelog.md Normal file
View File

@ -0,0 +1,841 @@
---
slug: /changelog/
sidebar_position: 14
---
# Changelog
## v3.34.1 - 2024-01-27
- Fixed prompt regression on
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles/)
(#1486, #1487 by @pd93).
## v3.34.0 - 2024-01-25
- Removed support for `version: 2` schemas. See the
[deprecation notice on our website](https://taskfile.dev/deprecations/version-2-schema)
(#1197, #1447 by @pd93).
- Fixed a couple of issues in the JSON Schema + added a CI step to ensure it's
correct (#1471, #1474, #1476 by @sirosen).
- Added
[Any Variables experiment proposal 2](https://taskfile.dev/experiments/any-variables/?proposal=2)
(#1415, #1444 by @pd93).
- Updated the experiments and deprecations documentation format (#1445 by
@pd93).
- Added new template function: `spew`, which can be used to print variables for
debugging purposes (#1452 by @pd93).
- Added new template function: `merge`, which can be used to merge any number of
map variables (#1438, #1464 by @pd93).
- Small change on the API when using as a library: `call.Direct` became
`call.Indirect` (#1459 by @pd93).
- Refactored the public `read` and `taskfile` packages and introduced
`taskfile/ast` (#1450 by @pd93).
- `ast.IncludedTaskfiles` renamed to `ast.Includes` and `orderedmap` package
renamed to `omap` plus some internal refactor work (#1456 by @pd93).
- Fix zsh completion script to allow lowercase `taskfile` file names (#1482 by
@xontab).
- Improvements on how we check the Taskfile version (#1465 by @pd93).
- Added a new `ROOT_TASKFILE` special variable (#1468, #1469 by @pd93).
- Fix experiment flags in `.env` when the `--dir` or `--taskfile` flags were
used (#1478 by @pd93).
## v3.33.1 - 2023-12-21
- Added support for looping over map variables with the
[Any Variables experiment](https://taskfile.dev/experiments/any-variables)
enabled (#1435, #1437 by @pd93).
- Fixed a bug where dynamic variables were causing errors during fast
compilation (#1435, #1437 by @pd93)
## v3.33.0 - 2023-12-20
- Added
[Any Variables experiment](https://taskfile.dev/experiments/any-variables)
(#1415, #1421 by @pd93).
- Updated Docusaurus to v3 (#1432 by @pd93).
- Added `aliases` to `--json` flag output (#1430, #1431 by @pd93).
- Added new `CLI_FORCE` special variable containing whether the `--force` or
`--force-all` flags were set (#1412, #1434 by @pd93).
## v3.32.0 - 2023-11-29
- Added ability to exclude some files from `sources:` by using `exclude:` (#225,
#1324 by @pd93 and @andreynering).
- The
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles)
now prefers remote files over cached ones by default (#1317, #1345 by @pd93).
- Added `--timeout` flag to the
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles)
(#1317, #1345 by @pd93).
- Fix bug where dynamic `vars:` and `env:` were being executed when they should
actually be skipped by `platforms:` (#1273, #1377 by @andreynering).
- Fix `schema.json` to make `silent` valid in `cmds` that use `for` (#1385,
#1386 by @iainvm).
- Add new `--no-status` flag to skip expensive status checks when running
`task --list --json` (#1348, #1368 by @amancevice).
## v3.31.0 - 2023-10-07
- Enabled the `--yes` flag for the
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles)
(#1317, #1344 by @pd93).
- Add ability to set `watch: true` in a task to automatically run it in watch
mode (#231, #1361 by @andreynering).
- Fixed a bug on the watch mode where paths that contained `.git` (like
`.github`), for example, were also being ignored (#1356 by @butuzov).
- Fixed a nil pointer error when running a Taskfile with no contents (#1341,
#1342 by @pd93).
- Added a new [exit code](https://taskfile.dev/api/#exit-codes) (107) for when a
Taskfile does not contain a schema version (#1342 by @pd93).
- Increased limit of maximum task calls from 100 to 1000 for now, as some people
have been reaching this limit organically now that we have loops. This check
exists to detect recursive calls, but will be removed in favor of a better
algorithm soon (#1321, #1332).
- Fixed templating on descriptions on `task --list` (#1343 by @blackjid).
- Fixed a bug where precondition errors were incorrectly being printed when task
execution was aborted (#1337, #1338 by @sylv-io).
## v3.30.1 - 2023-09-14
- Fixed a regression where some special variables weren't being set correctly
(#1331, #1334 by @pd93).
## v3.30.0 - 2023-09-13
- Prep work for Remote Taskfiles (#1316 by @pd93).
- Added the
[Remote Taskfiles experiment](https://taskfile.dev/experiments/remote-taskfiles)
as a draft (#1152, #1317 by @pd93).
- Improve performance of content checksuming on `sources:` by replacing md5 with
[XXH3](https://xxhash.com/) which is much faster. This is a soft breaking
change because checksums will be invalidated when upgrading to this release
(#1325 by @ReillyBrogan).
## v3.29.1 - 2023-08-26
- Update to Go 1.21 (bump minimum version to 1.20) (#1302 by @pd93)
- Fix a missing a line break on log when using `--watch` mode (#1285, #1297 by
@FilipSolich).
- Fix `defer` on JSON Schema (#1288 by @calvinmclean and @andreynering).
- Fix bug in usage of special variables like `{{.USER_WORKING_DIR}}` in
combination with `includes` (#1046, #1205, #1250, #1293, #1312, #1274 by
@andarto, #1309 by @andreynering).
- Fix bug on `--status` flag. Running this flag should not have side-effects: it
should not update the checksum on `.task`, only report its status (#1305,
#1307 by @visciang, #1313 by @andreynering).
## v3.28.0 - 2023-07-24
- Added the ability to
[loop over commands and tasks](https://taskfile.dev/usage/#looping-over-values)
using `for` (#82, #1220 by @pd93).
- Fixed variable propagation in multi-level includes (#778, #996, #1256 by
@hudclark).
- Fixed a bug where the `--exit-code` code flag was not returning the correct
exit code when calling commands indirectly (#1266, #1270 by @pd93).
- Fixed a `nil` panic when a dependency was commented out or left empty (#1263
by @neomantra).
## v3.27.1 - 2023-06-30
- Fix panic when a `.env` directory (not file) is present on current directory
(#1244, #1245 by @pd93).
## v3.27.0 - 2023-06-29
- Allow Taskfiles starting with lowercase characters (#947, #1221 by @pd93).
- e.g. `taskfile.yml`, `taskfile.yaml`, `taskfile.dist.yml` &
`taskfile.dist.yaml`
- Bug fixes were made to the
[npm installation method](https://taskfile.dev/installation/#npm). (#1190, by
@sounisi5011).
- Added the
[gentle force experiment](https://taskfile.dev/experiments/gentle-force) as a
draft (#1200, #1216 by @pd93).
- Added an `--experiments` flag to allow you to see which experiments are
enabled (#1242 by @pd93).
- Added ability to specify which variables are required in a task (#1203, #1204
by @benc-uk).
## v3.26.0 - 2023-06-10
- Only rewrite checksum files in `.task` if the checksum has changed (#1185,
#1194 by @deviantintegral).
- Added [experiments documentation](https://taskfile.dev/experiments) to the
website (#1198 by @pd93).
- Deprecated `version: 2` schema. This will be removed in the next major release
(#1197, #1198, #1199 by @pd93).
- Added a new `prompt:` prop to set a warning prompt to be shown before running
a potential dangurous task (#100, #1163 by @MaxCheetham,
[Documentation](https://taskfile.dev/usage/#warning-prompts)).
- Added support for single command task syntax. With this change, it's now
possible to declare just `cmd:` in a task, avoiding the more complex
`cmds: []` when you have only a single command for that task (#1130, #1131 by
@timdp).
## v3.25.0 - 2023-05-22
- Support `silent:` when calling another tasks (#680, #1142 by @danquah).
- Improve PowerShell completion script (#1168 by @trim21).
- Add more languages to the website menu and show translation progress
percentage (#1173 by @misitebao).
- Starting on this release, official binaries for FreeBSD will be available to
download (#1068 by @andreynering).
- Fix some errors being unintendedly supressed (#1134 by @clintmod).
- Fix a nil pointer error when `version` is omitted from a Taskfile (#1148,
#1149 by @pd93).
- Fix duplicate error message when a task does not exists (#1141, #1144 by
@pd93).
## v3.24.0 - 2023-04-15
- Fix Fish shell completion for tasks with aliases (#1113 by @patricksjackson).
- The default branch was renamed from `master` to `main` (#1049, #1048 by
@pd93).
- Fix bug where "up-to-date" logs were not being omitted for silent tasks (#546,
#1107 by @danquah).
- Add `.hg` (Mercurial) to the list of ignored directories when using `--watch`
(#1098 by @misery).
- More improvements to the release tool (#1096 by @pd93).
- Enforce [gofumpt](https://github.com/mvdan/gofumpt) linter (#1099 by @pd93)
- Add `--sort` flag for use with `--list` and `--list-all` (#946, #1105 by
@pd93).
- Task now has [custom exit codes](https://taskfile.dev/api/#exit-codes)
depending on the error (#1114 by @pd93).
## v3.23.0 - 2023-03-26
Task now has an
[official extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=task.vscode-task)
contributed by @pd93! :tada: The extension is maintained in a
[new repository](https://github.com/go-task/vscode-task) under the `go-task`
organization. We're looking to gather feedback from the community so please give
it a go and let us know what you think via a
[discussion](https://github.com/go-task/vscode-task/discussions),
[issue](https://github.com/go-task/vscode-task/issues) or on our
[Discord](https://discord.gg/6TY36E39UK)!
> **NOTE:** The extension _requires_ v3.23.0 to be installed in order to work.
- The website was integrated with
[Crowdin](https://crowdin.com/project/taskfile) to allow the community to
contribute with translations! [Chinese](https://taskfile.dev/zh-Hans/) is the
first language available (#1057, #1058 by @misitebao).
- Added task location data to the `--json` flag output (#1056 by @pd93)
- Change the name of the file generated by `task --init` from `Taskfile.yaml` to
`Taskfile.yml` (#1062 by @misitebao).
- Added new `splitArgs` template function
(`{{splitArgs "foo bar 'foo bar baz'"}}`) to ensure string is split as
arguments (#1040, #1059 by @dhanusaputra).
- Fix the value of `{{.CHECKSUM}}` variable in status (#1076, #1080 by @pd93).
- Fixed deep copy implementation (#1072 by @pd93)
- Created a tool to assist with releases (#1086 by @pd93).
## v3.22.0 - 2023-03-10
- Add a brand new `--global` (`-g`) flag that will run a Taskfile from your
`$HOME` directory. This is useful to have automation that you can run from
anywhere in your system!
([Documentation](https://taskfile.dev/usage/#running-a-global-taskfile), #1029
by @andreynering).
- Add ability to set `error_only: true` on the `group` output mode. This will
instruct Task to only print a command output if it returned with a non-zero
exit code (#664, #1022 by @jaedle).
- Fixed bug where `.task/checksum` file was sometimes not being created when
task also declares a `status:` (#840, #1035 by @harelwa, #1037 by @pd93).
- Refactored and decoupled fingerprinting from the main Task executor (#1039 by
@pd93).
- Fixed deadlock issue when using `run: once` (#715, #1025 by
@theunrepentantgeek).
## v3.21.0 - 2023-02-22
- Added new `TASK_VERSION` special variable (#990, #1014 by @ja1code).
- Fixed a bug where tasks were sometimes incorrectly marked as internal (#1007
by @pd93).
- Update to Go 1.20 (bump minimum version to 1.19) (#1010 by @pd93)
- Added environment variable `FORCE_COLOR` support to force color output.
Usefull for environments without TTY (#1003 by @automation-stack)
## v3.20.0 - 2023-01-14
- Improve behavior and performance of status checking when using the `timestamp`
mode (#976, #977 by @aminya).
- Performance optimizations were made for large Taskfiles (#982 by @pd93).
- Add ability to configure options for the
[`set`](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html)
and
[`shopt`](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html)
builtins (#908, #929 by @pd93,
[Documentation](http://taskfile.dev/usage/#set-and-shopt)).
- Add new `platforms:` attribute to `task` and `cmd`, so it's now possible to
choose in which platforms that given task or command will be run on. Possible
values are operating system (GOOS), architecture (GOARCH) or a combination of
the two. Example: `platforms: [linux]`, `platforms: [amd64]` or
`platforms: [linux/amd64]`. Other platforms will be skipped (#978, #980 by
@leaanthony).
## v3.19.1 - 2022-12-31
- Small bug fix: closing `Taskfile.yml` once we're done reading it (#963, #964
by @HeCorr).
- Fixes a bug in v2 that caused a panic when using a `Taskfile_{{OS}}.yml` file
(#961, #971 by @pd93).
- Fixed a bug where watch intervals set in the Taskfile were not being respected
(#969, #970 by @pd93)
- Add `--json` flag (alias `-j`) with the intent to improve support for code
editors and add room to other possible integrations. This is basic for now,
but we plan to add more info in the near future (#936 by @davidalpert, #764).
## v3.19.0 - 2022-12-05
- Installation via npm now supports [pnpm](https://pnpm.io/) as well
([go-task/go-npm#2](https://github.com/go-task/go-npm/issues/2),
[go-task/go-npm#3](https://github.com/go-task/go-npm/pull/3)).
- It's now possible to run Taskfiles from subdirectories! A new
`USER_WORKING_DIR` special variable was added to add even more flexibility for
monorepos (#289, #920).
- Add task-level `dotenv` support (#389, #904).
- It's now possible to use global level variables on `includes` (#942, #943).
- The website got a brand new
[translation to Chinese](https://task-zh.readthedocs.io/zh_CN/latest/) by
[@DeronW](https://github.com/DeronW). Thanks!
## v3.18.0 - 2022-11-12
- Show aliases on `task --list --silent` (`task --ls`). This means that aliases
will be completed by the completion scripts (#919).
- Tasks in the root Taskfile will now be displayed first in
`--list`/`--list-all` output (#806, #890).
- It's now possible to call a `default` task in an included Taskfile by using
just the namespace. For example: `docs:default` is now automatically aliased
to `docs` (#661, #815).
## v3.17.0 - 2022-10-14
- Add a "Did you mean ...?" suggestion when a task does not exits another one
with a similar name is found (#867, #880).
- Now YAML parse errors will print which Taskfile failed to parse (#885, #887).
- Add ability to set `aliases` for tasks and namespaces (#268, #340, #879).
- Improvements to Fish shell completion (#897).
- Added ability to set a different watch interval by setting `interval: '500ms'`
or using the `--interval=500ms` flag (#813, #865).
- Add colored output to `--list`, `--list-all` and `--summary` flags (#845,
#874).
- Fix unexpected behavior where `label:` was being shown instead of the task
name on `--list` (#603, #877).
## v3.16.0 - 2022-09-29
- Add `npm` as new installation method: `npm i -g @go-task/cli` (#870, #871,
[npm package](https://www.npmjs.com/package/@go-task/cli)).
- Add support to marking tasks and includes as internal, which will hide them
from `--list` and `--list-all` (#818).
## v3.15.2 - 2022-09-08
- Fix error when using variable in `env:` introduced in the previous release
(#858, #866).
- Fix handling of `CLI_ARGS` (`--`) in Bash completion (#863).
- On zsh completion, add ability to replace `--list-all` with `--list` as
already possible on the Bash completion (#861).
## v3.15.0 - 2022-09-03
- Add new special variables `ROOT_DIR` and `TASKFILE_DIR`. This was a highly
requested feature (#215, #857,
[Documentation](https://taskfile.dev/api/#special-variables)).
- Follow symlinks on `sources` (#826, #831).
- Improvements and fixes to Bash completion (#835, #844).
## v3.14.1 - 2022-08-03
- Always resolve relative include paths relative to the including Taskfile
(#822, #823).
- Fix ZSH and PowerShell completions to consider all tasks instead of just the
public ones (those with descriptions) (#803).
## v3.14.0 - 2022-07-08
- Add ability to override the `.task` directory location with the
`TASK_TEMP_DIR` environment variable.
- Allow to override Task colors using environment variables: `TASK_COLOR_RESET`,
`TASK_COLOR_BLUE`, `TASK_COLOR_GREEN`, `TASK_COLOR_CYAN`, `TASK_COLOR_YELLOW`,
`TASK_COLOR_MAGENTA` and `TASK_COLOR_RED` (#568, #792).
- Fixed bug when using the `output: group` mode where STDOUT and STDERR were
being print in separated blocks instead of in the right order (#779).
- Starting on this release, ARM architecture binaries are been released to Snap
as well (#795).
- i386 binaries won't be available anymore on Snap because Ubuntu removed the
support for this architecture.
- Upgrade mvdan.cc/sh, which fixes a bug with associative arrays (#785,
[mvdan/sh#884](https://github.com/mvdan/sh/issues/884),
[mvdan/sh#893](https://github.com/mvdan/sh/pull/893)).
## v3.13.0 - 2022-06-13
- Added `-n` as an alias to `--dry` (#776, #777).
- Fix behavior of interrupt (SIGINT, SIGTERM) signals. Task will now give time
for the processes running to do cleanup work (#458, #479, #728, #769).
- Add new `--exit-code` (`-x`) flag that will pass-through the exit form the
command being ran (#755).
## v3.12.1 - 2022-05-10
- Fixed bug where, on Windows, variables were ending with `\r` because we were
only removing the final `\n` but not `\r\n` (#717).
## v3.12.0 - 2022-03-31
- The `--list` and `--list-all` flags can now be combined with the `--silent`
flag to print the task names only, without their description (#691).
- Added support for multi-level inclusion of Taskfiles. This means that included
Taskfiles can also include other Taskfiles. Before this was limited to one
level (#390, #623, #656).
- Add ability to specify vars when including a Taskfile.
[Check out the documentation](https://taskfile.dev/#/usage?id=vars-of-included-taskfiles)
for more information (#677).
## v3.11.0 - 2022-02-19
- Task now supports printing begin and end messages when using the `group`
output mode, useful for grouping tasks in CI systems.
[Check out the documentation](http://taskfile.dev/#/usage?id=output-syntax)
for more information (#647, #651).
- Add `Taskfile.dist.yml` and `Taskfile.dist.yaml` to the supported file name
list.
[Check out the documentation](https://taskfile.dev/#/usage?id=supported-file-names)
for more information (#498, #666).
## v3.10.0 - 2022-01-04
- A new `--list-all` (alias `-a`) flag is now available. It's similar to the
exiting `--list` (`-l`) but prints all tasks, even those without a description
(#383, #401).
- It's now possible to schedule cleanup commands to run once a task finishes
with the `defer:` keyword
([Documentation](https://taskfile.dev/#/usage?id=doing-task-cleanup-with-defer),
#475, #626).
- Remove long deprecated and undocumented `$` variable prefix and `^` command
prefix (#642, #644, #645).
- Add support for `.yaml` extension (as an alternative to `.yml`). This was
requested multiple times throughout the years. Enjoy! (#183, #184, #369, #584,
#621).
- Fixed error when computing a variable when the task directory do not exist yet
(#481, #579).
## v3.9.2 - 2021-12-02
- Upgrade [mvdan/sh](https://github.com/mvdan/sh) which contains a fix a for a
important regression on Windows (#619,
[mvdan/sh#768](https://github.com/mvdan/sh/issues/768),
[mvdan/sh#769](https://github.com/mvdan/sh/pull/769)).
## v3.9.1 - 2021-11-28
- Add logging in verbose mode for when a task starts and finishes (#533, #588).
- Fix an issue with preconditions and context errors (#597, #598).
- Quote each `{{.CLI_ARGS}}` argument to prevent one with spaces to become many
(#613).
- Fix nil pointer when `cmd:` was left empty (#612, #614).
- Upgrade [mvdan/sh](https://github.com/mvdan/sh) which contains two relevant
fixes:
- Fix quote of empty strings in `shellQuote` (#609,
[mvdan/sh#763](https://github.com/mvdan/sh/issues/763)).
- Fix issue of wrong environment variable being picked when there's another
very similar one (#586,
[mvdan/sh#745](https://github.com/mvdan/sh/pull/745)).
- Install shell completions automatically when installing via Homebrew (#264,
#592,
[go-task/homebrew-tap#2](https://github.com/go-task/homebrew-tap/pull/2)).
## v3.9.0 - 2021-10-02
- A new `shellQuote` function was added to the template system
(`{{shellQuote "a string"}}`) to ensure a string is safe for use in shell
([mvdan/sh#727](https://github.com/mvdan/sh/pull/727),
[mvdan/sh#737](https://github.com/mvdan/sh/pull/737),
[Documentation](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote))
- In this version [mvdan.cc/sh](https://github.com/mvdan/sh) was upgraded with
some small fixes and features
- The `read -p` flag is now supported (#314,
[mvdan/sh#551](https://github.com/mvdan/sh/issues/551),
[mvdan/sh#772](https://github.com/mvdan/sh/pull/722))
- The `pwd -P` and `pwd -L` flags are now supported (#553,
[mvdan/sh#724](https://github.com/mvdan/sh/issues/724),
[mvdan/sh#728](https://github.com/mvdan/sh/pull/728))
- The `$GID` environment variable is now correctly being set (#561,
[mvdan/sh#723](https://github.com/mvdan/sh/pull/723))
## v3.8.0 - 2021-09-26
- Add `interactive: true` setting to improve support for interactive CLI apps
(#217, #563).
- Fix some `nil` errors (#534, #573).
- Add ability to declare an included Taskfile as optional (#519, #552).
- Add support for including Taskfiles in the home directory by using `~` (#539,
#557).
## v3.7.3 - 2021-09-04
- Add official support to Apple M1 (#564, #567).
- Our [official Homebrew tap](https://github.com/go-task/homebrew-tap) will
support more platforms, including Apple M1
## v3.7.0 - 2021-07-31
- Add `run:` setting to control if tasks should run multiple times or not.
Available options are `always` (the default), `when_changed` (if a variable
modified the task) and `once` (run only once no matter what). This is a long
time requested feature. Enjoy! (#53, #359).
## v3.6.0 - 2021-07-10
- Allow using both `sources:` and `status:` in the same task (#411, #427, #477).
- Small optimization and bug fix: don't compute variables if not needed for
`dotenv:` (#517).
## v3.5.0 - 2021-07-04
- Add support for interpolation in `dotenv:` (#433, #434, #453).
## v3.4.3 - 2021-05-30
- Add support for the `NO_COLOR` environment variable. (#459,
[fatih/color#137](https://github.com/fatih/color/pull/137)).
- Fix bug where sources were not considering the right directory in `--watch`
mode (#484, #485).
## v3.4.2 - 2021-04-23
- On watch, report which file failed to read (#472).
- Do not try to catch SIGKILL signal, which are not actually possible (#476).
- Improve version reporting when building Task from source using Go Modules
(#462, #473).
## v3.4.1 - 2021-04-17
- Improve error reporting when parsing YAML: in some situations where you would
just see an generic error, you'll now see the actual error with more detail:
the YAML line the failed to parse, for example (#467).
- A JSON Schema was published [here](https://json.schemastore.org/taskfile.json)
and is automatically being used by some editors like Visual Studio Code
(#135).
- Print task name before the command in the log output (#398).
## v3.3.0 - 2021-03-20
- Add support for delegating CLI arguments to commands with `--` and a special
`CLI_ARGS` variable (#327).
- Add a `--concurrency` (alias `-C`) flag, to limit the number of tasks that run
concurrently. This is useful for heavy workloads. (#345).
## v3.2.2 - 2021-01-12
- Improve performance of `--list` and `--summary` by skipping running shell
variables for these flags (#332).
- Fixed a bug where an environment in a Taskfile was not always overridable by
the system environment (#425).
- Fixed environment from .env files not being available as variables (#379).
- The install script is now working for ARM platforms (#428).
## v3.2.1 - 2021-01-09
- Fixed some bugs and regressions regarding dynamic variables and directories
(#426).
- The [slim-sprig](https://github.com/go-task/slim-sprig) package was updated
with the upstream [sprig](https://github.com/Masterminds/sprig).
## v3.2.0 - 2021-01-07
- Fix the `.task` directory being created in the task directory instead of the
Taskfile directory (#247).
- Fix a bug where dynamic variables (those declared with `sh:`) were not running
in the task directory when the task has a custom dir or it was in an included
Taskfile (#384).
- The watch feature (via the `--watch` flag) got a few different bug fixes and
should be more stable now (#423, #365).
## v3.1.0 - 2021-01-03
- Fix a bug when the checksum up-to-date resolution is used by a task with a
custom `label:` attribute (#412).
- Starting from this release, we're releasing official ARMv6 and ARM64 binaries
for Linux (#375, #418).
- Task now respects the order of declaration of included Taskfiles when
evaluating variables declaring by them (#393).
- `set -e` is now automatically set on every command. This was done to fix an
issue where multiline string commands wouldn't really fail unless the sentence
was in the last line (#403).
## v3.0.1 - 2020-12-26
- Allow use as a library by moving the required packages out of the `internal`
directory (#358).
- Do not error if a specified dotenv file does not exist (#378, #385).
- Fix panic when you have empty tasks in your Taskfile (#338, #362).
## v3.0.0 - 2020-08-16
- On `v3`, all CLI variables will be considered global variables (#336, #341)
- Add support to `.env` like files (#324, #356).
- Add `label:` to task so you can override the task name in the logs (#321,
#337).
- Refactor how variables work on version 3 (#311).
- Disallow `expansions` on v3 since it has no effect.
- `Taskvars.yml` is not automatically included anymore.
- `Taskfile_{{OS}}.yml` is not automatically included anymore.
- Allow interpolation on `includes`, so you can manually include a Taskfile
based on operation system, for example.
- Expose `.TASK` variable in templates with the task name (#252).
- Implement short task syntax (#194, #240).
- Added option to make included Taskfile run commands on its own directory
(#260, #144)
- Taskfiles in version 1 are not supported anymore (#237).
- Added global `method:` option. With this option, you can set a default method
to all tasks in a Taskfile (#246).
- Changed default method from `timestamp` to `checksum` (#246).
- New magic variables are now available when using `status:`: `.TIMESTAMP` which
contains the greatest modification date from the files listed in `sources:`,
and `.CHECKSUM`, which contains a checksum of all files listed in `status:`.
This is useful for manual checking when using external, or even remote,
artifacts when using `status:` (#216).
- We're now using [slim-sprig](https://github.com/go-task/slim-sprig) instead of
[sprig](https://github.com/Masterminds/sprig), which allowed a file size
reduction of about 22% (#219).
- We now use some colors on Task output to better distinguish message types -
commands are green, errors are red, etc (#207).
## v2.8.1 - 2020-05-20
- Fix error code for the `--help` flag (#300, #330).
- Print version to stdout instead of stderr (#299, #329).
- Supress `context` errors when using the `--watch` flag (#313, #317).
- Support templating on description (#276, #283).
## v2.8.0 - 2019-12-07
- Add `--parallel` flag (alias `-p`) to run tasks given by the command line in
parallel (#266).
- Fixed bug where calling the `task` CLI only informing global vars would not
execute the `default` task.
- Add hability to silent all tasks by adding `silent: true` a the root of the
Taskfile.
## v2.7.1 - 2019-11-10
- Fix error being raised when `exit 0` was called (#251).
## v2.7.0 - 2019-09-22
- Fixed panic bug when assigning a global variable (#229, #243).
- A task with `method: checksum` will now re-run if generated files are deleted
(#228, #238).
## v2.6.0 - 2019-07-21
- Fixed some bugs regarding minor version checks on `version:`.
- Add `preconditions:` to task (#205).
- Create directory informed on `dir:` if it doesn't exist (#209, #211).
- We now have a `--taskfile` flag (alias `-t`), which can be used to run another
Taskfile (other than the default `Taskfile.yml`) (#221).
- It's now possible to install Task using Homebrew on Linux
([go-task/homebrew-tap#1](https://github.com/go-task/homebrew-tap/pull/1)).
## v2.5.2 - 2019-05-11
- Reverted YAML upgrade due issues with CRLF on Windows (#201,
[go-yaml/yaml#450](https://github.com/go-yaml/yaml/issues/450)).
- Allow setting global variables through the CLI (#192).
## 2.5.1 - 2019-04-27
- Fixed some issues with interactive command line tools, where sometimes the
output were not being shown, and similar issues (#114, #190, #200).
- Upgraded [go-yaml/yaml](https://github.com/go-yaml/yaml) from v2 to v3.
## v2.5.0 - 2019-03-16
- We moved from the taskfile.org domain to the new fancy taskfile.dev domain.
While stuff is being redirected, we strongly recommend to everyone that use
[this install script](https://taskfile.dev/#/installation?id=install-script)
to use the new taskfile.dev domain on scripts from now on.
- Fixed to the ZSH completion (#182).
- Add
[`--summary` flag along with `summary:` task attribute](https://taskfile.org/#/usage?id=display-summary-of-task)
(#180).
## v2.4.0 - 2019-02-21
- Allow calling a task of the root Taskfile from an included Taskfile by
prefixing it with `:` (#161, #172).
- Add flag to override the `output` option (#173).
- Fix bug where Task was persisting the new checksum on the disk when the Dry
Mode is enabled (#166).
- Fix file timestamp issue when the file name has spaces (#176).
- Mitigating path expanding issues on Windows (#170).
## v2.3.0 - 2019-01-02
- On Windows, Task can now be installed using [Scoop](https://scoop.sh/) (#152).
- Fixed issue with file/directory globing (#153).
- Added ability to globally set environment variables (#138, #159).
## v2.2.1 - 2018-12-09
- This repository now uses Go Modules (#143). We'll still keep the `vendor`
directory in sync for some time, though;
- Fixing a bug when the Taskfile has no tasks but includes another Taskfile
(#150);
- Fix a bug when calling another task or a dependency in an included Taskfile
(#151).
## v2.2.0 - 2018-10-25
- Added support for
[including other Taskfiles](https://taskfile.org/#/usage?id=including-other-taskfiles)
(#98)
- This should be considered experimental. For now, only including local files
is supported, but support for including remote Taskfiles is being discussed.
If you have any feedback, please comment on #98.
- Task now have a dedicated documentation site: https://taskfile.org
- Thanks to [Docsify](https://docsify.js.org/) for making this pretty easy. To
check the source code, just take a look at the
[docs](https://github.com/go-task/task/tree/main/docs) directory of this
repository. Contributions to the documentation is really appreciated.
## v2.1.1 - 2018-09-17
- Fix suggestion to use `task --init` not being shown anymore (when a
`Taskfile.yml` is not found)
- Fix error when using checksum method and no file exists for a source glob
(#131)
- Fix signal handling when the `--watch` flag is given (#132)
## v2.1.0 - 2018-08-19
- Add a `ignore_error` option to task and command (#123)
- Add a dry run mode (`--dry` flag) (#126)
## v2.0.3 - 2018-06-24
- Expand environment variables on "dir", "sources" and "generates" (#116)
- Fix YAML merging syntax (#112)
- Add ZSH completion (#111)
- Implement new `output` option. Please check out the
[documentation](https://github.com/go-task/task#output-syntax)
## v2.0.2 - 2018-05-01
- Fix merging of YAML anchors (#112)
## v2.0.1 - 2018-03-11
- Fixes panic on `task --list`
## v2.0.0 - 2018-03-08
Version 2.0.0 is here, with a new Taskfile format.
Please, make sure to read the
[Taskfile versions](https://github.com/go-task/task/blob/main/TASKFILE_VERSIONS.md)
document, since it describes in depth what changed for this version.
- New Taskfile version 2 (#77)
- Possibility to have global variables in the `Taskfile.yml` instead of
`Taskvars.yml` (#66)
- Small improvements and fixes
## v1.4.4 - 2017-11-19
- Handle SIGINT and SIGTERM (#75);
- List: print message with there's no task with description;
- Expand home dir ("~" symbol) on paths (#74);
- Add Snap as an installation method;
- Move examples to its own repo;
- Watch: also walk on tasks called on on "cmds", and not only on "deps";
- Print logs to stderr instead of stdout (#68);
- Remove deprecated `set` keyword;
- Add checksum based status check, alternative to timestamp based.
## v1.4.3 - 2017-09-07
- Allow assigning variables to tasks at run time via CLI (#33)
- Added suport for multiline variables from sh (#64)
- Fixes env: remove square braces and evaluate shell (#62)
- Watch: change watch library and few fixes and improvements
- When use watching, cancel and restart long running process on file change (#59
and #60)
## v1.4.2 - 2017-07-30
- Flag to set directory of execution
- Always echo command if is verbose mode
- Add silent mode to disable echoing of commands
- Fixes and improvements of variables (#56)
## v1.4.1 - 2017-07-15
- Allow use of YAML for dynamic variables instead of $ prefix
- `VAR: {sh: echo Hello}` instead of `VAR: $echo Hello`
- Add `--list` (or `-l`) flag to print existing tasks
- OS specific Taskvars file (e.g. `Taskvars_windows.yml`, `Taskvars_linux.yml`,
etc)
- Consider task up-to-date on equal timestamps (#49)
- Allow absolute path in generates section (#48)
- Bugfix: allow templating when calling deps (#42)
- Fix panic for invalid task in cyclic dep detection
- Better error output for dynamic variables in Taskvars.yml (#41)
- Allow template evaluation in parameters
## v1.4.0 - 2017-07-06
- Cache dynamic variables
- Add verbose mode (`-v` flag)
- Support to task parameters (overriding vars) (#31) (#32)
- Print command, also when "set:" is specified (#35)
- Improve task command help text (#35)
## v1.3.1 - 2017-06-14
- Fix glob not working on commands (#28)
- Add ExeExt template function
- Add `--init` flag to create a new Taskfile
- Add status option to prevent task from running (#27)
- Allow interpolation on `generates` and `sources` attributes (#26)
## v1.3.0 - 2017-04-24
- Migrate from os/exec.Cmd to a native Go sh/bash interpreter
- This is a potentially breaking change if you use Windows.
- Now, `cmd` is not used anymore on Windows. Always use Bash-like syntax for
your commands, even on Windows.
- Add "ToSlash" and "FromSlash" to template functions
- Use functions defined on github.com/Masterminds/sprig
- Do not redirect stdin while running variables commands
- Using `context` and `errgroup` packages (this will make other tasks to be
cancelled, if one returned an error)
## v1.2.0 - 2017-04-02
- More tests and Travis integration
- Watch a task (experimental)
- Possibility to call another task
- Fix "=" not being reconized in variables/environment variables
- Tasks can now have a description, and help will print them (#10)
- Task dependencies now run concurrently
- Support for a default task (#16)
## v1.1.0 - 2017-03-08
- Support for YAML, TOML and JSON (#1)
- Support running command in another directory (#4)
- `--force` or `-f` flag to force execution of task even when it's up-to-date
- Detection of cyclic dependencies (#5)
- Support for variables (#6, #9, #14)
- Operation System specific commands and variables (#13)
## v1.0.0 - 2017-02-28
- Add LICENSE file

43
docs/versioned_docs/version-latest/community.md Normal file
View File

@ -0,0 +1,43 @@
---
slug: /community/
sidebar_position: 9
---
# Community
Some of the work to improve the Task ecosystem is done by the community, be it
installation methods or integrations with code editor. I (the author) am
thankful for everyone that helps me to improve the overall experience.
## Translations
We use [Crowdin](https://crowdin.com/project/taskfile) to translate our
document.
## Integrations
Many of our integrations are contributed and maintained by the community. You
can view the full list of community integrations
[here](/integrations#community-integrations).
## Installation methods
Some installation methods are maintained by third party:
- [GitHub Actions](https://github.com/arduino/setup-task) by @arduino
- [AUR](https://aur.archlinux.org/packages/go-task-bin) by @carlsmedstad
- [Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json)
- [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)
- [NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/go-task/default.nix)
- [Conda](https://github.com/conda-forge/go-task-feedstock/)
## More
Also, thanks for all the
[code contributors](https://github.com/go-task/task/graphs/contributors),
[financial contributors](https://opencollective.com/task), all those who
[reported bugs](https://github.com/go-task/task/issues?q=is%3Aissue) and
[answered questions](https://github.com/go-task/task/discussions).
If you know something that is missing in this document, please submit a pull
request.

167
docs/versioned_docs/version-latest/contributing.md Normal file
View File

@ -0,0 +1,167 @@
---
slug: /contributing/
sidebar_position: 11
---
# Contributing
Contributions to Task are very welcome, but we ask that you read this document
before submitting a PR.
:::note
This document applies to the core [Task][task] repository _and_ [Task for Visual
Studio Code][vscode-task].
:::
## Before you start
- **Check existing work** - Is there an existing PR? Are there issues discussing
the feature/change you want to make? Please make sure you consider/address
these discussions in your work.
- **Backwards compatibility** - Will your change break existing Taskfiles? It is
much more likely that your change will merged if it backwards compatible. Is
there an approach you can take that maintains this compatibility? If not,
consider opening an issue first so that API changes can be discussed before
you invest your time into a PR.
- **Experiments** - If there is no way to make your change backward compatible
then there is a procedure to introduce breaking changes into minor versions.
We call these "[experiments][experiments]". If you're intending to work on an
experiment, then please read the [experiments workflow][experiments-workflow]
document carefully and submit a proposal first.
## 1. Setup
- **Go** - Task is written in [Go][go]. We always support the latest two major
Go versions, so make sure your version is recent enough.
- **Node.js** - [Node.js][nodejs] is used to host Task's documentation server
and is required if you want to run this server locally. It is also required if
you want to contribute to the Visual Studio Code extension.
- **Yarn** - [Yarn][yarn] is the Node.js package manager used by Task.
## 2. Making changes
- **Code style** - Try to maintain the existing code style where possible. Go
code should be formatted by [`gofumpt`][gofumpt] and linted using
[`golangci-lint`][golangci-lint]. Any Markdown or TypeScript files should be
formatted and linted by [Prettier][prettier]. This style is enforced by our CI
to ensure that we have a consistent style across the project. You can use the
`task lint` command to lint the code locally and the `task lint:fix` command
to automatically fix any issues that are found.
- **Documentation** - Ensure that you add/update any relevant documentation. See
the [updating documentation](#updating-documentation) section below.
- **Tests** - Ensure that you add/update any relevant tests and that all tests
are passing before submitting the PR. See the [writing tests](#writing-tests)
section below.
### Running your changes
To run Task with working changes, you can use `go run ./cmd/task`. To run a
development build of task against a test Taskfile in `testdata`, you can use
`go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`.
To run Task for Visual Studio Code, you can open the project in VSCode and hit
F5 (or whatever you debug keybind is set to). This will open a new VSCode window
with the extension running. Debugging this way is recommended as it will allow
you to set breakpoints and step through the code. Otherwise, you can run
`task package` which will generate a `.vsix` file that can be used to manually
install the extension.
### Updating documentation
Task uses [Docusaurus][docusaurus] to host a documentation server. The code for
this is located in the core Task repository. This can be setup and run locally
by using `task docs` (requires `nodejs` & `yarn`). All content is written in
Markdown and is located in the `docs/docs` directory. All Markdown documents
should have an 80 character line wrap limit (enforced by Prettier).
When making a change, consider whether a change to the [Usage
Guide](/usage) is necessary. This document contains descriptions and
examples of how to use Task features. If you're adding a new feature, try to
find an appropriate place to add a new section. If you're updating an existing
feature, ensure that the documentation and any examples are up-to-date. Ensure
that any examples follow the [Taskfile Styleguide](/styleguide).
If you added a new field, command or flag, ensure that you add it to the
[API Reference](/api). New fields also need to be added to the
[JSON Schema][json-schema]. The descriptions for fields in the API reference and
the schema should match.
### Writing tests
A lot of Task's tests are held in the `task_test.go` file in the project root
and this is where you'll most likely want to add new ones too. Most of these
tests also have a subdirectory in the `testdata` directory where any
Taskfiles/data required to run the tests are stored.
When making a changes, consider whether new tests are required. These tests
should ensure that the functionality you are adding will continue to work in the
future. Existing tests may also need updating if you have changed Task's
behavior.
You may also consider adding unit tests for any new functions you have added.
The unit tests should follow the Go convention of being location in a file named
`*_test.go` in the same package as the code being tested.
## 3. Committing your code
Try to write meaningful commit messages and avoid having too many commits on the
PR. Most PRs should likely have a single commit (although for bigger PRs it may
be reasonable to split it in a few). Git squash and rebase is your friend!
If you're not sure how to format your commit message, check out [Conventional
Commits][conventional-commits]. This style is not enforced, but it is a good way
to make your commit messages more readable and consistent.
## 4. Submitting a PR
- **Describe your changes** - Ensure that you provide a comprehensive
description of your changes.
- **Issue/PR links** - Link any previous work such as related issues or PRs.
Please describe how your changes differ to/extend this work.
- **Examples** - Add any examples or screenshots that you think are useful to
demonstrate the effect of your changes.
- **Draft PRs** - If your changes are incomplete, but you would like to discuss
them, open the PR as a draft and add a comment to start a discussion. Using
comments rather than the PR description allows the description to be updated
later while preserving any discussions.
## FAQ
> I want to contribute, where do I start?
Take a look at the list of [open issues for Task][task-open-issues] or [Task for
Visual Studio Code][vscode-task-open-issues]. We have a [good first
issue][good-first-issue] label for simpler issues that are ideal for first time
contributions.
All kinds of contributions are welcome, whether its a typo fix or a shiny new
feature. You can also contribute by upvoting/commenting on issues, helping to
answer questions or contributing to other [community projects](/community).
> I'm stuck, where can I get help?
If you have questions, feel free to ask them in the `#help` forum channel on our
[Discord server][discord-server] or open a [Discussion][discussion] on GitHub.
---
<!-- prettier-ignore-start -->
[task]: https://github.com/go-task/task
[vscode-task]: https://github.com/go-task/vscode-task
[go]: https://go.dev
[gofumpt]: https://github.com/mvdan/gofumpt
[golangci-lint]: https://golangci-lint.run
[prettier]: https://prettier.io
[nodejs]: https://nodejs.org/en/
[yarn]: https://yarnpkg.com/
[docusaurus]: https://docusaurus.io
[json-schema]: https://github.com/go-task/task/blob/main/docs/static/schema.json
[task-open-issues]: https://github.com/go-task/task/issues
[vscode-task-open-issues]: https://github.com/go-task/vscode-task/issues
[good-first-issue]: https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[discord-server]: https://discord.gg/6TY36E39UK
[discussion]: https://github.com/go-task/task/discussions
[conventional-commits]: https://www.conventionalcommits.org
<!-- prettier-ignore-end -->

19
docs/versioned_docs/version-latest/deprecations/deprecations.md Normal file
View File

@ -0,0 +1,19 @@
---
slug: /deprecations/
sidebar_position: 7
---
# Deprecations
As Task evolves, it occasionally outgrows some of its functionality. This can be
because they are no longer useful, because another feature has replaced it or
because of a change in the way that Task works internally.
When this happens, we mark the functionality as deprecated. This means that it
will be removed in a future version of Task. This functionality will continue to
work until that time, but we strongly recommend that you do not implement this
functionality in new Taskfiles and make a plan to migrate away from it as soon
as possible.
You can view a full list of active deprecations in the "Deprecations" section of
the sidebar.

23
docs/versioned_docs/version-latest/deprecations/template.md Normal file
View File

@ -0,0 +1,23 @@
---
# This is a template for an experiments documentation
# Copy this page and fill in the details as necessary
title: '--- Template ---'
sidebar_position: -1 # Always push to the top
draft: true # Hide in production
---
# \{Name of Deprecated Feature\} (#\{Issue\})
:::warning
This deprecation breaks the following functionality:
- \{list any existing functionality that will be broken by this deprecation\}
- \{if there are no breaking changes, remove this admonition\}
:::
\{Short description of the feature/behavior and why it is being deprecated\}
\{Short explanation of any replacement features/behaviors and how users should
migrate to it\}

33
docs/versioned_docs/version-latest/deprecations/version_2_schema.md Normal file
View File

@ -0,0 +1,33 @@
---
slug: /deprecations/version-2-schema/
---
# Version 2 Schema (#1197)
:::warning
This deprecation breaks the following functionality:
- Any Taskfiles that use the version 2 schema
- `Taskvar.yml` files
:::
The Taskfile version 2 schema was introduced in March 2018 and replaced by
version 3 in August 2019. In May 2023 [we published a deprecation
notice][deprecation-notice] for the version 2 schema on the basis that the vast
majority of users had already upgraded to version 3 and removing support for
version 2 would allow us to tidy up the codebase and focus on new functionality
instead.
In December 2023, the final version of Task that supports the version 2 schema
([v3.33.0][v3.33.0]) was published and all legacy code was removed from Task's
main branch. To use a more recent version of Task, you will need to ensure that
your Taskfile uses the version 3 schema instead. A list of changes between
version 2 and version 3 are available in the [Task v3 Release Notes][v3.0.0].
<!-- prettier-ignore-start -->
[v3.0.0]: https://github.com/go-task/task/releases/tag/v3.0.0
[v3.33.0]: https://github.com/go-task/task/releases/tag/v3.33.0
[deprecation-notice]: https://github.com/go-task/task/issues/1197
<!-- prettier-ignore-end -->

52
docs/versioned_docs/version-latest/donate.md Normal file
View File

@ -0,0 +1,52 @@
---
slug: /donate/
sidebar_position: 16
---
# Donate
If you find this project useful, you can consider donating by using one of the
channels listed below.
This is just a way of saying "thank you", it won't give you any benefits like
higher priority on issues or something similar.
Companies who donate at least $50/month will be featured as a "Gold Sponsor" in
the website homepage and on the GitHub repository README. Make contact with
[@andreynering] with the logo you want to be shown. Suspect businesses
(gambling, casinos, etc) won't be allowed, though.
## GitHub Sponsors
The preferred way to donate to the maintainers is via GitHub Sponsors. Just use
the following links to do your donation. We suggest a 50/50 split to each
maintainer of the total amount you plan to donate to the project.
- [@andreynering](https://github.com/sponsors/andreynering)
- [@pd93](https://github.com/sponsors/pd93)
## Open Collective
If you prefer [Open Collective](https://opencollective.com/task) you can donate
by using these links:
- [$2 per month](https://opencollective.com/task/contribute/backer-4034/checkout)
- [$5 per month](https://opencollective.com/task/contribute/supporter-8404/checkout)
- [$20 per month](https://opencollective.com/task/contribute/sponsor-4035/checkout)
- [$50 per month](https://opencollective.com/task/contribute/sponsor-28775/checkout)
- [Custom value - One-time donation option supported](https://opencollective.com/task/donate)
## PayPal
You can donate to [@andreynering] via PayPal as well:
- [Any value - One-time donation](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=GSVDU63RKG45A&currency_code=USD&source=url)
## PIX (Brazil only)
And if you're Brazilian, you can also donate to [@andreynering] via PIX by
[using this QR Code](/img/pix.png).
<!-- prettier-ignore-start -->
[@andreynering]: https://github.com/andreynering
<!-- prettier-ignore-end -->

346
docs/versioned_docs/version-latest/experiments/any_variables.mdx Normal file
View File

@ -0,0 +1,346 @@
---
slug: /experiments/any-variables/
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Any Variables (#1415)
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
Currently, Task only supports string variables. This experiment allows you to
specify and use the following variable types:
- `string`
- `bool`
- `int`
- `float`
- `array`
- `map`
This allows you to have a lot more flexibility in how you use variables in
Task's templating engine. There are two active proposals for this experiment.
Click on the tabs below to switch between them.
<Tabs defaultValue="1" queryString="proposal"
values={[
{label: 'Proposal 1', value: '1'},
{label: 'Proposal 2', value: '2'}
]}>
<TabItem value="1">
:::warning
This experiment proposal breaks the following functionality:
- Dynamically defined variables (using the `sh` keyword)
:::
:::info
To enable this experiment, set the environment variable:
`TASK_X_ANY_VARIABLES=1`. Check out [our guide to enabling experiments
][enabling-experiments] for more information.
:::
## Maps
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:
```yaml
version: 3
tasks:
foo:
vars:
FOO: {a: 1, b: 2, c: 3} # <-- Directly defined map on the `FOO` key
cmds:
- 'echo {{.FOO.a}}'
```
## 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.
Previously, you might have defined a dynamic variable like this:
```yaml
version: 3
tasks:
foo:
vars:
CALCULATED_VAR:
sh: 'echo hello'
cmds:
- '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:
```yaml
version: 3
tasks:
foo:
vars:
CALCULATED_VAR: '$echo hello'
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>
<TabItem value="2">
:::info
To enable this experiment, set the environment variable:
`TASK_X_ANY_VARIABLES=2`. Check out [our guide to enabling experiments
][enabling-experiments] for more information.
:::
## Maps
This proposal maintains backwards-compatibility and the `sh` subkey and adds
another new `map` subkey for defining map variables:
```yaml
version: 3
tasks:
foo:
vars:
FOO:
map: {a: 1, b: 2, c: 3} # <-- Defined using the `map' subkey instead of directly on 'FOO'
BAR: true # <-- Other types of variables are still defined directly on the key
BAZ:
sh: 'echo Hello Task' # <-- The `sh` 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.
Before:
```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}}'
```
After:
```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}}'
```
## 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 to pass it:
```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'
```
Unfortunately, this results in the value always being passed as a string as this
is the output type of the templater and operations on the passed variable may
not behave as expected. With this proposal, you can now pass variables by
reference using the `ref` subkey:
```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
```
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'
```
</TabItem></Tabs>
---
## Common to both proposals
Both proposals add support for all other variable types by directly defining
them in the Taskfile. For example:
### Evaluating booleans
```yaml
version: 3
tasks:
foo:
vars:
BOOL: false
cmds:
- '{{if .BOOL}}echo foo{{end}}'
```
### Arithmetic
```yaml
version: 3
tasks:
foo:
vars:
INT: 10
FLOAT: 3.14159
cmds:
- 'echo {{add .INT .FLOAT}}'
```
### Ranging
```yaml
version: 3
tasks:
foo:
vars:
ARRAY: [1, 2, 3]
cmds:
- 'echo {{range .ARRAY}}{{.}}{{end}}'
```
There are many more templating functions which can be used with the new types of
variables. For a full list, see the [slim-sprig][slim-sprig] documentation.
## Looping over variables
Previously, you would have to use a delimiter separated string to loop over an
arbitrary list of items in a variable and split them by using the `split` subkey
to specify the delimiter:
```yaml
version: 3
tasks:
foo:
vars:
LIST: 'foo,bar,baz'
cmds:
- for:
var: LIST
split: ','
cmd: echo {{.ITEM}}
```
Both of these proposals add support for looping over "collection-type" variables
using the `for` keyword, so now you are able to loop over a map/array variable
directly:
```yaml
version: 3
tasks:
foo:
vars:
LIST: [foo, bar, baz]
cmds:
- for:
var: LIST
cmd: echo {{.ITEM}}
```
When looping over a map we also make an additional `{{.KEY}}` variable availabe
that holds the string value of the map key. Remember that maps are unordered, so
the order in which the items are looped over is random.
<!-- prettier-ignore-start -->
[enabling-experiments]: /experiments/#enabling-experiments
[slim-sprig]: https://go-task.github.io/slim-sprig/
<!-- prettier-ignore-end -->

131
docs/versioned_docs/version-latest/experiments/experiments.md Normal file
View File

@ -0,0 +1,131 @@
---
slug: /experiments/
sidebar_position: 6
---
# Experiments
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
In order to allow Task to evolve quickly, we sometimes roll out breaking changes
to minor versions behind experimental flags. This allows us to gather feedback
on breaking changes before committing to a major release. This process can also
be used to gather feedback on important non-breaking features before their
design is completed. This document describes the
[experiment workflow](#workflow) and how you can get involved.
You can view the full list of active experiments in the sidebar submenu to the
left of the page and click on each one to find out more about it.
## Enabling Experiments
Task uses environment variables to detect whether or not an experiment is
enabled. All of the experiment variables will begin with the same `TASK_X_`
prefix followed by the name of the experiment. You can find the exact name for
each experiment on their respective pages in the sidebar. If the variable is set
`=1` then it will be enabled. Some experiments may have multiple proposals, in
which case, you will need to set the variable equal to the number of the
proposal that you want to enable (`=2`, `=3` etc).
There are three main ways to set the environment variables for an experiment.
Which method you use depends on how you intend to use the experiment:
1. Prefixing your task commands with the relevant environment variable(s). For
example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
invocations of Task to test out experimental features.
1. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
`.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
for your personal environment.
```shell title="~/.bashrc"
export TASK_X_FEATURE=1
```
1. Creating a `.env` file in the same directory as your root Taskfile that
contains the relevant environment variable(s). This allows you to enable an
experimental feature at a project level. If you commit the `.env` file to
source control then other users of your project will also have these
experiments enabled.
```shell title=".env"
TASK_X_FEATURE=1
```
## Workflow
Experiments are a way for us to test out new features in Task before committing
to them in a major release. Because this concept is built around the idea of
feedback from our community, we have built a workflow for the process of
introducing these changes. This ensures that experiments are given the attention
and time that they need and that we are getting the best possible results out of
them.
The sections below describe the various stages that an experiment must go
through from its proposal all the way to being released in a major version of
Task.
### 1. Proposal
All experimental features start with a proposal in the form of a GitHub issue.
If the maintainers decide that an issue has enough support and is a breaking
change or is complex/controversial enough to require user feedback, then the
issue will be marked with the `experiment: proposal` label. At this point, the
issue becomes a proposal and a period of consultation begins. During this
period, we request that users provide feedback on the proposal and how it might
effect their use of Task. It is up to the discretion of the maintainers to
decide how long this period lasts.
### 2. Draft
Once a proposal's consultation ends, a contributor may pick up the work and
begin the initial implementation. Once a PR is opened, the maintainers will
ensure that it meets the requirements for an experimental feature (i.e. flags
are in the right format etc) and merge the feature. Once this code is released,
the status will be updated via the `experiment: draft` label. This indicates
that an implementation is now available for use in a release and the experiment
is open for feedback.
:::note
During the draft period, major changes to the implementation may be made based
on the feedback received from users. There are _no stability guarantees_ and
experimental features may be abandoned _at any time_.
:::
### 3. Candidate
Once an acceptable level of consensus has been reached by the community and
feedback/changes are less frequent/significant, the status may be updated via
the `experiment: candidate` label. This indicates that a proposal is _likely_ to
accepted and will enter a period for final comments and minor changes.
### 4. Stable
Once a suitable amount of time has passed with no changes or feedback, an
experiment will be given the `experiment: stable` label. At this point, the
functionality will be treated like any other feature in Task and any changes
_must_ be backward compatible. This allows users to migrate to the new
functionality without having to worry about anything breaking in future
releases. This provides the best experience for users migrating to a new major
version.
### 5. Released
When making a new major release of Task, all experiments marked as
`experiment: stable` will move to `experiment: released` and their behaviors
will become the new default in Task. Experiments in an earlier stage (i.e. not
stable) cannot be released and so will continue to be experiments in the new
version.
### Abandoned / Superseded
If an experiment is unsuccessful at any point then it will be given the
`experiment: abandoned` or `experiment: superseded` labels depending on which is
more suitable. These experiments will be removed from Task.

49
docs/versioned_docs/version-latest/experiments/gentle_force.md Normal file
View File

@ -0,0 +1,49 @@
---
slug: /experiments/gentle-force/
---
# Gentle Force (#1200)
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
:::warning
This experiment breaks the following functionality:
- The `--force` flag
:::
:::info
To enable this experiment, set the environment variable: `TASK_X_FORCE=1`. Check
out [our guide to enabling experiments ][enabling-experiments] for more
information.
:::
The `--force` flag currently forces _all_ tasks to run regardless of the status
checks. This can be useful, but we have found that most of the time users only
expect the direct task they are calling to be forced and _not_ all of its
dependant tasks.
This experiment changes the `--force` flag to only force the directly called
task. All dependant tasks will have their statuses checked as normal and will
only run if Task considers them to be out of date. A new `--force-all` flag will
also be added to maintain the current behavior for users that need this
functionality.
If you want to migrate, but continue to force all dependant tasks to run, you
should replace all uses of the `--force` flag with `--force-all`. Alternatively,
if you want to adopt the new behavior, you can continue to use the `--force`
flag as you do now!
<!-- prettier-ignore-start -->
[enabling-experiments]: /experiments/#enabling-experiments
<!-- prettier-ignore-end -->

105
docs/versioned_docs/version-latest/experiments/remote_taskfiles.md Normal file
View File

@ -0,0 +1,105 @@
---
slug: /experiments/remote-taskfiles/
---
# Remote Taskfiles (#1317)
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
:::info
To enable this experiment, set the environment variable:
`TASK_X_REMOTE_TASKFILES=1`. Check out [our guide to enabling experiments
][enabling-experiments] for more information.
:::
This experiment allows you to specify a remote Taskfile URL when including a
Taskfile. For example:
```yaml
version: '3'
includes:
my-remote-namespace: https://raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml
```
This works exactly the same way that including a local file does. Any tasks in
the remote Taskfile will be available to run from your main Taskfile via the
namespace `my-remote-namespace`. For example, if the remote file contains the
following:
```yaml
version: '3'
tasks:
hello:
silent: true
cmds:
- echo "Hello from the remote Taskfile!"
```
and you run `task my-remote-namespace:hello`, it will print the text: "Hello
from the remote Taskfile!" to your console.
## Security
Running commands from sources that you do not control is always a potential
security risk. For this reason, we have added some checks when using remote
Taskfiles:
1. When running a task from a remote Taskfile for the first time, Task will
print a warning to the console asking you to check that you are sure that you
trust the source of the Taskfile. If you do not accept the prompt, then Task
will exit with code `104` (not trusted) and nothing will run. If you accept
the prompt, the remote Taskfile will run and further calls to the remote
Taskfile will not prompt you again.
2. Whenever you run a remote Taskfile, Task will create and store a checksum of
the file that you are running. If the checksum changes, then Task will print
another warning to the console to inform you that the contents of the remote
file has changed. If you do not accept the prompt, then Task will exit with
code `104` (not trusted) and nothing will run. If you accept the prompt, the
checksum will be updated and the remote Taskfile will run.
Sometimes you need to run Task in an environment that does not have an
interactive terminal, so you are not able to accept a prompt. In these cases you
are able to tell task to accept these prompts automatically by using the `--yes`
flag. Before enabling this flag, you should:
1. Be sure that you trust the source and contents of the remote Taskfile.
2. Consider using a pinned version of the remote Taskfile (e.g. A link
containing a commit hash) to prevent Task from automatically accepting a
prompt that says a remote Taskfile has changed.
Task currently supports both `http` and `https` URLs. However, the `http`
requests will not execute by default unless you run the task with the
`--insecure` flag. This is to protect you from accidentally running a remote
Taskfile that is hosted on and unencrypted connection. Sources that are not
protected by TLS are vulnerable to [man-in-the-middle
attacks][man-in-the-middle-attacks] and should be avoided unless you know what
you are doing.
## Caching & Running Offline
Whenever you run a remote Taskfile, the latest copy will be downloaded from the
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.
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.
<!-- prettier-ignore-start -->
[enabling-experiments]: /experiments/#enabling-experiments
[man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
<!-- prettier-ignore-end -->

42
docs/versioned_docs/version-latest/experiments/template.md Normal file
View File

@ -0,0 +1,42 @@
---
# This is a template for an experiments documentation
# Copy this page and fill in the details as necessary
title: '--- Template ---'
sidebar_position: -1 # Always push to the top
draft: true # Hide in production
---
# \{Name of Experiment\} (#\{Issue\})
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
:::warning
This experiment breaks the following functionality:
- \{list any existing functionality that will be broken by this experiment\}
- \{if there are no breaking changes, remove this admonition\}
:::
:::info
To enable this experiment, set the environment variable: `TASK_X_{feature}=1`.
Check out [our guide to enabling experiments ][enabling-experiments] for more
information.
:::
\{Short description of the feature\}
\{Short explanation of how users should migrate to the new behavior\}
<!-- prettier-ignore-start -->
[enabling-experiments]: /experiments/#enabling-experiments
<!-- prettier-ignore-end -->

101
docs/versioned_docs/version-latest/faq.md Normal file
View File

@ -0,0 +1,101 @@
---
slug: /faq/
sidebar_position: 15
---
# FAQ
This page contains a list of frequently asked questions about Task.
## Why won't my task update my shell environment?
This is a limitation of how shells work. Task runs as a subprocess of your
current shell, so it can't change the environment of the shell that started it.
This limitation is shared by other task runners and build tools too.
A common way to work around this is to create a task that will generate output
that can be parsed by your shell. For example, to set an environment variable on
your shell you can write a task like this:
```yaml
my-shell-env:
cmds:
- echo "export FOO=foo"
- echo "export BAR=bar"
```
Now run `eval $(task my-shell-env)` and the variables `$FOO` and `$BAR` will be
available in your shell.
## I can't reuse my shell in a task's commands
Task runs each command as a separate shell process, so something you do in one
command won't effect any future commands. For example, this won't work:
```yaml
version: '3'
tasks:
foo:
cmds:
- a=foo
- echo $a
# outputs ""
```
To work around this you can either use a multiline command:
```yaml
version: '3'
tasks:
foo:
cmds:
- |
a=foo
echo $a
# outputs "foo"
```
Or for more complex multi-line commands it is recommended to move your code into
a separate file and call that instead:
```yaml
version: '3'
tasks:
foo:
cmds:
- ./foo-printer.bash
```
```shell
#!/bin/bash
a=foo
echo $a
```
## 'x' builtin command doesn't work on Windows
The default shell on Windows (`cmd` and `powershell`) do not have commands like
`rm` and `cp` available as builtins. This means that these commands won't work.
If you want to make your Taskfile fully cross-platform, you'll need to work
around this limitation using one of the following methods:
- Use the `{{OS}}` function to run an OS-specific script.
- Use something like `{{if eq OS "windows"}}powershell {{end}}<my_cmd>` to
detect windows and run the command in Powershell directly.
- Use a shell on Windows that supports these commands as builtins, such as [Git
Bash][git-bash] or [WSL][wsl].
We want to make improvements to this part of Task and the issues below track
this work. Constructive comments and contributions are very welcome!
- #197
- [mvdan/sh#93](https://github.com/mvdan/sh/issues/93)
- [mvdan/sh#97](https://github.com/mvdan/sh/issues/97)
<!-- prettier-ignore-start -->
[git-bash]: https://gitforwindows.org/
[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install
<!-- prettier-ignore-end -->

303
docs/versioned_docs/version-latest/installation.md Normal file
View File

@ -0,0 +1,303 @@
---
slug: /installation/
sidebar_position: 2
---
# Installation
Task offers many installation methods. Check out the available methods below.
## Package Managers
### Homebrew
If you're on macOS or Linux and have [Homebrew][homebrew] installed, getting
Task is as simple as running:
```shell
brew install go-task/tap/go-task
```
The above Formula is
[maintained by ourselves](https://github.com/go-task/homebrew-tap/blob/main/Formula/go-task.rb).
Recently, Task was also made available
[on the official Homebrew repository](https://formulae.brew.sh/formula/go-task),
so you also have that option if you prefer:
```shell
brew install go-task
```
### Tea
If you're on macOS or Linux and have [tea][tea] installed, getting Task is as
simple as running:
```shell
tea task
```
or, if you have tea’s magic enabled:
```shell
task
```
This installation method is community owned. After a new release of Task, they
are automatically released by tea in a minimum of time.
### Snap
Task is available in [Snapcraft][snapcraft], but keep in mind that your Linux
distribution should allow classic confinement for Snaps to Task work right:
```shell
sudo snap install task --classic
```
### Chocolatey
If you're on Windows and have [Chocolatey][choco] installed, getting Task is as
simple as running:
```shell
choco install go-task
```
This installation method is community owned.
### Scoop
If you're on Windows and have [Scoop][scoop] installed, getting Task is as
simple as running:
```shell
scoop install task
```
This installation method is community owned. After a new release of Task, it may
take some time until it's available on Scoop.
### AUR
If you're on Arch Linux you can install Task from
[AUR](https://aur.archlinux.org/packages/go-task-bin) using your favorite
package manager such as `yay`, `pacaur` or `yaourt`:
```shell
yay -S go-task-bin
```
Alternatively, there's
[this package](https://aur.archlinux.org/packages/go-task) which installs from
the source code instead of downloading the binary from the
[releases page](https://github.com/go-task/task/releases):
```shell
yay -S go-task
```
This installation method is community owned.
### Fedora
If you're on Fedora Linux you can install Task from the official
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)
repository using `dnf`:
```shell
sudo dnf install go-task
```
This installation method is community owned. After a new release of Task, it may
take some time until it's available in
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/).
### Nix
If you're on NixOS or have Nix installed you can install Task from
[nixpkgs](https://github.com/NixOS/nixpkgs):
```shell
nix-env -iA nixpkgs.go-task
```
This installation method is community owned. After a new release of Task, it may
take some time until it's available in
[nixpkgs](https://github.com/NixOS/nixpkgs).
### npm
You can also use Node and npm to install Task by installing
[this package](https://www.npmjs.com/package/@go-task/cli).
```shell
npm install -g @go-task/cli
```
### Winget
If you are using Windows and installed the
[winget](https://github.com/microsoft/winget-cli) package management tool, you
can install Task from [winget-pkgs](https://github.com/microsoft/winget-pkgs).
```shell
winget install Task.Task
```
## Get The Binary
### Binary
You can download the binary from the [releases page on GitHub][releases] and add
to your `$PATH`.
DEB and RPM packages are also available.
The `task_checksums.txt` file contains the SHA-256 checksum for each file.
### Install Script
We also have an [install script][installscript] which is very useful in
scenarios like CI. Many thanks to [GoDownloader][godownloader] for enabling the
easy generation of this script.
By default, it installs on the `./bin` directory relative to the working
directory:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
```
It is possible to override the installation directory with the `-b` parameter.
On Linux, common choices are `~/.local/bin` and `~/bin` to install for the
current user or `/usr/local/bin` to install for all users:
```shell
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin
```
:::caution
On macOS and Windows, `~/.local/bin` and `~/bin` are not added to `$PATH` by
default.
:::
### GitHub Actions
If you want to install Task in GitHub Actions you can try using
[this action](https://github.com/arduino/setup-task) by the Arduino team:
```yaml
- name: Install Task
uses: arduino/setup-task@v1
with:
version: 3.x
repo-token: ${{ secrets.GITHUB_TOKEN }}
```
This installation method is community owned.
## Build From Source
### Go Modules
Ensure that you have a supported version of [Go][go] properly installed and
setup. You can find the minimum required version of Go in the
[go.mod](https://github.com/go-task/task/blob/main/go.mod#L3) file.
You can then install the latest release globally by running:
```shell
go install github.com/go-task/task/v3/cmd/task@latest
```
Or you can install into another directory:
```shell
env GOBIN=/bin go install github.com/go-task/task/v3/cmd/task@latest
```
:::tip
For CI environments we recommend using the [install script](#install-script)
instead, which is faster and more stable, since it'll just download the latest
released binary.
:::
## Setup completions
Download the autocompletion file corresponding to your shell.
[All completions are available on the Task repository](https://github.com/go-task/task/tree/main/completion).
### Bash
First, ensure that you installed bash-completion using your package manager.
Make the completion file executable:
```shell
chmod +x path/to/task.bash
```
After, add this to your `~/.bash_profile`:
```shell
source path/to/task.bash
```
### ZSH
Put the `_task` file somewhere in your `$FPATH`:
```shell
mv path/to/_task /usr/local/share/zsh/site-functions/_task
```
Ensure that the following is present in your `~/.zshrc`:
```shell
autoload -U compinit
compinit -i
```
ZSH version 5.7 or later is recommended.
### Fish
Move the `task.fish` completion script:
```shell
mv path/to/task.fish ~/.config/fish/completions/task.fish
```
### PowerShell
Open your profile script with:
```powershell
mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue
notepad $profile
```
Add the line and save the file:
```shell
Invoke-Expression -Command path/to/task.ps1
```
<!-- prettier-ignore-start -->
[go]: https://golang.org/
[snapcraft]: https://snapcraft.io/task
[homebrew]: https://brew.sh/
[installscript]: https://github.com/go-task/task/blob/main/install-task.sh
[releases]: https://github.com/go-task/task/releases
[godownloader]: https://github.com/goreleaser/godownloader
[choco]: https://chocolatey.org/
[scoop]: https://scoop.sh/
[tea]: https://tea.xyz/
<!-- prettier-ignore-end -->

84
docs/versioned_docs/version-latest/integrations.md Normal file
View File

@ -0,0 +1,84 @@
---
slug: /integrations/
sidebar_position: 8
---
# Integrations
## Visual Studio Code Extension
Task has an
[official extension for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=task.vscode-task).
The code for this project can be found
[here](https://github.com/go-task/vscode-task). To use this extension, you must
have Task v3.23.0+ installed on your system.
This extension provides the following features (and more):
- View tasks in the sidebar.
- Run tasks from the sidebar and command palette.
- Go to definition from the sidebar and command palette.
- Run last task command.
- Multi-root workspace support.
- Initialize a Taskfile in the current workspace.
To get autocompletion and validation for your Taskfile, see the
[Schema](#schema) section below.
![Task for Visual Studio Code](https://github.com/go-task/vscode-task/blob/main/res/preview.png?raw=true)
## Schema
This was initially created by @KROSF in
[this Gist](https://gist.github.com/KROSF/c5435acf590acd632f71bb720f685895) and
is now officially maintained in
[this file](https://github.com/go-task/task/blob/main/docs/static/schema.json)
and made available at https://taskfile.dev/schema.json. This schema can be used
to validate Taskfiles and provide autocompletion in many code editors:
### Visual Studio Code
To integrate the schema into VS Code, you need to install the
[YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)
by Red Hat. Any `Taskfile.yml` in your project should automatically be detected
and validation/autocompletion should work. If this doesn't work or you want to
manually configure it for files with a different name, you can add the following
to your `settings.json`:
```json
// settings.json
{
"yaml.schemas": {
"https://taskfile.dev/schema.json": [
"**/Taskfile.yml",
"./path/to/any/other/taskfile.yml"
]
}
}
```
You can also configure the schema directly inside of a Taskfile by adding the
following comment to the top of the file:
```yaml
# yaml-language-server: $schema=https://taskfile.dev/schema.json
version: '3'
```
You can find more information on this in the
[YAML language server project](https://github.com/redhat-developer/yaml-language-server).
## Community Integrations
In addition to our official integrations, there is an amazing community of
developers who have created their own integrations for Task:
- [Sublime Text Plugin](https://packagecontrol.io/packages/Taskfile)
[[source](https://github.com/biozz/sublime-taskfile)] by @biozz
- [IntelliJ Plugin](https://plugins.jetbrains.com/plugin/17058-taskfile)
[[source](https://github.com/lechuckroh/task-intellij-plugin)] by @lechuckroh
- [mk](https://github.com/pycontribs/mk) command line tool recognizes Taskfiles
natively.
If you have made something that integrates with Task, please feel free to open a
PR to add it to this list.

61
docs/versioned_docs/version-latest/intro.md Normal file
View File

@ -0,0 +1,61 @@
---
slug: /
sidebar_position: 1
title: Home
---
# Task
<div align="center">
<img id="logo" src="img/logo.svg" height="250px" width="250px" />
</div>
Task is a task runner / build tool that aims to be simpler and easier to use
than, for example, [GNU Make][make].
Since it's written in [Go][go], Task is just a single binary and has no other
dependencies, which means you don't need to mess with any complicated install
setups just to use a build tool.
Once [installed](/installation), you just need to describe your build tasks
using a simple [YAML][yaml] schema in a file called `Taskfile.yml`:
```yaml title="Taskfile.yml"
version: '3'
tasks:
hello:
cmds:
- echo 'Hello World from Task!'
silent: true
```
And call it by running `task hello` from your terminal.
The above example is just the start, you can take a look at the [usage](/usage)
guide to check the full schema documentation and Task features.
## Features
- [Easy installation](/installation): just download a single binary, add to
`$PATH` and you're done! Or you can also install using [Homebrew][homebrew],
[Snapcraft][snapcraft], or [Scoop][scoop] if you want.
- Available on CIs: by adding
[this simple command](/installation#install-script) to install on your CI
script and you're ready to use Task as part of your CI pipeline;
- Truly cross-platform: while most build tools only work well on Linux or macOS,
Task also supports Windows thanks to [this shell interpreter for Go][sh].
- Great for code generation: you can easily
[prevent a task from running](/usage#prevent-unnecessary-work) if a given set
of files haven't changed since last run (based either on its timestamp or
content).
<!-- prettier-ignore-start -->
[make]: https://www.gnu.org/software/make/
[go]: https://go.dev/
[yaml]: http://yaml.org/
[homebrew]: https://brew.sh/
[snapcraft]: https://snapcraft.io/
[scoop]: https://scoop.sh/
[sh]: https://github.com/mvdan/sh
<!-- prettier-ignore-end -->

72
docs/versioned_docs/version-latest/releasing.md Normal file
View File

@ -0,0 +1,72 @@
---
slug: /releasing/
sidebar_position: 13
---
# Releasing
The release process of Task is done with the help of [GoReleaser][goreleaser].
You can test the release process locally by calling the `test-release` task of
the Taskfile.
[GitHub Actions](https://github.com/go-task/task/actions) should release
artifacts automatically when a new Git tag is pushed to `main` branch (raw
executables and DEB and RPM packages).
Since v3.15.0, raw executables can also be reproduced and verified locally by
checking out a specific tag and calling `goreleaser build`, using the Go version
defined in the above GitHub Actions.
# Homebrew
Goreleaser will automatically push a new commit to the
[Formula/go-task.rb][gotaskrb] file in the [Homebrew tap][homebrewtap]
repository to release the new version.
# npm
To release to npm update the version in the [`package.json`][packagejson] file
and then run `task npm:publish` to push it.
# Snapcraft
The [snap package][snappackage] requires to manual steps to release a new
version:
- Updating the current version on [snapcraft.yaml][snapcraftyaml].
- Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel
on the [Snapcraft dashboard][snapcraftdashboard].
# winget
winget also requires manual steps to be completed. By running
`task goreleaser:test` locally, manifest files will be generated on
`dist/winget/manifests/t/Task/Task/v{version}`.
[Upload the manifest directory into this fork](https://github.com/go-task/winget-pkgs/tree/master/manifests/t/Task/Task)
and open a pull request into
[this repository](https://github.com/microsoft/winget-pkgs).
# Scoop
Scoop is a command-line package manager for the Windows operating system. Scoop
package manifests are maintained by the community. Scoop owners usually take
care of updating versions there by editing
[this file](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json).
If you think its Task version is outdated, open an issue to let us know.
# Nix
Nix is a community owned installation method. Nix package maintainers usually
take care of updating versions there by editing
[this file](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/development/tools/go-task/default.nix).
If you think its Task version is outdated, open an issue to let us know.
<!-- prettier-ignore-start -->
[goreleaser]: https://goreleaser.com/
[homebrewtap]: https://github.com/go-task/homebrew-tap
[gotaskrb]: https://github.com/go-task/homebrew-tap/blob/main/Formula/go-task.rb
[packagejson]: https://github.com/go-task/task/blob/main/package.json#L3
[snappackage]: https://github.com/go-task/snap
[snapcraftyaml]: https://github.com/go-task/snap/blob/main/snap/snapcraft.yaml#L2
[snapcraftdashboard]: https://snapcraft.io/task/releases
<!-- prettier-ignore-end -->

227
docs/versioned_docs/version-latest/styleguide.md Normal file
View File

@ -0,0 +1,227 @@
---
slug: /styleguide/
sidebar_position: 10
---
# Style guide
This is the official style guide for `Taskfile.yml` files. It provides basic
instructions for keeping your Taskfiles clean and familiar to other users.
This guide contains general guidelines, but they do not necessarily need to be
followed strictly. Feel free to disagree and do things differently if you need
or want to. Any improvements to this guide are welcome! Please open an issue or
create a pull request to contribute.
## Use the suggested ordering of the main sections
```yaml
version:
includes:
# optional configurations (output, silent, method, run, etc.)
vars:
env: # followed or replaced by dotenv
tasks:
```
## Use two spaces for indentation
This is the most common convention for YAML files, and Task follows it.
```yaml
# bad
tasks:
foo:
cmds:
- echo 'foo'
# good
tasks:
foo:
cmds:
- echo 'foo'
```
## Separate the main sections with empty lines
```yaml
# bad
version: '3'
includes:
docker: ./docker/Taskfile.yml
output: prefixed
vars:
FOO: bar
env:
BAR: baz
tasks:
# ...
# good
version: '3'
includes:
docker: ./docker/Taskfile.yml
output: prefixed
vars:
FOO: bar
env:
BAR: baz
tasks:
# ...
```
## Separate tasks with empty lines
```yaml
# bad
version: '3'
tasks:
foo:
cmds:
- echo 'foo'
bar:
cmds:
- echo 'bar'
baz:
cmds:
- echo 'baz'
# good
version: '3'
tasks:
foo:
cmds:
- echo 'foo'
bar:
cmds:
- echo 'bar'
baz:
cmds:
- echo 'baz'
```
## Use only uppercase letters for variable names
```yaml
# bad
version: '3'
vars:
binary_name: myapp
tasks:
build:
cmds:
- go build -o {{.binary_name}} .
# good
version: '3'
vars:
BINARY_NAME: myapp
tasks:
build:
cmds:
- go build -o {{.BINARY_NAME}} .
```
## Avoid using whitespace when templating variables
```yaml
# bad
version: '3'
tasks:
greet:
cmds:
- echo '{{ .MESSAGE }}'
# good
version: '3'
tasks:
greet:
cmds:
- echo '{{.MESSAGE}}'
```
This convention is also commonly used in templates for the Go programming
language.
## Use kebab case for task names
```yaml
# bad
version: '3'
tasks:
do_something_fancy:
cmds:
- echo 'Do something'
# good
version: '3'
tasks:
do-something-fancy:
cmds:
- echo 'Do something'
```
## Use a colon to separate the task namespace and name
```yaml
# good
version: '3'
tasks:
docker:build:
cmds:
- docker ...
docker:run:
cmds:
- docker-compose ...
```
This is also done automatically when using included Taskfiles.
## Prefer using external scripts instead of multi-line commands
```yaml
# bad
version: '3'
tasks:
build:
cmds:
- |
for i in $(seq 1 10); do
echo $i
echo "some other complex logic"
done'
# good
version: '3'
tasks:
build:
cmds:
- ./scripts/my_complex_script.sh
```

263
docs/versioned_docs/version-latest/taskfile_versions.md Normal file
View File

@ -0,0 +1,263 @@
---
slug: /taskfile-versions/
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.
## What the Taskfile version mean
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:
```yaml
includes:
docs:
taskfile: ./docs
dir: ./docs
```
- Implemented short task syntax. All below syntaxes are equivalent:
```yaml
version: '3'
tasks:
print:
cmds:
- echo "Hello, World!"
```
```yaml
version: '3'
tasks:
print:
- echo "Hello, World!"
```
```yaml
version: '3'
tasks:
print: echo "Hello, World!"
```
- 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 2.6
:::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/
[output]: /usage#output-syntax
[ignore_errors]: /usage#ignore-errors
[includes]: /usage#including-other-taskfiles
<!-- prettier-ignore-end -->

22
docs/versioned_docs/version-latest/translate.md Normal file
View File

@ -0,0 +1,22 @@
---
slug: /translate/
sidebar_position: 12
---
# Translate
Want to help us translate this documentation? In this document we explain how.
Do NOT edit translated markdown files directly on the GitHub repository! We use
[Crowdin][crowdin] to allow contributors on work on translations. The repository
is periodically updated with progress from Crowdin.
If you want to have access to the Crowdin project to be able to suggest
translations, please ask for access on the [#translations channel on our Discord
server][discord]. If a given language is not being shown to Crowdin yet, just
ask and we can configure it.
<!-- prettier-ignore-start -->
[crowdin]: https://crowdin.com/project/taskfile
[discord]: https://discord.gg/6TY36E39UK
<!-- prettier-ignore-end -->

1922
docs/versioned_docs/version-latest/usage.md Normal file
View File

File diff suppressed because it is too large Load Diff

12
docs/versioned_sidebars/version-latest-sidebars.json Normal file
View File

@ -0,0 +1,12 @@
{
"taskSidebar": [
{
"type": "autogenerated",
"dirName": "."
},
{
"type": "html",
"value": "<div id=\"sidebar-ads\"></div>"
}
]
}

3
docs/versions.json Normal file
View File

@ -0,0 +1,3 @@
[
"latest"
]