diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 693cdd35..ba04caa5 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -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', diff --git a/docs/versioned_docs/version-latest/api_reference.md b/docs/versioned_docs/version-latest/api_reference.md new file mode 100644 index 00000000..a53b7cf6 --- /dev/null +++ b/docs/versioned_docs/version-latest/api_reference.md @@ -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.
`default` - Alphanumeric with root tasks first
`alphanumeric` - Alphanumeric
`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 | diff --git a/docs/versioned_docs/version-latest/changelog.md b/docs/versioned_docs/version-latest/changelog.md new file mode 100644 index 00000000..33701df7 --- /dev/null +++ b/docs/versioned_docs/version-latest/changelog.md @@ -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 diff --git a/docs/versioned_docs/version-latest/community.md b/docs/versioned_docs/version-latest/community.md new file mode 100644 index 00000000..8b944126 --- /dev/null +++ b/docs/versioned_docs/version-latest/community.md @@ -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. diff --git a/docs/versioned_docs/version-latest/contributing.md b/docs/versioned_docs/version-latest/contributing.md new file mode 100644 index 00000000..dbe15e6c --- /dev/null +++ b/docs/versioned_docs/version-latest/contributing.md @@ -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/ `. + +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. + +--- + + +[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 + diff --git a/docs/versioned_docs/version-latest/deprecations/deprecations.md b/docs/versioned_docs/version-latest/deprecations/deprecations.md new file mode 100644 index 00000000..aa5011a8 --- /dev/null +++ b/docs/versioned_docs/version-latest/deprecations/deprecations.md @@ -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. diff --git a/docs/versioned_docs/version-latest/deprecations/template.md b/docs/versioned_docs/version-latest/deprecations/template.md new file mode 100644 index 00000000..dee9802a --- /dev/null +++ b/docs/versioned_docs/version-latest/deprecations/template.md @@ -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\} diff --git a/docs/versioned_docs/version-latest/deprecations/version_2_schema.md b/docs/versioned_docs/version-latest/deprecations/version_2_schema.md new file mode 100644 index 00000000..7ed1b85d --- /dev/null +++ b/docs/versioned_docs/version-latest/deprecations/version_2_schema.md @@ -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]. + + +[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 + diff --git a/docs/versioned_docs/version-latest/donate.md b/docs/versioned_docs/version-latest/donate.md new file mode 100644 index 00000000..108a9250 --- /dev/null +++ b/docs/versioned_docs/version-latest/donate.md @@ -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¤cy_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). + + +[@andreynering]: https://github.com/andreynering + diff --git a/docs/versioned_docs/version-latest/experiments/any_variables.mdx b/docs/versioned_docs/version-latest/experiments/any_variables.mdx new file mode 100644 index 00000000..bb292e86 --- /dev/null +++ b/docs/versioned_docs/version-latest/experiments/any_variables.mdx @@ -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. + + + + + +:::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. + + + + + +:::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' +``` + + + +--- + +## 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. + + +[enabling-experiments]: /experiments/#enabling-experiments +[slim-sprig]: https://go-task.github.io/slim-sprig/ + diff --git a/docs/versioned_docs/version-latest/experiments/experiments.md b/docs/versioned_docs/version-latest/experiments/experiments.md new file mode 100644 index 00000000..8a665ce8 --- /dev/null +++ b/docs/versioned_docs/version-latest/experiments/experiments.md @@ -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. diff --git a/docs/versioned_docs/version-latest/experiments/gentle_force.md b/docs/versioned_docs/version-latest/experiments/gentle_force.md new file mode 100644 index 00000000..d468770c --- /dev/null +++ b/docs/versioned_docs/version-latest/experiments/gentle_force.md @@ -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! + + +[enabling-experiments]: /experiments/#enabling-experiments + diff --git a/docs/versioned_docs/version-latest/experiments/remote_taskfiles.md b/docs/versioned_docs/version-latest/experiments/remote_taskfiles.md new file mode 100644 index 00000000..40236509 --- /dev/null +++ b/docs/versioned_docs/version-latest/experiments/remote_taskfiles.md @@ -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. + + +[enabling-experiments]: /experiments/#enabling-experiments +[man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack + diff --git a/docs/versioned_docs/version-latest/experiments/template.md b/docs/versioned_docs/version-latest/experiments/template.md new file mode 100644 index 00000000..37ac9987 --- /dev/null +++ b/docs/versioned_docs/version-latest/experiments/template.md @@ -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\} + + +[enabling-experiments]: /experiments/#enabling-experiments + diff --git a/docs/versioned_docs/version-latest/faq.md b/docs/versioned_docs/version-latest/faq.md new file mode 100644 index 00000000..6a8a96e6 --- /dev/null +++ b/docs/versioned_docs/version-latest/faq.md @@ -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}}` 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) + + +[git-bash]: https://gitforwindows.org/ +[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install + diff --git a/docs/versioned_docs/version-latest/installation.md b/docs/versioned_docs/version-latest/installation.md new file mode 100644 index 00000000..c9fc489e --- /dev/null +++ b/docs/versioned_docs/version-latest/installation.md @@ -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 +``` + + +[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/ + diff --git a/docs/versioned_docs/version-latest/integrations.md b/docs/versioned_docs/version-latest/integrations.md new file mode 100644 index 00000000..2e15da29 --- /dev/null +++ b/docs/versioned_docs/version-latest/integrations.md @@ -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. diff --git a/docs/versioned_docs/version-latest/intro.md b/docs/versioned_docs/version-latest/intro.md new file mode 100644 index 00000000..72151db0 --- /dev/null +++ b/docs/versioned_docs/version-latest/intro.md @@ -0,0 +1,61 @@ +--- +slug: / +sidebar_position: 1 +title: Home +--- + +# Task + +
+ +
+ +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). + + +[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 + diff --git a/docs/versioned_docs/version-latest/releasing.md b/docs/versioned_docs/version-latest/releasing.md new file mode 100644 index 00000000..0db6ef8b --- /dev/null +++ b/docs/versioned_docs/version-latest/releasing.md @@ -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. + + +[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 + diff --git a/docs/versioned_docs/version-latest/styleguide.md b/docs/versioned_docs/version-latest/styleguide.md new file mode 100644 index 00000000..eaab37cc --- /dev/null +++ b/docs/versioned_docs/version-latest/styleguide.md @@ -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 +``` diff --git a/docs/versioned_docs/version-latest/taskfile_versions.md b/docs/versioned_docs/version-latest/taskfile_versions.md new file mode 100644 index 00000000..989e17c2 --- /dev/null +++ b/docs/versioned_docs/version-latest/taskfile_versions.md @@ -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 + + +[deprecate-version-2-schema]: /deprecations/version-2-schema/ +[output]: /usage#output-syntax +[ignore_errors]: /usage#ignore-errors +[includes]: /usage#including-other-taskfiles + diff --git a/docs/versioned_docs/version-latest/translate.md b/docs/versioned_docs/version-latest/translate.md new file mode 100644 index 00000000..47f39b35 --- /dev/null +++ b/docs/versioned_docs/version-latest/translate.md @@ -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. + + +[crowdin]: https://crowdin.com/project/taskfile +[discord]: https://discord.gg/6TY36E39UK + diff --git a/docs/versioned_docs/version-latest/usage.md b/docs/versioned_docs/version-latest/usage.md new file mode 100644 index 00000000..7d1f1d73 --- /dev/null +++ b/docs/versioned_docs/version-latest/usage.md @@ -0,0 +1,1922 @@ +--- +slug: /usage/ +sidebar_position: 3 +--- + +# Usage + +## Getting started + +Create a file called `Taskfile.yml` in the root of your project. The `cmds` +attribute should contain the commands of a task. The example below allows +compiling a Go app and uses [esbuild](https://esbuild.github.io/) to concat and +minify multiple CSS files into a single one. + +```yaml +version: '3' + +tasks: + build: + cmds: + - go build -v -i main.go + + assets: + cmds: + - esbuild --bundle --minify css/index.css > public/bundle.css +``` + +Running the tasks is as simple as running: + +```shell +task assets build +``` + +Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh interpreter. So +you can write sh/bash commands, and it will work even on Windows, where `sh` or +`bash` are usually not available. Just remember any executable called must be +available by the OS or in PATH. + +If you omit a task name, "default" will be assumed. + +## Supported file names + +Task will look for the following file names, in order of priority: + +- Taskfile.yml +- taskfile.yml +- Taskfile.yaml +- taskfile.yaml +- Taskfile.dist.yml +- taskfile.dist.yml +- Taskfile.dist.yaml +- taskfile.dist.yaml + +The intention of having the `.dist` variants is to allow projects to have one +committed version (`.dist`) while still allowing individual users to override +the Taskfile by adding an additional `Taskfile.yml` (which would be on +`.gitignore`). + +### Running a Taskfile from a subdirectory + +If a Taskfile cannot be found in the current working directory, it will walk up +the file tree until it finds one (similar to how `git` works). When running Task +from a subdirectory like this, it will behave as if you ran it from the +directory containing the Taskfile. + +You can use this functionality along with the special `{{.USER_WORKING_DIR}}` +variable to create some very useful reusable tasks. For example, if you have a +monorepo with directories for each microservice, you can `cd` into a +microservice directory and run a task command to bring it up without having to +create multiple tasks or Taskfiles with identical content. For example: + +```yaml +version: '3' + +tasks: + up: + dir: '{{.USER_WORKING_DIR}}' + preconditions: + - test -f docker-compose.yml + cmds: + - docker-compose up -d +``` + +In this example, we can run `cd ` and `task up` and as long as the +`` directory contains a `docker-compose.yml`, the Docker composition +will be brought up. + +### Running a global Taskfile + +If you call Task with the `--global` (alias `-g`) flag, it will look for your +home directory instead of your working directory. In short, Task will look for a +Taskfile that matches `$HOME/{T,t}askfile.{yml,yaml}` . + +This is useful to have automation that you can run from anywhere in your system! + +:::info + +When running your global Taskfile with `-g`, tasks will run on `$HOME` by +default, and not on your working directory! + +As mentioned in the previous section, the `{{.USER_WORKING_DIR}}` special +variable can be very handy here to run stuff on the directory you're calling +`task -g` from. + +```yaml +version: '3' + +tasks: + from-home: + cmds: + - pwd + + from-working-directory: + dir: '{{.USER_WORKING_DIR}}' + cmds: + - pwd +``` + +::: + +### Reading a Taskfile from stdin + +Taskfile also supports reading from stdin. This is useful if you are generating +Taskfiles dynamically and don't want write them to disk. This works just like +any other program that supports stdin. For example: + +```shell +task < <(cat ./Taskfile.yml) +# OR +cat ./Taskfile.yml | task +``` + +## Environment variables + +### Task + +You can use `env` to set custom environment variables for a specific task: + +```yaml +version: '3' + +tasks: + greet: + cmds: + - echo $GREETING + env: + GREETING: Hey, there! +``` + +Additionally, you can set global environment variables that will be available to +all tasks: + +```yaml +version: '3' + +env: + GREETING: Hey, there! + +tasks: + greet: + cmds: + - echo $GREETING +``` + +:::info + +`env` supports expansion and retrieving output from a shell command just like +variables, as you can see in the [Variables](#variables) section. + +::: + +### .env files + +You can also ask Task to include `.env` like files by using the `dotenv:` +setting: + +```shell title=".env" +KEYNAME=VALUE +``` + +```shell title="testing/.env" +ENDPOINT=testing.com +``` + +```yaml title="Taskfile.yml" +version: '3' + +env: + ENV: testing + +dotenv: ['.env', '{{.ENV}}/.env.', '{{.HOME}}/.env'] + +tasks: + greet: + cmds: + - echo "Using $KEYNAME and endpoint $ENDPOINT" +``` + +Dotenv files can also be specified at the task level: + +```yaml +version: '3' + +env: + ENV: testing + +tasks: + greet: + dotenv: ['.env', '{{.ENV}}/.env.', '{{.HOME}}/.env'] + cmds: + - echo "Using $KEYNAME and endpoint $ENDPOINT" +``` + +Environment variables specified explicitly at the task-level will override +variables defined in dotfiles: + +```yaml +version: '3' + +env: + ENV: testing + +tasks: + greet: + dotenv: ['.env', '{{.ENV}}/.env.', '{{.HOME}}/.env'] + env: + KEYNAME: DIFFERENT_VALUE + cmds: + - echo "Using $KEYNAME and endpoint $ENDPOINT" +``` + +:::info + +Please note that you are not currently able to use the `dotenv` key inside +included Taskfiles. + +::: + +## Including other Taskfiles + +If you want to share tasks between different projects (Taskfiles), you can use +the importing mechanism to include other Taskfiles using the `includes` keyword: + +```yaml +version: '3' + +includes: + docs: ./documentation # will look for ./documentation/Taskfile.yml + docker: ./DockerTasks.yml +``` + +The tasks described in the given Taskfiles will be available with the informed +namespace. So, you'd call `task docs:serve` to run the `serve` task from +`documentation/Taskfile.yml` or `task docker:build` to run the `build` task from +the `DockerTasks.yml` file. + +Relative paths are resolved relative to the directory containing the including +Taskfile. + +### OS-specific Taskfiles + +With `version: '2'`, task automatically includes any `Taskfile_{{OS}}.yml` if it +exists (for example: `Taskfile_windows.yml`, `Taskfile_linux.yml` or +`Taskfile_darwin.yml`). Since this behavior was a bit too implicit, it was +removed on version 3, but you still can have a similar behavior by explicitly +importing these files: + +```yaml +version: '3' + +includes: + build: ./Taskfile_{{OS}}.yml +``` + +### Directory of included Taskfile + +By default, included Taskfile's tasks are run in the current directory, even if +the Taskfile is in another directory, but you can force its tasks to run in +another directory by using this alternative syntax: + +```yaml +version: '3' + +includes: + docs: + taskfile: ./docs/Taskfile.yml + dir: ./docs +``` + +:::info + +The included Taskfiles must be using the same schema version as the main +Taskfile uses. + +::: + +### Optional includes + +Includes marked as optional will allow Task to continue execution as normal if +the included file is missing. + +```yaml +version: '3' + +includes: + tests: + taskfile: ./tests/Taskfile.yml + optional: true + +tasks: + greet: + cmds: + - echo "This command can still be successfully executed if + ./tests/Taskfile.yml does not exist" +``` + +### Internal includes + +Includes marked as internal will set all the tasks of the included file to be +internal as well (see the [Internal tasks](#internal-tasks) section below). This +is useful when including utility tasks that are not intended to be used directly +by the user. + +```yaml +version: '3' + +includes: + tests: + taskfile: ./taskfiles/Utils.yml + internal: true +``` + +### Vars of included Taskfiles + +You can also specify variables when including a Taskfile. This may be useful for +having reusable Taskfile that can be tweaked or even included more than once: + +```yaml +version: '3' + +includes: + backend: + taskfile: ./taskfiles/Docker.yml + vars: + DOCKER_IMAGE: backend_image + + frontend: + taskfile: ./taskfiles/Docker.yml + vars: + DOCKER_IMAGE: frontend_image +``` + +### Namespace aliases + +When including a Taskfile, you can give the namespace a list of `aliases`. This +works in the same way as [task aliases](#task-aliases) and can be used together +to create shorter and easier-to-type commands. + +```yaml +version: '3' + +includes: + generate: + taskfile: ./taskfiles/Generate.yml + aliases: [gen] +``` + +:::info + +Vars declared in the included Taskfile have preference over the variables in the +including Taskfile! If you want a variable in an included Taskfile to be +overridable, use the +[default function](https://go-task.github.io/slim-sprig/defaults.html): +`MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`. + +::: + +## Internal tasks + +Internal tasks are tasks that cannot be called directly by the user. They will +not appear in the output when running `task --list|--list-all`. Other tasks may +call internal tasks in the usual way. This is useful for creating reusable, +function-like tasks that have no useful purpose on the command line. + +```yaml +version: '3' + +tasks: + build-image-1: + cmds: + - task: build-image + vars: + DOCKER_IMAGE: image-1 + + build-image: + internal: true + cmds: + - docker build -t {{.DOCKER_IMAGE}} . +``` + +## Task directory + +By default, tasks will be executed in the directory where the Taskfile is +located. But you can easily make the task run in another folder, informing +`dir`: + +```yaml +version: '3' + +tasks: + serve: + dir: public/www + cmds: + # run http server + - caddy +``` + +If the directory does not exist, `task` creates it. + +## Task dependencies + +> Dependencies run in parallel, so dependencies of a task should not depend one +> another. If you want to force tasks to run serially, take a look at the +> [Calling Another Task](#calling-another-task) section below. + +You may have tasks that depend on others. Just pointing them on `deps` will make +them run automatically before running the parent task: + +```yaml +version: '3' + +tasks: + build: + deps: [assets] + cmds: + - go build -v -i main.go + + assets: + cmds: + - esbuild --bundle --minify css/index.css > public/bundle.css +``` + +In the above example, `assets` will always run right before `build` if you run +`task build`. + +A task can have only dependencies and no commands to group tasks together: + +```yaml +version: '3' + +tasks: + assets: + deps: [js, css] + + js: + cmds: + - esbuild --bundle --minify js/index.js > public/bundle.js + + css: + cmds: + - esbuild --bundle --minify css/index.css > public/bundle.css +``` + +If there is more than one dependency, they always run in parallel for better +performance. + +:::tip + +You can also make the tasks given by the command line run in parallel by using +the `--parallel` flag (alias `-p`). Example: `task --parallel js css`. + +::: + +If you want to pass information to dependencies, you can do that the same manner +as you would to [call another task](#calling-another-task): + +```yaml +version: '3' + +tasks: + default: + deps: + - task: echo_sth + vars: { TEXT: 'before 1' } + - task: echo_sth + vars: { TEXT: 'before 2' } + silent: true + cmds: + - echo "after" + + echo_sth: + cmds: + - echo {{.TEXT}} +``` + +## Platform specific tasks and commands + +If you want to restrict the running of tasks to explicit platforms, this can be +achieved using the `platforms:` key. Tasks can be restricted to a specific OS, +architecture or a combination of both. On a mismatch, the task or command will +be skipped, and no error will be thrown. + +The values allowed as OS or Arch are valid `GOOS` and `GOARCH` values, as +defined by the Go language +[here](https://github.com/golang/go/blob/master/src/go/build/syslist.go). + +The `build-windows` task below will run only on Windows, and on any +architecture: + +```yaml +version: '3' + +tasks: + build-windows: + platforms: [windows] + cmds: + - echo 'Running command on Windows' +``` + +This can be restricted to a specific architecture as follows: + +```yaml +version: '3' + +tasks: + build-windows-amd64: + platforms: [windows/amd64] + cmds: + - echo 'Running command on Windows (amd64)' +``` + +It is also possible to restrict the task to specific architectures: + +```yaml +version: '3' + +tasks: + build-amd64: + platforms: [amd64] + cmds: + - echo 'Running command on amd64' +``` + +Multiple platforms can be specified as follows: + +```yaml +version: '3' + +tasks: + build: + platforms: [windows/amd64, darwin] + cmds: + - echo 'Running command on Windows (amd64) and macOS' +``` + +Individual commands can also be restricted to specific platforms: + +```yaml +version: '3' + +tasks: + build: + cmds: + - cmd: echo 'Running command on Windows (amd64) and macOS' + platforms: [windows/amd64, darwin] + - cmd: echo 'Running on all platforms' +``` + +## Calling another task + +When a task has many dependencies, they are executed concurrently. This will +often result in a faster build pipeline. However, in some situations, you may +need to call other tasks serially. In this case, use the following syntax: + +```yaml +version: '3' + +tasks: + main-task: + cmds: + - task: task-to-be-called + - task: another-task + - echo "Both done" + + task-to-be-called: + cmds: + - echo "Task to be called" + + another-task: + cmds: + - echo "Another task" +``` + +Using the `vars` and `silent` attributes you can choose to pass variables and +toggle [silent mode](#silent-mode) on a call-by-call basis: + +```yaml +version: '3' + +tasks: + greet: + vars: + RECIPIENT: '{{default "World" .RECIPIENT}}' + cmds: + - echo "Hello, {{.RECIPIENT}}!" + + greet-pessimistically: + cmds: + - task: greet + vars: { RECIPIENT: 'Cruel World' } + silent: true +``` + +The above syntax is also supported in `deps`. + +:::tip + +NOTE: If you want to call a task declared in the root Taskfile from within an +[included Taskfile](#including-other-taskfiles), add a leading `:` like this: +`task: :task-name`. + +::: + +## Prevent unnecessary work + +### By fingerprinting locally generated files and their sources + +If a task generates something, you can inform Task the source and generated +files, so Task will prevent running them if not necessary. + +```yaml +version: '3' + +tasks: + build: + deps: [js, css] + cmds: + - go build -v -i main.go + + js: + cmds: + - esbuild --bundle --minify js/index.js > public/bundle.js + sources: + - src/js/**/*.js + generates: + - public/bundle.js + + css: + cmds: + - esbuild --bundle --minify css/index.css > public/bundle.css + sources: + - src/css/**/*.css + generates: + - public/bundle.css +``` + +`sources` and `generates` can be files or glob patterns. When given, Task will +compare the checksum of the source files to determine if it's necessary to run +the task. If not, it will just print a message like `Task "js" is up to date`. + +`exclude:` can also be used to exclude files from fingerprinting. Sources are +evaluated in order, so `exclude:` must come after the positive glob it is +negating. + +```yaml +version: '3' + +tasks: + css: + sources: + - mysources/**/*.css + - exclude: mysources/ignoreme.css + generates: + - public/bundle.css +``` + +If you prefer these check to be made by the modification timestamp of the files, +instead of its checksum (content), just set the `method` property to +`timestamp`. + +```yaml +version: '3' + +tasks: + build: + cmds: + - go build . + sources: + - ./*.go + generates: + - app{{exeExt}} + method: timestamp +``` + +In situations where you need more flexibility the `status` keyword can be used. +You can even combine the two. See the documentation for +[status](#using-programmatic-checks-to-indicate-a-task-is-up-to-date) for an +example. + +:::info + +By default, task stores checksums on a local `.task` directory in the project's +directory. Most of the time, you'll want to have this directory on `.gitignore` +(or equivalent) so it isn't committed. (If you have a task for code generation +that is committed it may make sense to commit the checksum of that task as well, +though). + +If you want these files to be stored in another directory, you can set a +`TASK_TEMP_DIR` environment variable in your machine. It can contain a relative +path like `tmp/task` that will be interpreted as relative to the project +directory, or an absolute or home path like `/tmp/.task` or `~/.task` +(subdirectories will be created for each project). + +```shell +export TASK_TEMP_DIR='~/.task' +``` + +::: + +:::info + +Each task has only one checksum stored for its `sources`. If you want to +distinguish a task by any of its input variables, you can add those variables as +part of the task's label, and it will be considered a different task. + +This is useful if you want to run a task once for each distinct set of inputs +until the sources actually change. For example, if the sources depend on the +value of a variable, or you if you want the task to rerun if some arguments +change even if the source has not. + +::: + +:::tip + +The method `none` skips any validation and always run the task. + +::: + +:::info + +For the `checksum` (default) or `timestamp` method to work, it is only necessary +to inform the source files. When the `timestamp` method is used, the last time +of the running the task is considered as a generate. + +::: + +### Using programmatic checks to indicate a task is up to date + +Alternatively, you can inform a sequence of tests as `status`. If no error is +returned (exit status 0), the task is considered up-to-date: + +```yaml +version: '3' + +tasks: + generate-files: + cmds: + - mkdir directory + - touch directory/file1.txt + - touch directory/file2.txt + # test existence of files + status: + - test -d directory + - test -f directory/file1.txt + - test -f directory/file2.txt +``` + +Normally, you would use `sources` in combination with `generates` - but for +tasks that generate remote artifacts (Docker images, deploys, CD releases) the +checksum source and timestamps require either access to the artifact or for an +out-of-band refresh of the `.checksum` fingerprint file. + +Two special variables `{{.CHECKSUM}}` and `{{.TIMESTAMP}}` are available for +interpolation within `status` commands, depending on the method assigned to +fingerprint the sources. Only `source` globs are fingerprinted. + +Note that the `{{.TIMESTAMP}}` variable is a "live" Go `time.Time` struct, and +can be formatted using any of the methods that `time.Time` responds to. + +See [the Go Time documentation](https://golang.org/pkg/time/) for more +information. + +You can use `--force` or `-f` if you want to force a task to run even when +up-to-date. + +Also, `task --status [tasks]...` will exit with a non-zero exit code if any of +the tasks are not up-to-date. + +`status` can be combined with the +[fingerprinting](#by-fingerprinting-locally-generated-files-and-their-sources) +to have a task run if either the the source/generated artifacts changes, or the +programmatic check fails: + +```yaml +version: '3' + +tasks: + build:prod: + desc: Build for production usage. + cmds: + - composer install + # Run this task if source files changes. + sources: + - composer.json + - composer.lock + generates: + - ./vendor/composer/installed.json + - ./vendor/autoload.php + # But also run the task if the last build was not a production build. + status: + - grep -q '"dev": false' ./vendor/composer/installed.json +``` + +### Using programmatic checks to cancel the execution of a task and its dependencies + +In addition to `status` checks, `preconditions` checks are the logical inverse +of `status` checks. That is, if you need a certain set of conditions to be +_true_ you can use the `preconditions` stanza. `preconditions` are similar to +`status` lines, except they support `sh` expansion, and they SHOULD all +return 0. + +```yaml +version: '3' + +tasks: + generate-files: + cmds: + - mkdir directory + - touch directory/file1.txt + - touch directory/file2.txt + # test existence of files + preconditions: + - test -f .env + - sh: '[ 1 = 0 ]' + msg: "One doesn't equal Zero, Halting" +``` + +Preconditions can set specific failure messages that can tell a user what steps +to take using the `msg` field. + +If a task has a dependency on a sub-task with a precondition, and that +precondition is not met - the calling task will fail. Note that a task executed +with a failing precondition will not run unless `--force` is given. + +Unlike `status`, which will skip a task if it is up to date and continue +executing tasks that depend on it, a `precondition` will fail a task, along with +any other tasks that depend on it. + +```yaml +version: '3' + +tasks: + task-will-fail: + preconditions: + - sh: 'exit 1' + + task-will-also-fail: + deps: + - task-will-fail + + task-will-still-fail: + cmds: + - task: task-will-fail + - echo "I will not run" +``` + +### Limiting when tasks run + +If a task executed by multiple `cmds` or multiple `deps` you can control when it +is executed using `run`. `run` can also be set at the root of the Taskfile to +change the behavior of all the tasks unless explicitly overridden. + +Supported values for `run`: + +- `always` (default) always attempt to invoke the task regardless of the number + of previous executions +- `once` only invoke this task once regardless of the number of references +- `when_changed` only invokes the task once for each unique set of variables + passed into the task + +```yaml +version: '3' + +tasks: + default: + cmds: + - task: generate-file + vars: { CONTENT: '1' } + - task: generate-file + vars: { CONTENT: '2' } + - task: generate-file + vars: { CONTENT: '2' } + + generate-file: + run: when_changed + deps: + - install-deps + cmds: + - echo {{.CONTENT}} + + install-deps: + run: once + cmds: + - sleep 5 # long operation like installing packages +``` + +### Ensuring required variables are set + +If you want to check that certain variables are set before running a task then +you can use `requires`. This is useful when might not be clear to users which +variables are needed, or if you want clear message about what is required. Also +some tasks could have dangerous side effects if run with un-set variables. + +Using `requires` you specify an array of strings in the `vars` sub-section under +`requires`, these strings are variable names which are checked prior to running +the task. If any variables are un-set the the task will error and not run. + +Environmental variables are also checked. + +Syntax: + +```yaml +requires: + vars: [] # Array of strings +``` + +:::note + +Variables set to empty zero length strings, will pass the `requires` check. + +::: + +Example of using `requires`: + +```yaml +version: '3' + +tasks: + docker-build: + cmds: + - 'docker build . -t {{.IMAGE_NAME}}:{{.IMAGE_TAG}}' + + # Make sure these variables are set before running + requires: + vars: [IMAGE_NAME, IMAGE_TAG] +``` + +## Variables + +When doing interpolation of variables, Task will look for the below. They are +listed below in order of importance (i.e. most important first): + +- Variables declared in the task definition +- Variables given while calling a task from another (See + [Calling another task](#calling-another-task) above) +- Variables of the [included Taskfile](#including-other-taskfiles) (when the + task is included) +- Variables of the [inclusion of the Taskfile](#vars-of-included-taskfiles) + (when the task is included) +- Global variables (those declared in the `vars:` option in the Taskfile) +- Environment variables + +Example of sending parameters with environment variables: + +```shell +$ TASK_VARIABLE=a-value task do-something +``` + +:::tip + +A special variable `.TASK` is always available containing the task name. + +::: + +Since some shells do not support the above syntax to set environment variables +(Windows) tasks also accept a similar style when not at the beginning of the +command. + +```shell +$ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!" +``` + +Example of locally declared vars: + +```yaml +version: '3' + +tasks: + print-var: + cmds: + - echo "{{.VAR}}" + vars: + VAR: Hello! +``` + +Example of global vars in a `Taskfile.yml`: + +```yaml +version: '3' + +vars: + GREETING: Hello from Taskfile! + +tasks: + greet: + cmds: + - echo "{{.GREETING}}" +``` + +### Dynamic variables + +The below syntax (`sh:` prop in a variable) is considered a dynamic variable. +The value will be treated as a command and the output assigned. If there are one +or more trailing newlines, the last newline will be trimmed. + +```yaml +version: '3' + +tasks: + build: + cmds: + - go build -ldflags="-X main.Version={{.GIT_COMMIT}}" main.go + vars: + GIT_COMMIT: + sh: git log -n 1 --format=%h +``` + +This works for all types of variables. + +## Looping over values + +As of v3.28.0, Task allows you to loop over certain values and execute a command +for each. There are a number of ways to do this depending on the type of value +you want to loop over. + +### Looping over a static list + +The simplest kind of loop is an explicit one. This is useful when you want to +loop over a set of values that are known ahead of time. + +```yaml +version: '3' + +tasks: + default: + cmds: + - for: ['foo.txt', 'bar.txt'] + cmd: cat {{ .ITEM }} +``` + +### Looping over your task's sources + +You are also able to loop over the sources of your task: + +```yaml +version: '3' + +tasks: + default: + sources: + - foo.txt + - bar.txt + cmds: + - for: sources + cmd: cat {{ .ITEM }} +``` + +This will also work if you use globbing syntax in your sources. For example, if +you specify a source for `*.txt`, the loop will iterate over all files that +match that glob. + +Source paths will always be returned as paths relative to the task directory. If +you need to convert this to an absolute path, you can use the built-in +`joinPath` function. There are some [special variables](/api/#special-variables) +that you may find useful for this. + +```yaml +version: '3' + +tasks: + default: + vars: + MY_DIR: /path/to/dir + dir: '{{.MY_DIR}}' + sources: + - foo.txt + - bar.txt + cmds: + - for: sources + cmd: cat {{joinPath .MY_DIR .ITEM}} +``` + +### Looping over variables + +To loop over the contents of a variable, you simply need to specify the variable +you want to loop over. By default, variables will be split on any whitespace +characters. + +```yaml +version: '3' + +tasks: + default: + vars: + MY_VAR: foo.txt bar.txt + cmds: + - for: { var: MY_VAR } + cmd: cat {{.ITEM}} +``` + +If you need to split on a different character, you can do this by specifying the +`split` property: + +```yaml +version: '3' + +tasks: + default: + vars: + MY_VAR: foo.txt,bar.txt + cmds: + - for: { var: MY_VAR, split: ',' } + cmd: cat {{.ITEM}} +``` + +All of this also works with dynamic variables! + +```yaml +version: '3' + +tasks: + default: + vars: + MY_VAR: + sh: find -type f -name '*.txt' + cmds: + - for: { var: MY_VAR } + cmd: cat {{.ITEM}} +``` + +### Renaming variables + +If you want to rename the iterator variable to make it clearer what the value +contains, you can do so by specifying the `as` property: + +```yaml +version: '3' + +tasks: + default: + vars: + MY_VAR: foo.txt bar.txt + cmds: + - for: { var: MY_VAR, as: FILE } + cmd: cat {{.FILE}} +``` + +### Looping over tasks + +Because the `for` property is defined at the `cmds` level, you can also use it +alongside the `task` keyword to run tasks multiple times with different +variables. + +```yaml +version: '3' + +tasks: + default: + cmds: + - for: [foo, bar] + task: my-task + vars: + FILE: '{{.ITEM}}' + + my-task: + cmds: + - echo '{{.FILE}}' +``` + +Or if you want to run different tasks depending on the value of the loop: + +```yaml +version: '3' + +tasks: + default: + cmds: + - for: [foo, bar] + task: task-{{.ITEM}} + + task-foo: + cmds: + - echo 'foo' + + task-bar: + cmds: + - echo 'bar' +``` + +## Forwarding CLI arguments to commands + +If `--` is given in the CLI, all following parameters are added to a special +`.CLI_ARGS` variable. This is useful to forward arguments to another command. + +The below example will run `yarn install`. + +```shell +$ task yarn -- install +``` + +```yaml +version: '3' + +tasks: + yarn: + cmds: + - yarn {{.CLI_ARGS}} +``` + +## Wildcard arguments + +Another way to parse arguments into a task is to use a wildcard in your task's +name. Wildcards are denoted by an asterisk (`*`) and can be used multiple times +in a task's name to pass in multiple arguments. + +Matching arguments will be captured and stored in the `.MATCH` variable and can +then be used in your task's commands like any other variable. This variable is +an array of strings and so will need to be indexed to access the individual +arguments. We suggest creating a named variable for each argument to make it +clear what they contain: + +```yaml +version: '3' + +tasks: + echo-*: + vars: + TEXT: '{{index .MATCH 0}}' + cmds: + - echo {{.TEXT}} + + run-*-*: + vars: + ARG_1: '{{index .MATCH 0}}' + ARG_2: '{{index .MATCH 1}}' + cmds: + - echo {{.ARG_1}} {{.ARG_2}} +``` + +```shell +# This call matches the "echo-*" task and the string "hello" is captured by the +# wildcard and stored in the .MATCH variable. We then index the .MATCH array and +# store the result in the .TEXT variable which is then echoed out in the cmds. +$ task echo-hello +hello +# You can use whitespace in your arguments as long as you quote the task name +$ task "echo-hello world" +hello world +# And you can pass multiple arguments +$ task run-foo-bar +foo bar +``` + +If multiple matching tasks are found, an error occurs. If you are using included +Taskfiles, tasks in parent files will be considered first. + +## Doing task cleanup with `defer` + +With the `defer` keyword, it's possible to schedule cleanup to be run once the +task finishes. The difference with just putting it as the last command is that +this command will run even when the task fails. + +In the example below, `rm -rf tmpdir/` will run even if the third command fails: + +```yaml +version: '3' + +tasks: + default: + cmds: + - mkdir -p tmpdir/ + - defer: rm -rf tmpdir/ + - echo 'Do work on tmpdir/' +``` + +If you want to move the cleanup command into another task, that is possible as +well: + +```yaml +version: '3' + +tasks: + default: + cmds: + - mkdir -p tmpdir/ + - defer: { task: cleanup } + - echo 'Do work on tmpdir/' + + cleanup: rm -rf tmpdir/ +``` + +:::info + +Due to the nature of how the +[Go's own `defer` work](https://go.dev/tour/flowcontrol/13), the deferred +commands are executed in the reverse order if you schedule multiple of them. + +::: + +## Go's template engine + +Task parse commands as [Go's template engine][gotemplate] before executing them. +Variables are accessible through dot syntax (`.VARNAME`). + +All functions by the Go's +[slim-sprig lib](https://go-task.github.io/slim-sprig/) are available. The +following example gets the current date in a given format: + +```yaml +version: '3' + +tasks: + print-date: + cmds: + - echo {{now | date "2006-01-02"}} +``` + +Task also adds the following functions: + +- `OS`: Returns the operating system. Possible values are `windows`, `linux`, + `darwin` (macOS) and `freebsd`. +- `ARCH`: return the architecture Task was compiled to: `386`, `amd64`, `arm` or + `s390x`. +- `splitLines`: Splits Unix (`\n`) and Windows (`\r\n`) styled newlines. +- `catLines`: Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a + space. +- `toSlash`: Does nothing on Unix, but on Windows converts a string from `\` + path format to `/`. +- `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows + converts a string from `/` path format to `\`. +- `exeExt`: Returns the right executable extension for the current OS (`".exe"` + for Windows, `""` for others). +- `shellQuote`: Quotes a string to make it safe for use in shell scripts. Task + uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote) + for this. The Bash dialect is assumed. +- `splitArgs`: Splits a string as if it were a command's arguments. Task uses + [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields) +- `joinPath`: Joins any number of arguments into a path. The same as Go's + [filepath.Join](https://pkg.go.dev/path/filepath#Join). +- `relPath`: Converts an absolute path (second argument) into a relative path, + based on a base path (first argument). The same as Go's + [filepath.Rel](https://pkg.go.dev/path/filepath#Rel). +- `merge`: Creates a new map that is a copy of the first map with the keys of + each subsequent map merged into it. If there is a duplicate key, the value of + the last map with that key is used. +- `spew`: Returns the Go representation of a specific variable. Useful for + debugging. Uses the [davecgh/go-spew](https://github.com/davecgh/go-spew) + package. + +Example: + +```yaml +version: '3' + +tasks: + print-os: + cmds: + - echo '{{OS}} {{ARCH}}' + - echo '{{if eq OS "windows"}}windows-command{{else}}unix-command{{end}}' + # This will be path/to/file on Unix but path\to\file on Windows + - echo '{{fromSlash "path/to/file"}}' + enumerated-file: + vars: + CONTENT: | + foo + bar + cmds: + - | + cat << EOF > output.txt + {{range $i, $line := .CONTENT | splitLines -}} + {{printf "%3d" $i}}: {{$line}} + {{end}}EOF +``` + +## Help + +Running `task --list` (or `task -l`) lists all tasks with a description. The +following Taskfile: + +```yaml +version: '3' + +tasks: + build: + desc: Build the go binary. + cmds: + - go build -v -i main.go + + test: + desc: Run all the go tests. + cmds: + - go test -race ./... + + js: + cmds: + - esbuild --bundle --minify js/index.js > public/bundle.js + + css: + cmds: + - esbuild --bundle --minify css/index.css > public/bundle.css +``` + +would print the following output: + +```shell +* build: Build the go binary. +* test: Run all the go tests. +``` + +If you want to see all tasks, there's a `--list-all` (alias `-a`) flag as well. + +## Display summary of task + +Running `task --summary task-name` will show a summary of a task. The following +Taskfile: + +```yaml +version: '3' + +tasks: + release: + deps: [build] + summary: | + Release your project to github + + It will build your project before starting the release. + Please make sure that you have set GITHUB_TOKEN before starting. + cmds: + - your-release-tool + + build: + cmds: + - your-build-tool +``` + +with running `task --summary release` would print the following output: + +``` +task: release + +Release your project to github + +It will build your project before starting the release. +Please make sure that you have set GITHUB_TOKEN before starting. + +dependencies: + - build + +commands: + - your-release-tool +``` + +If a summary is missing, the description will be printed. If the task does not +have a summary or a description, a warning is printed. + +Please note: _showing the summary will not execute the command_. + +## Task aliases + +Aliases are alternative names for tasks. They can be used to make it easier and +quicker to run tasks with long or hard-to-type names. You can use them on the +command line, when [calling sub-tasks](#calling-another-task) in your Taskfile +and when [including tasks](#including-other-taskfiles) with aliases from another +Taskfile. They can also be used together with +[namespace aliases](#namespace-aliases). + +```yaml +version: '3' + +tasks: + generate: + aliases: [gen] + cmds: + - task: gen-mocks + + generate-mocks: + aliases: [gen-mocks] + cmds: + - echo "generating..." +``` + +## Overriding task name + +Sometimes you may want to override the task name printed on the summary, +up-to-date messages to STDOUT, etc. In this case, you can just set `label:`, +which can also be interpolated with variables: + +```yaml +version: '3' + +tasks: + default: + - task: print + vars: + MESSAGE: hello + - task: print + vars: + MESSAGE: world + + print: + label: 'print-{{.MESSAGE}}' + cmds: + - echo "{{.MESSAGE}}" +``` + +## Warning Prompts + +Warning Prompts are used to prompt a user for confirmation before a task is +executed. + +Below is an example using `prompt` with a dangerous command, that is called +between two safe commands: + +```yaml +version: '3' + +tasks: + example: + cmds: + - task: not-dangerous + - task: dangerous + - task: another-not-dangerous + + not-dangerous: + cmds: + - echo 'not dangerous command' + + another-not-dangerous: + cmds: + - echo 'another not dangerous command' + + dangerous: + prompt: This is a dangerous command... Do you want to continue? + cmds: + - echo 'dangerous command' +``` + +```shell +❯ task dangerous +task: "This is a dangerous command... Do you want to continue?" [y/N] +``` + +Warning prompts are called before executing a task. If a prompt is denied Task +will exit with [exit code](/api#exit-codes) 205. If approved, Task will continue +as normal. + +```shell +❯ task example +not dangerous command +task: "This is a dangerous command. Do you want to continue?" [y/N] +y +dangerous command +another not dangerous command +``` + +To skip warning prompts automatically, you can use the `--yes` (alias `-y`) +option when calling the task. By including this option, all warnings, will be +automatically confirmed, and no prompts will be shown. + +:::caution + +Tasks with prompts always fail by default on non-terminal environments, like a +CI, where an `stdin` won't be available for the user to answer. In those cases, +use `--yes` (`-y`) to force all tasks with a prompt to run. + +::: + +## Silent mode + +Silent mode disables the echoing of commands before Task runs it. For the +following Taskfile: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - echo "Print something" +``` + +Normally this will be printed: + +```shell +echo "Print something" +Print something +``` + +With silent mode on, the below will be printed instead: + +```shell +Print something +``` + +There are four ways to enable silent mode: + +- At command level: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - cmd: echo "Print something" + silent: true +``` + +- At task level: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - echo "Print something" + silent: true +``` + +- Globally at Taskfile level: + +```yaml +version: '3' + +silent: true + +tasks: + echo: + cmds: + - echo "Print something" +``` + +- Or globally with `--silent` or `-s` flag + +If you want to suppress STDOUT instead, just redirect a command to `/dev/null`: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - echo "This will print nothing" > /dev/null +``` + +## Dry run mode + +Dry run mode (`--dry`) compiles and steps through each task, printing the +commands that would be run without executing them. This is useful for debugging +your Taskfiles. + +## Ignore errors + +You have the option to ignore errors during command execution. Given the +following Taskfile: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - exit 1 + - echo "Hello World" +``` + +Task will abort the execution after running `exit 1` because the status code `1` +stands for `EXIT_FAILURE`. However, it is possible to continue with execution +using `ignore_error`: + +```yaml +version: '3' + +tasks: + echo: + cmds: + - cmd: exit 1 + ignore_error: true + - echo "Hello World" +``` + +`ignore_error` can also be set for a task, which means errors will be suppressed +for all commands. Nevertheless, keep in mind that this option will not propagate +to other tasks called either by `deps` or `cmds`! + +## Output syntax + +By default, Task just redirects the STDOUT and STDERR of the running commands to +the shell in real-time. This is good for having live feedback for logging +printed by commands, but the output can become messy if you have multiple +commands running simultaneously and printing lots of stuff. + +To make this more customizable, there are currently three different output +options you can choose: + +- `interleaved` (default) +- `group` +- `prefixed` + +To choose another one, just set it to root in the Taskfile: + +```yaml +version: '3' + +output: 'group' + +tasks: + # ... +``` + +The `group` output will print the entire output of a command once after it +finishes, so you will not have live feedback for commands that take a long time +to run. + +When using the `group` output, you can optionally provide a templated message to +print at the start and end of the group. This can be useful for instructing CI +systems to group all of the output for a given task, such as with +[GitHub Actions' `::group::` command](https://docs.github.com/en/actions/learn-github-actions/workflow-commands-for-github-actions#grouping-log-lines) +or +[Azure Pipelines](https://docs.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?expand=1&view=azure-devops&tabs=bash#formatting-commands). + +```yaml +version: '3' + +output: + group: + begin: '::group::{{.TASK}}' + end: '::endgroup::' + +tasks: + default: + cmds: + - echo 'Hello, World!' + silent: true +``` + +```shell +$ task default +::group::default +Hello, World! +::endgroup:: +``` + +When using the `group` output, you may swallow the output of the executed +command on standard output and standard error if it does not fail (zero exit +code). + +```yaml +version: '3' + +silent: true + +output: + group: + error_only: true + +tasks: + passes: echo 'output-of-passes' + errors: echo 'output-of-errors' && exit 1 +``` + +```shell +$ task passes +$ task errors +output-of-errors +task: Failed to run task "errors": exit status 1 +``` + +The `prefix` output will prefix every line printed by a command with +`[task-name] ` as the prefix, but you can customize the prefix for a command +with the `prefix:` attribute: + +```yaml +version: '3' + +output: prefixed + +tasks: + default: + deps: + - task: print + vars: { TEXT: foo } + - task: print + vars: { TEXT: bar } + - task: print + vars: { TEXT: baz } + + print: + cmds: + - echo "{{.TEXT}}" + prefix: 'print-{{.TEXT}}' + silent: true +``` + +```shell +$ task default +[print-foo] foo +[print-bar] bar +[print-baz] baz +``` + +:::tip + +The `output` option can also be specified by the `--output` or `-o` flags. + +::: + +## Interactive CLI application + +When running interactive CLI applications inside Task they can sometimes behave +weirdly, especially when the [output mode](#output-syntax) is set to something +other than `interleaved` (the default), or when interactive apps are run in +parallel with other tasks. + +The `interactive: true` tells Task this is an interactive application and Task +will try to optimize for it: + +```yaml +version: '3' + +tasks: + default: + cmds: + - vim my-file.txt + interactive: true +``` + +If you still have problems running an interactive app through Task, please open +an issue about it. + +## Short task syntax + +Starting on Task v3, you can now write tasks with a shorter syntax if they have +the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc): + +```yaml +version: '3' + +tasks: + build: go build -v -o ./app{{exeExt}} . + + run: + - task: build + - ./app{{exeExt}} -h localhost -p 8080 +``` + +## `set` and `shopt` + +It's possible to specify options to 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. This can be added at global, task or command level. + +```yaml +version: '3' + +set: [pipefail] +shopt: [globstar] + +tasks: + # `globstar` required for double star globs to work + default: echo **/*.go +``` + +:::info + +Keep in mind that not all options are available in the +[shell interpreter library](https://github.com/mvdan/sh) that Task uses. + +::: + +## Watch tasks + +With the flags `--watch` or `-w` task will watch for file changes and run the +task again. This requires the `sources` attribute to be given, so task knows +which files to watch. + +The default watch interval is 5 seconds, but it's possible to change it by +either setting `interval: '500ms'` in the root of the Taskfile or by passing it +as an argument like `--interval=500ms`. + +Also, it's possible to set `watch: true` in a given task and it'll automatically +run in watch mode: + +```yaml +version: '3' + +interval: 500ms + +tasks: + build: + desc: Builds the Go application + watch: true + sources: + - '**/*.go' + cmds: + - go build # ... +``` + +:::info + +Note that when setting `watch: true` to a task, it'll only run in watch mode +when running from the CLI via `task my-watch-task`, but won't run in watch mode +if called by another task, either directly or as a dependency. + +::: + + +[gotemplate]: https://golang.org/pkg/text/template/ + diff --git a/docs/versioned_sidebars/version-latest-sidebars.json b/docs/versioned_sidebars/version-latest-sidebars.json new file mode 100644 index 00000000..1fbeb079 --- /dev/null +++ b/docs/versioned_sidebars/version-latest-sidebars.json @@ -0,0 +1,12 @@ +{ + "taskSidebar": [ + { + "type": "autogenerated", + "dirName": "." + }, + { + "type": "html", + "value": "
" + } + ] +} diff --git a/docs/versions.json b/docs/versions.json new file mode 100644 index 00000000..c24f3d37 --- /dev/null +++ b/docs/versions.json @@ -0,0 +1,3 @@ +[ + "latest" +]