Mirrors/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-12-16 11:47:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Configure Prettier for Markdown formatting (#1112)

Browse Source
This commit is contained in:
Misite Bao
2023-04-16 03:13:29 +08:00
committed by GitHub
parent 7876ccb3bc
commit 8026d8ddb3
17 changed files with 583 additions and 526 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.prettierignore Normal file
View File

@@ -0,0 +1 @@
docs/docs/changelog.md

7
.prettierrc.yml Normal file
View File

@@ -0,0 +1,7 @@
trailingComma: none
singleQuote: true
overrides:
- files: "*.md"
options:
printWidth: 80
proseWrap: always

148
CHANGELOG.md
View File

@@ -2,8 +2,8 @@
## Unreleased ## Unreleased
- Fix bug where "up-to-date" logs were not being omitted for silent tasks - Fix bug where "up-to-date" logs were not being omitted for silent tasks (#546,
(#546, #1107 by @danquah). #1107 by @danquah).
- Add `.hg` (Mercurial) to the list of ignored directories when using `--watch` - Add `.hg` (Mercurial) to the list of ignored directories when using `--watch`
(#1098 by @misery). (#1098 by @misery).
- More improvements to the release tool (#1096 by @pd93) - More improvements to the release tool (#1096 by @pd93)
@@ -13,18 +13,17 @@
## v3.23.0 - 2023-03-26 ## v3.23.0 - 2023-03-26
Task now has an [official extension for Visual Studio Task now has an
Code](https://marketplace.visualstudio.com/items?itemName=task.vscode-task) [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 contributed by @pd93! :tada: The extension is maintained in a
repository](https://github.com/go-task/vscode-task) under the `go-task` [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 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 it a go and let us know what you think via a
[discussion](https://github.com/go-task/vscode-task/discussions), [discussion](https://github.com/go-task/vscode-task/discussions),
[issue](https://github.com/go-task/vscode-task/issues) or on our [issue](https://github.com/go-task/vscode-task/issues) or on our
[Discord](https://discord.gg/6TY36E39UK)! [Discord](https://discord.gg/6TY36E39UK)!
> **NOTE:** > **NOTE:** The extension _requires_ v3.23.0 to be installed in order to work.
> The extension _requires_ v3.23.0 to be installed in order to work.
- The website was integrated with - The website was integrated with
[Crowdin](https://crowdin.com/project/taskfile) to allow the community to [Crowdin](https://crowdin.com/project/taskfile) to allow the community to
@@ -33,9 +32,9 @@ it a go and let us know what you think via a
- Added task location data to the `--json` flag output (#1056 by @pd93) - 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 - Change the name of the file generated by `task --init` from `Taskfile.yaml` to
`Taskfile.yml` (#1062 by @misitebao). `Taskfile.yml` (#1062 by @misitebao).
- Added new `splitArgs` template function (`{{splitArgs "foo bar 'foo bar - Added new `splitArgs` template function
baz'"}}`) to ensure string is split as arguments (#1040, (`{{splitArgs "foo bar 'foo bar baz'"}}`) to ensure string is split as
#1059 by @dhanusaputra). arguments (#1040, #1059 by @dhanusaputra).
- Fix the value of `{{.CHECKSUM}}` variable in status (#1076, #1080 by @pd93). - Fix the value of `{{.CHECKSUM}}` variable in status (#1076, #1080 by @pd93).
- Fixed deep copy implementation (#1072 by @pd93) - Fixed deep copy implementation (#1072 by @pd93)
- Created a tool to assist with releases (#1086 by @pd93). - Created a tool to assist with releases (#1086 by @pd93).
@@ -80,21 +79,21 @@ it a go and let us know what you think via a
- Add new `platforms:` attribute to `task` and `cmd`, so it's now possible to - 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 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 values are operating system (GOOS), architecture (GOARCH) or a combination of
the two. Example: `platforms: [linux]`, `platforms: [amd64]` or `platforms: the two. Example: `platforms: [linux]`, `platforms: [amd64]` or
[linux/amd64]`. Other platforms will be skipped (#978, #980 by @leaanthony). `platforms: [linux/amd64]`. Other platforms will be skipped (#978, #980 by
@leaanthony).
## v3.19.1 - 2022-12-31 ## v3.19.1 - 2022-12-31
- Small bug fix: closing `Taskfile.yml` once we're done reading it - Small bug fix: closing `Taskfile.yml` once we're done reading it (#963, #964
(#963, #964 by @HeCorr). by @HeCorr).
- Fixes a bug in v2 that caused a panic when using a `Taskfile_{{OS}}.yml` file - Fixes a bug in v2 that caused a panic when using a `Taskfile_{{OS}}.yml` file
(#961, #971 by @pd93). (#961, #971 by @pd93).
- Fixed a bug where watch intervals set in the Taskfile were not being respected - Fixed a bug where watch intervals set in the Taskfile were not being respected
(#969, #970 by @pd93) (#969, #970 by @pd93)
- Add `--json` flag (alias `-j`) with the intent to improve support for code - 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, editors and add room to other possible integrations. This is basic for now,
but we plan to add more info in the near future but we plan to add more info in the near future (#936 by @davidalpert, #764).
(#936 by @davidalpert, #764).
## v3.19.0 - 2022-12-05 ## v3.19.0 - 2022-12-05
@@ -106,19 +105,19 @@ it a go and let us know what you think via a
monorepos (#289, #920). monorepos (#289, #920).
- Add task-level `dotenv` support (#389, #904). - Add task-level `dotenv` support (#389, #904).
- It's now possible to use global level variables on `includes` (#942, #943). - It's now possible to use global level variables on `includes` (#942, #943).
- The website got a brand new [translation to - The website got a brand new
Chinese](https://task-zh.readthedocs.io/zh_CN/latest/) by [translation to Chinese](https://task-zh.readthedocs.io/zh_CN/latest/) by
[@DeronW](https://github.com/DeronW). Thanks! [@DeronW](https://github.com/DeronW). Thanks!
## v3.18.0 - 2022-11-12 ## v3.18.0 - 2022-11-12
- Show aliases on `task --list --silent` (`task --ls`). This means that aliases - Show aliases on `task --list --silent` (`task --ls`). This means that aliases
will be completed by the completion scripts (#919). will be completed by the completion scripts (#919).
- Tasks in the root Taskfile will now be displayed first in `--list`/`--list-all` - Tasks in the root Taskfile will now be displayed first in
output (#806, #890). `--list`/`--list-all` output (#806, #890).
- It's now possible to call a `default` task in an included Taskfile by using - 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 just the namespace. For example: `docs:default` is now automatically aliased
aliased to `docs` (#661, #815). to `docs` (#661, #815).
## v3.17.0 - 2022-10-14 ## v3.17.0 - 2022-10-14
@@ -136,8 +135,8 @@ it a go and let us know what you think via a
## v3.16.0 - 2022-09-29 ## v3.16.0 - 2022-09-29
- Add `npm` as new installation method: `npm i -g @go-task/cli` - Add `npm` as new installation method: `npm i -g @go-task/cli` (#870, #871,
(#870, #871, [npm package](https://www.npmjs.com/package/@go-task/cli)). [npm package](https://www.npmjs.com/package/@go-task/cli)).
- Add support to marking tasks and includes as internal, which will hide them - Add support to marking tasks and includes as internal, which will hide them
from `--list` and `--list-all` (#818). from `--list` and `--list-all` (#818).
@@ -201,20 +200,20 @@ it a go and let us know what you think via a
- Added support for multi-level inclusion of Taskfiles. This means that included - Added support for multi-level inclusion of Taskfiles. This means that included
Taskfiles can also include other Taskfiles. Before this was limited to one Taskfiles can also include other Taskfiles. Before this was limited to one
level (#390, #623, #656). level (#390, #623, #656).
- Add ability to specify vars when including a Taskfile. [Check out the - Add ability to specify vars when including a Taskfile.
documentation](https://taskfile.dev/#/usage?id=vars-of-included-taskfiles) for [Check out the documentation](https://taskfile.dev/#/usage?id=vars-of-included-taskfiles)
more information (#677). for more information (#677).
## v3.11.0 - 2022-02-19 ## v3.11.0 - 2022-02-19
- Task now supports printing begin and end messages when using the `group` - Task now supports printing begin and end messages when using the `group`
output mode, useful for grouping tasks in CI systems. [Check out the output mode, useful for grouping tasks in CI systems.
documentation](http://taskfile.dev/#/usage?id=output-syntax) for more [Check out the documentation](http://taskfile.dev/#/usage?id=output-syntax)
information (#647, #651). for more information (#647, #651).
- Add `Taskfile.dist.yml` and `Taskfile.dist.yaml` to the supported file name - Add `Taskfile.dist.yml` and `Taskfile.dist.yaml` to the supported file name
list. [Check out the list.
documentation](https://taskfile.dev/#/usage?id=supported-file-names) for more [Check out the documentation](https://taskfile.dev/#/usage?id=supported-file-names)
information (#498, #666). for more information (#498, #666).
## v3.10.0 - 2022-01-04 ## v3.10.0 - 2022-01-04
@@ -260,8 +259,8 @@ it a go and let us know what you think via a
## v3.9.0 - 2021-10-02 ## v3.9.0 - 2021-10-02
- A new `shellQuote` function was added to the template system (`{{shellQuote "a - A new `shellQuote` function was added to the template system
string"}}`) to ensure a string is safe for use in shell (`{{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#727](https://github.com/mvdan/sh/pull/727),
[mvdan/sh#737](https://github.com/mvdan/sh/pull/737), [mvdan/sh#737](https://github.com/mvdan/sh/pull/737),
[Documentation](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote)) [Documentation](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote))
@@ -295,8 +294,8 @@ it a go and let us know what you think via a
- Add `run:` setting to control if tasks should run multiple times or not. - Add `run:` setting to control if tasks should run multiple times or not.
Available options are `always` (the default), `when_changed` (if a variable Available options are `always` (the default), `when_changed` (if a variable
modified the task) and `once` (run only once no matter what). modified the task) and `once` (run only once no matter what). This is a long
This is a long time requested feature. Enjoy! (#53, #359). time requested feature. Enjoy! (#53, #359).
## v3.6.0 - 2021-07-10 ## v3.6.0 - 2021-07-10
@@ -310,10 +309,10 @@ it a go and let us know what you think via a
## v3.4.3 - 2021-05-30 ## v3.4.3 - 2021-05-30
- Add support for the `NO_COLOR` environment variable. - Add support for the `NO_COLOR` environment variable. (#459,
(#459, [fatih/color#137](https://github.com/fatih/color/pull/137)). [fatih/color#137](https://github.com/fatih/color/pull/137)).
- Fix bug where sources were not considering the right directory - Fix bug where sources were not considering the right directory in `--watch`
in `--watch` mode (#484, #485). mode (#484, #485).
## v3.4.2 - 2021-04-23 ## v3.4.2 - 2021-04-23
@@ -324,9 +323,9 @@ it a go and let us know what you think via a
## v3.4.1 - 2021-04-17 ## v3.4.1 - 2021-04-17
- Improve error reporting when parsing YAML: in some situations where you - Improve error reporting when parsing YAML: in some situations where you would
would just see an generic error, you'll now see the actual error with just see an generic error, you'll now see the actual error with more detail:
more detail: the YAML line the failed to parse, for example (#467). the YAML line the failed to parse, for example (#467).
- A JSON Schema was published [here](https://json.schemastore.org/taskfile.json) - A JSON Schema was published [here](https://json.schemastore.org/taskfile.json)
and is automatically being used by some editors like Visual Studio Code and is automatically being used by some editors like Visual Studio Code
(#135). (#135).
@@ -334,17 +333,17 @@ it a go and let us know what you think via a
## v3.3.0 - 2021-03-20 ## v3.3.0 - 2021-03-20
- Add support for delegating CLI arguments to commands with `--` and a - Add support for delegating CLI arguments to commands with `--` and a special
special `CLI_ARGS` variable (#327). `CLI_ARGS` variable (#327).
- Add a `--concurrency` (alias `-C`) flag, to limit the number of tasks that - Add a `--concurrency` (alias `-C`) flag, to limit the number of tasks that run
run concurrently. This is useful for heavy workloads. (#345). concurrently. This is useful for heavy workloads. (#345).
## v3.2.2 - 2021-01-12 ## v3.2.2 - 2021-01-12
- Improve performance of `--list` and `--summary` by skipping running shell - Improve performance of `--list` and `--summary` by skipping running shell
variables for these flags (#332). variables for these flags (#332).
- Fixed a bug where an environment in a Taskfile was not always overridable - Fixed a bug where an environment in a Taskfile was not always overridable by
by the system environment (#425). the system environment (#425).
- Fixed environment from .env files not being available as variables (#379). - Fixed environment from .env files not being available as variables (#379).
- The install script is now working for ARM platforms (#428). - The install script is now working for ARM platforms (#428).
@@ -359,23 +358,23 @@ it a go and let us know what you think via a
- Fix the `.task` directory being created in the task directory instead of the - Fix the `.task` directory being created in the task directory instead of the
Taskfile directory (#247). Taskfile directory (#247).
- Fix a bug where dynamic variables (those declared with `sh:`) were not - Fix a bug where dynamic variables (those declared with `sh:`) were not running
running in the task directory when the task has a custom dir or it was in the task directory when the task has a custom dir or it was in an included
in an included Taskfile (#384). Taskfile (#384).
- The watch feature (via the `--watch` flag) got a few different bug fixes and - The watch feature (via the `--watch` flag) got a few different bug fixes and
should be more stable now (#423, #365). should be more stable now (#423, #365).
## v3.1.0 - 2021-01-03 ## v3.1.0 - 2021-01-03
- Fix a bug when the checksum up-to-date resolution is used by a task - Fix a bug when the checksum up-to-date resolution is used by a task with a
with a custom `label:` attribute (#412). custom `label:` attribute (#412).
- Starting from this release, we're releasing official ARMv6 and ARM64 binaries - Starting from this release, we're releasing official ARMv6 and ARM64 binaries
for Linux (#375, #418). for Linux (#375, #418).
- Task now respects the order of declaration of included Taskfiles when - Task now respects the order of declaration of included Taskfiles when
evaluating variables declaring by them (#393). evaluating variables declaring by them (#393).
- `set -e` is now automatically set on every command. This was done to fix an - `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 issue where multiline string commands wouldn't really fail unless the sentence
sentence was in the last line (#403). was in the last line (#403).
## v3.0.1 - 2020-12-26 ## v3.0.1 - 2020-12-26
@@ -401,13 +400,12 @@ it a go and let us know what you think via a
- Added option to make included Taskfile run commands on its own directory - Added option to make included Taskfile run commands on its own directory
(#260, #144) (#260, #144)
- Taskfiles in version 1 are not supported anymore (#237). - Taskfiles in version 1 are not supported anymore (#237).
- Added global `method:` option. With this option, you can set a default - Added global `method:` option. With this option, you can set a default method
method to all tasks in a Taskfile (#246). to all tasks in a Taskfile (#246).
- Changed default method from `timestamp` to `checksum` (#246). - Changed default method from `timestamp` to `checksum` (#246).
- New magic variables are now available when using `status:`: - New magic variables are now available when using `status:`: `.TIMESTAMP` which
`.TIMESTAMP` which contains the greatest modification date contains the greatest modification date from the files listed in `sources:`,
from the files listed in `sources:`, and `.CHECKSUM`, which and `.CHECKSUM`, which contains a checksum of all files listed in `status:`.
contains a checksum of all files listed in `status:`.
This is useful for manual checking when using external, or even remote, This is useful for manual checking when using external, or even remote,
artifacts when using `status:` (#216). artifacts when using `status:` (#216).
- We're now using [slim-sprig](https://github.com/go-task/slim-sprig) instead of - We're now using [slim-sprig](https://github.com/go-task/slim-sprig) instead of
@@ -447,15 +445,15 @@ it a go and let us know what you think via a
- Fixed some bugs regarding minor version checks on `version:`. - Fixed some bugs regarding minor version checks on `version:`.
- Add `preconditions:` to task (#205). - Add `preconditions:` to task (#205).
- Create directory informed on `dir:` if it doesn't exist (#209, #211). - 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 - We now have a `--taskfile` flag (alias `-t`), which can be used to run another
another Taskfile (other than the default `Taskfile.yml`) (#221). Taskfile (other than the default `Taskfile.yml`) (#221).
- It's now possible to install Task using Homebrew on Linux - 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)). ([go-task/homebrew-tap#1](https://github.com/go-task/homebrew-tap/pull/1)).
## v2.5.2 - 2019-05-11 ## v2.5.2 - 2019-05-11
- Reverted YAML upgrade due issues with CRLF on Windows - Reverted YAML upgrade due issues with CRLF on Windows (#201,
(#201, [go-yaml/yaml#450](https://github.com/go-yaml/yaml/issues/450)). [go-yaml/yaml#450](https://github.com/go-yaml/yaml/issues/450)).
- Allow setting global variables through the CLI (#192). - Allow setting global variables through the CLI (#192).
## 2.5.1 - 2019-04-27 ## 2.5.1 - 2019-04-27
@@ -471,8 +469,9 @@ it a go and let us know what you think via a
[this install script](https://taskfile.dev/#/installation?id=install-script) [this install script](https://taskfile.dev/#/installation?id=install-script)
to use the new taskfile.dev domain on scripts from now on. to use the new taskfile.dev domain on scripts from now on.
- Fixed to the ZSH completion (#182). - Fixed to the ZSH completion (#182).
- Add [`--summary` flag along with `summary:` task - Add
attribute](https://taskfile.org/#/usage?id=display-summary-of-task) (#180). [`--summary` flag along with `summary:` task attribute](https://taskfile.org/#/usage?id=display-summary-of-task)
(#180).
## v2.4.0 - 2019-02-21 ## v2.4.0 - 2019-02-21
@@ -501,8 +500,9 @@ it a go and let us know what you think via a
## v2.2.0 - 2018-10-25 ## v2.2.0 - 2018-10-25
- Added support for [including other - Added support for
Taskfiles](https://taskfile.org/#/usage?id=including-other-taskfiles) (#98) [including other Taskfiles](https://taskfile.org/#/usage?id=including-other-taskfiles)
(#98)
- This should be considered experimental. For now, only including local files - This should be considered experimental. For now, only including local files
is supported, but support for including remote Taskfiles is being discussed. is supported, but support for including remote Taskfiles is being discussed.
If you have any feedback, please comment on #98. If you have any feedback, please comment on #98.
@@ -545,8 +545,8 @@ it a go and let us know what you think via a
Version 2.0.0 is here, with a new Taskfile format. Version 2.0.0 is here, with a new Taskfile format.
Please, make sure to read the [Taskfile Please, make sure to read the
versions](https://github.com/go-task/task/blob/master/TASKFILE_VERSIONS.md) [Taskfile versions](https://github.com/go-task/task/blob/master/TASKFILE_VERSIONS.md)
document, since it describes in depth what changed for this version. document, since it describes in depth what changed for this version.
- New Taskfile version 2 (#77) - New Taskfile version 2 (#77)

6
README.md
View File

@@ -18,10 +18,12 @@
<div align="center"> <div align="center">
| [Appwrite][appwrite] | | [Appwrite][appwrite] |
| - | | ------------------------------------------------------ |
| [![Appwrite](/docs/static/img/appwrite.svg)][appwrite] | | [![Appwrite](/docs/static/img/appwrite.svg)][appwrite] |
</div> </div>
<!-- prettier-ignore-start -->
[appwrite]: https://appwrite.io/?utm_source=task_github&utm_medium=social&utm_campaign=task_oss_fund [appwrite]: https://appwrite.io/?utm_source=task_github&utm_medium=social&utm_campaign=task_oss_fund
<!-- prettier-ignore-end -->

1
docs/.prettierignore Normal file
View File

@@ -0,0 +1 @@
docs/changelog.md

255
docs/docs/api_reference.md
View File

@@ -17,43 +17,45 @@ task [--flags] [tasks...] [-- CLI_ARGS...]
:::tip :::tip
If `--` is given, all remaning arguments will be assigned to a special `CLI_ARGS` If `--` is given, all remaning arguments will be assigned to a special
variable `CLI_ARGS` variable
::: :::
| Short | Flag | Type | Default | Description | | 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` | `--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. | | `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. | | `-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. | | `-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. | | `-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. | | `-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}`. | | `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. | | `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. | | `-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). | | `-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. | | `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. | | `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed. | | | `--sort` | `string` | `default` | Changes the order of the tasks when listed. |
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) | | | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. | | `-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-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-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. | | | `--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. | | `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. | | `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. | | | `--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. | | | `--summary` | `bool` | `false` | Show summary about a task. |
| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | | | `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. | | `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
| | `--version` | `bool` | `false` | Show Task version. | | | `--version` | `bool` | `false` | Show Task version. |
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. | | `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. |
## JSON Output ## 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: 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:
```jsonc ```jsonc
{ {
@@ -68,7 +70,7 @@ When using the `--json` flag in combination with either the `--list` or `--list-
"column": 3, "column": 3,
"taskfile": "/path/to/Taskfile.yml" "taskfile": "/path/to/Taskfile.yml"
} }
}, }
// ... // ...
], ],
"location": "/path/to/Taskfile.yml" "location": "/path/to/Taskfile.yml"
@@ -79,65 +81,66 @@ When using the `--json` flag in combination with either the `--list` or `--list-
There are some special variables that is available on the templating system: There are some special variables that is available on the templating system:
| Var | Description | | Var | Description |
| - | - | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. | | `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `TASK` | The name of the current task. | | `TASK` | The name of the current task. |
| `ROOT_DIR` | The absolute path of the root Taskfile. | | `ROOT_DIR` | The absolute path of the root Taskfile. |
| `TASKFILE_DIR` | The absolute path of the included Taskfile. | | `TASKFILE_DIR` | The absolute path of the included Taskfile. |
| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. | | `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`. | | `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 listes in `sources`. Only available within the `status` prop and if method is set to `timestamp`. | | `TIMESTAMP` | The date object of the greatest timestamp of the files listes in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. | | `TASK_VERSION` | The current version of task. |
## ENV ## ENV
Some environment variables can be overriden to adjust Task behavior. Some environment variables can be overriden to adjust Task behavior.
| ENV | Default | Description | | 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_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_RESET` | `0` | Color used for white. |
| `TASK_COLOR_BLUE` | `34` | Color used for blue. | | `TASK_COLOR_BLUE` | `34` | Color used for blue. |
| `TASK_COLOR_GREEN` | `32` | Color used for green. | | `TASK_COLOR_GREEN` | `32` | Color used for green. |
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. | | `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. | | `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. | | `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
| `TASK_COLOR_RED` | `31` | Color used for red. | | `TASK_COLOR_RED` | `31` | Color used for red. |
| `FORCE_COLOR` | | Force color output usage. | | `FORCE_COLOR` | | Force color output usage. |
## Taskfile Schema ## Taskfile Schema
| Attribute | Type | Default | Description | | Attribute | Type | Default | Description |
| - | - | - | - | | ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `string` | | Version of the Taskfile. The current version is `3`. | | `version` | `string` | | Version of the Taskfile. The current version is `3`. |
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. | | `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. | | `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. | | `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
| `vars` | [`map[string]Variable`](#variable) | | A set of global variables. | | `vars` | [`map[string]Variable`](#variable) | | A set of global variables. |
| `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. | | `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. |
| `tasks` | [`map[string]Task`](#task) | | A set of task definitions. | | `tasks` | [`map[string]Task`](#task) | | A set of task definitions. |
| `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. | | `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. | | `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`. | | `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). | | `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). | | `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). | | `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
### Include ### Include
| Attribute | Type | Default | Description | | 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. | | `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. | | `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. | | `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`. | | `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. | | `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. | | `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |
:::info :::info
Informing only a string like below is equivalent to setting that value to the `taskfile` attribute. Informing only a string like below is equivalent to setting that value to the
`taskfile` attribute.
```yaml ```yaml
includes: includes:
@@ -148,10 +151,10 @@ includes:
### Variable ### Variable
| Attribute | Type | Default | Description | | Attribute | Type | Default | Description |
| - | - | - | - | | --------- | -------- | ------- | ------------------------------------------------------------------------ |
| *itself* | `string` | | A static value that will be set to the variable. | | _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. | | `sh` | `string` | | A shell command. The output (`STDOUT`) will be assigned to the variable. |
:::info :::info
@@ -168,32 +171,32 @@ vars:
### Task ### Task
| Attribute | Type | Default | Description | | Attribute | Type | Default | Description |
| - | - | - | - | | --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmds` | [`[]Command`](#command) | | A list of shell commands to be executed. | | `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. | | `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. | | `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`. | | `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. |
| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. | | `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. | | `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. | | `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. | | `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`. | | `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. | | `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. | | `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. | | `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. | | `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. | | `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. | | `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. | | `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`. | | `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. | | `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`. | | `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. | | `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`. | | `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Task will be skipped otherwise. | | `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Task will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). | | `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). | | `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
:::info :::info
@@ -216,17 +219,17 @@ tasks:
#### Command #### Command
| Attribute | Type | Default | Description | | Attribute | Type | Default | Description |
| - | - | - | - | | -------------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmd` | `string` | | The shell command to be executed. | | `cmd` | `string` | | The shell command to be executed. |
| `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. | | `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. |
| `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. | | `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`. | | `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. | | `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`. | | `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Command will be skipped otherwise. | | `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Command will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). | | `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). | | `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
:::info :::info
@@ -244,10 +247,10 @@ tasks:
#### Dependency #### Dependency
| Attribute | Type | Default | Description | | Attribute | Type | Default | Description |
| - | - | - | - | | --------- | ---------------------------------- | ------- | -------------------------------------------------------- |
| `task` | `string` | | The task to be execute as a dependency. | | `task` | `string` | | The task to be execute as a dependency. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to this task. | | `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to this task. |
:::tip :::tip
@@ -264,10 +267,10 @@ tasks:
#### Precondition #### Precondition
| Attribute | Type | Default | Description | | 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. | | `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. | | `msg` | `string` | | Optional message to print if the precondition isn't met. |
:::tip :::tip

51
docs/docs/community.md
View File

@@ -5,13 +5,13 @@ sidebar_position: 8
# Community # Community
Some of the work to improve the Task ecosystem is done by the community, be Some of the work to improve the Task ecosystem is done by the community, be it
it installation methods or integrations with code editor. I (the author) am installation methods or integrations with code editor. I (the author) am
thankful for everyone that helps me to improve the overall experience. thankful for everyone that helps me to improve the overall experience.
## Translations ## Translations
[@DeronW](https://github.com/DeronW) maintains the [@DeronW](https://github.com/DeronW) maintains the
[Chinese translation](https://task-zh.readthedocs.io/zh_CN/latest/) of the [Chinese translation](https://task-zh.readthedocs.io/zh_CN/latest/) of the
website [on this repository](https://github.com/DeronW/task). website [on this repository](https://github.com/DeronW/task).
@@ -19,31 +19,35 @@ website [on this repository](https://github.com/DeronW/task).
### JSON Schema ### JSON Schema
Initial work on the schema was made by [@KROSF](https://github.com/KROSF) Initial work on the schema was made by [@KROSF](https://github.com/KROSF) on
on [this Gist](https://gist.github.com/KROSF/c5435acf590acd632f71bb720f685895). [this Gist](https://gist.github.com/KROSF/c5435acf590acd632f71bb720f685895). The
The schema is currently available at schema is currently available at https://taskfile.dev/schema.json and linked at
https://taskfile.dev/schema.json and linked at https://json.schemastore.org/taskfile.json https://json.schemastore.org/taskfile.json so it is be used automatically many
so it is be used automatically many code editors, like VSCode. code editors, like VSCode. Contributions can be done by editing
Contributions can be done by editing [this file](https://github.com/go-task/task/blob/master/docs/static/schema.json). [this file](https://github.com/go-task/task/blob/master/docs/static/schema.json).
### Visual Studio Code extension ### Visual Studio Code extension
Additionally, there's also some work done by Additionally, there's also some work done by
[@paulvarache](https://github.com/paulvarache) in making an Visual Studio Code [@paulvarache](https://github.com/paulvarache) in making an Visual Studio Code
extension, which has its code [here](https://github.com/paulvarache/vscode-taskfile) extension, which has its code
and is published [here](https://marketplace.visualstudio.com/items?itemName=paulvarache.vscode-taskfile). [here](https://github.com/paulvarache/vscode-taskfile) and is published
[here](https://marketplace.visualstudio.com/items?itemName=paulvarache.vscode-taskfile).
### Sublime Text 4 package ### Sublime Text 4 package
There is a convenience wrapper for initializing and running tasks from Sublime Text's command palette. The package is There is a convenience wrapper for initializing and running tasks from Sublime
developed by [@biozz](https://github.com/biozz), the source code is available [here](https://github.com/biozz/sublime-taskfile) Text's command palette. The package is developed by
and it is published on Package Control [here](https://packagecontrol.io/packages/Taskfile). [@biozz](https://github.com/biozz), the source code is available
[here](https://github.com/biozz/sublime-taskfile) and it is published on Package
Control [here](https://packagecontrol.io/packages/Taskfile).
### IntelliJ plugin ### IntelliJ plugin
There's a JetBrains IntelliJ plugin done by There's a JetBrains IntelliJ plugin done by
[@lechuckroh](https://github.com/lechuckroh), which has its code [here](https://github.com/lechuckroh/task-intellij-plugin) [@lechuckroh](https://github.com/lechuckroh), which has its code
and is published [here](https://plugins.jetbrains.com/plugin/17058-taskfile). [here](https://github.com/lechuckroh/task-intellij-plugin) and is published
[here](https://plugins.jetbrains.com/plugin/17058-taskfile).
## Other Integrations ## Other Integrations
@@ -54,20 +58,21 @@ and is published [here](https://plugins.jetbrains.com/plugin/17058-taskfile).
Some installation methods are maintained by third party: Some installation methods are maintained by third party:
- [GitHub Actions](https://github.com/arduino/setup-task) - [GitHub Actions](https://github.com/arduino/setup-task) by
by [@arduino](https://github.com/arduino) [@arduino](https://github.com/arduino)
- [AUR](https://aur.archlinux.org/packages/go-task-bin) - [AUR](https://aur.archlinux.org/packages/go-task-bin) by
by [@carlsmedstad](https://github.com/carlsmedstad) [@carlsmedstad](https://github.com/carlsmedstad)
- [Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json) - [Scoop](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json)
- [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/) - [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) - [NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/development/tools/go-task/default.nix)
## More ## More
Also, thanks for all the [code contributors](https://github.com/go-task/task/graphs/contributors), Also, thanks for all the
[code contributors](https://github.com/go-task/task/graphs/contributors),
[financial contributors](https://opencollective.com/task), all those who [financial contributors](https://opencollective.com/task), all those who
[reported bugs](https://github.com/go-task/task/issues?q=is%3Aissue) and [reported bugs](https://github.com/go-task/task/issues?q=is%3Aissue) and
[answered questions](https://github.com/go-task/task/discussions). [answered questions](https://github.com/go-task/task/discussions).
If you know something that is missing in this document, please submit a If you know something that is missing in this document, please submit a pull
pull request. request.

71
docs/docs/contributing.md
View File

@@ -11,21 +11,21 @@ before submitting a PR.
## Before you start ## Before you start
- **Check existing work** - Is there an existing PR? Are there issues discussing - **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 the feature/change you want to make? Please make sure you consider/address
discussions in your work. these discussions in your work.
- **Backwards compatibility** - Will your change break existing Taskfiles? It is - **Backwards compatibility** - Will your change break existing Taskfiles? It is
much more likely that your change will merged if it backwards compatible. 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, 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 consider opening an issue first so that API changes can be discussed before
invest your time into a PR. you invest your time into a PR.
## 1. Setup ## 1. Setup
- **Go** - Task is written in [Go]. We always support the latest two major Go - **Go** - Task is written in [Go][go]. We always support the latest two major
versions, so make sure your version is recent enough. Go versions, so make sure your version is recent enough.
- **Node.js** - [Node.js] is used to host Task's documentation server and is - **Node.js** - [Node.js][nodejs] is used to host Task's documentation server
required if you want to run this server locally. and is required if you want to run this server locally.
- **Yarn** - [Yarn] is the Node.js package manager used by Task. - **Yarn** - [Yarn][yarn] is the Node.js package manager used by Task.
## 2. Making changes ## 2. Making changes
@@ -45,15 +45,15 @@ invest your time into a PR.
### Running your changes ### Running your changes
To run Task with working changes, you can use `go run ./cmd/task`. To run a 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 development build of task against a test Taskfile in `testdata`, you can use
run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`. `go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`.
### Updating documentation ### Updating documentation
Task uses [Docusaurus] to host a documentation server. This can be setup and run Task uses [Docusaurus][docusaurus] to host a documentation server. This can be
locally by using `task docs` (requires `nodejs` & `yarn`). All content is setup and run locally by using `task docs` (requires `nodejs` & `yarn`). All
written in Markdown and is located in the `docs/docs` directory. All Markdown content is written in Markdown and is located in the `docs/docs` directory. All
documents should have an 80 character line wrap limit. Markdown documents should have an 80 character line wrap limit.
When making a change, consider whether a change to the [Usage Guide](./usage.md) When making a change, consider whether a change to the [Usage Guide](./usage.md)
is necessary. This document contains descriptions and examples of how to use is necessary. This document contains descriptions and examples of how to use
@@ -62,10 +62,10 @@ 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 documentation and any examples are up-to-date. Ensure that any examples follow
the [Taskfile Styleguide](./styleguide.md). the [Taskfile Styleguide](./styleguide.md).
If you added a new field, command or flag, ensure that you add it to the [API If you added a new field, command or flag, ensure that you add it to the
Reference](./api_reference.md). New fields also need to be added to the [JSON [API Reference](./api_reference.md). New fields also need to be added to the
Schema]. The descriptions for fields in the API reference and the schema should [JSON Schema][json-schema]. The descriptions for fields in the API reference and
match. the schema should match.
### Writing tests ### Writing tests
@@ -102,8 +102,9 @@ be reasonable to split it in a few). Git squash and rebase is your friend!
> I want to contribute, where do I start? > I want to contribute, where do I start?
Take a look at the list of [open issues]. We have a [good first issue] label for Take a look at the list of [open issues][open-issues]. We have a [good first
simpler issues that are ideal for first time contributions. 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 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 feature. You can also contribute by upvoting/commenting on issues, helping to
@@ -112,18 +113,18 @@ answer questions or contributing to other [community projects](./community.md).
> I'm stuck, where can I get help? > I'm stuck, where can I get help?
If you have questions, feel free to ask them in the `#help` forum channel on our If you have questions, feel free to ask them in the `#help` forum channel on our
[Discord server] or open a [Discussion] on GitHub. [Discord server][discord-server] or open a [Discussion][discussion] on GitHub.
--- ---
[Go]: https://go.dev <!-- prettier-ignore-start -->
[Node.js]: https://nodejs.org/en/ [go]: https://go.dev
[Yarn]: https://yarnpkg.com/ [nodejs]: https://nodejs.org/en/
[Docusaurus]: https://docusaurus.io [yarn]: https://yarnpkg.com/
[JSON Schema]: [docusaurus]: https://docusaurus.io
https://github.com/go-task/task/blob/master/docs/static/schema.json [json-schema]: https://github.com/go-task/task/blob/master/docs/static/schema.json
[open issues]: https://github.com/go-task/task/issues [open-issues]: https://github.com/go-task/task/issues
[good first issue]: [good-first-issue]: https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22 [discord-server]: https://discord.gg/6TY36E39UK
[Discord server]: https://discord.gg/6TY36E39UK [discussion]: https://github.com/go-task/task/discussions
[Discussion]: https://github.com/go-task/task/discussions <!-- prettier-ignore-end -->

14
docs/docs/donate.md
View File

@@ -11,15 +11,15 @@ channels listed below.
This is just a way of saying "thank you", it won't give you any benefits like This is just a way of saying "thank you", it won't give you any benefits like
higher priority on issues or something similar. higher priority on issues or something similar.
Companies who donate at least $50/month will be featured as a "Gold Sponsor" Companies who donate at least $50/month will be featured as a "Gold Sponsor" in
in the website homepage and on the GitHub repository README. Make contact with the website homepage and on the GitHub repository README. Make contact with
[@andreynering] with the logo you want to be shown. [@andreynering] with the logo you want to be shown. Suspect businesses
Suspect businesses (gambling, casinos, etc) won't be allowed, though. (gambling, casinos, etc) won't be allowed, though.
## GitHub Sponsors ## GitHub Sponsors
The preferred way to donate to the maintainers is via GitHub Sponsors. The preferred way to donate to the maintainers is via GitHub Sponsors. Just use
Just use the following links to do your donation: the following links to do your donation:
- [@andreynering](https://github.com/sponsors/andreynering) - [@andreynering](https://github.com/sponsors/andreynering)
- [@pd93](https://github.com/sponsors/pd93) - [@pd93](https://github.com/sponsors/pd93)
@@ -46,4 +46,6 @@ You can donate to [@andreynering] via PayPal as well:
And if you're Brazilian, you can also donate to [@andreynering] via PIX by And if you're Brazilian, you can also donate to [@andreynering] via PIX by
[using this QR Code](/img/pix.png). [using this QR Code](/img/pix.png).
<!-- prettier-ignore-start -->
[@andreynering]: https://github.com/andreynering [@andreynering]: https://github.com/andreynering
<!-- prettier-ignore-end -->

8
docs/docs/faq.md
View File

@@ -41,7 +41,7 @@ around this limitation using one of the following methods:
- Use something like `{{if eq OS "windows"}}powershell {{end}}<my_cmd>` to - Use something like `{{if eq OS "windows"}}powershell {{end}}<my_cmd>` to
detect windows and run the command in Powershell directly. detect windows and run the command in Powershell directly.
- Use a shell on Windows that supports these commands as builtins, such as [Git - Use a shell on Windows that supports these commands as builtins, such as [Git
Bash] or [WSL]. Bash][git-bash] or [WSL][wsl].
We want to make improvements to this part of Task and the issues below track We want to make improvements to this part of Task and the issues below track
this work. Constructive comments and contributions are very welcome! this work. Constructive comments and contributions are very welcome!
@@ -50,5 +50,7 @@ this work. Constructive comments and contributions are very welcome!
- [mvdan/sh#93](https://github.com/mvdan/sh/issues/93) - [mvdan/sh#93](https://github.com/mvdan/sh/issues/93)
- [mvdan/sh#97](https://github.com/mvdan/sh/issues/97) - [mvdan/sh#97](https://github.com/mvdan/sh/issues/97)
[Git Bash]: https://gitforwindows.org/ <!-- prettier-ignore-start -->
[WSL]: https://learn.microsoft.com/en-us/windows/wsl/install [git-bash]: https://gitforwindows.org/
[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install
<!-- prettier-ignore-end -->

59
docs/docs/installation.md
View File

@@ -18,9 +18,11 @@ Task is as simple as running:
brew install go-task/tap/go-task brew install go-task/tap/go-task
``` ```
The above Formula is [maintained by ourselves](https://github.com/go-task/homebrew-tap/blob/master/Formula/go-task.rb). The above Formula is
[maintained by ourselves](https://github.com/go-task/homebrew-tap/blob/master/Formula/go-task.rb).
Recently, Task was also made available [on the official Homebrew repository](https://formulae.brew.sh/formula/go-task), 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: so you also have that option if you prefer:
```bash ```bash
@@ -29,9 +31,8 @@ brew install go-task
### Snap ### Snap
Task is available in [Snapcraft][snapcraft], but keep in mind that your Task is available in [Snapcraft][snapcraft], but keep in mind that your Linux
Linux distribution should allow classic confinement for Snaps to Task work distribution should allow classic confinement for Snaps to Task work right:
right:
```bash ```bash
sudo snap install task --classic sudo snap install task --classic
@@ -39,8 +40,8 @@ sudo snap install task --classic
### Chocolatey ### Chocolatey
If you're on Windows and have [Chocolatey][choco] installed, getting If you're on Windows and have [Chocolatey][choco] installed, getting Task is as
Task is as simple as running: simple as running:
```bash ```bash
choco install go-task choco install go-task
@@ -50,15 +51,15 @@ This installation method is community owned.
### Scoop ### Scoop
If you're on Windows and have [Scoop][scoop] installed, getting If you're on Windows and have [Scoop][scoop] installed, getting Task is as
Task is as simple as running: simple as running:
```cmd ```cmd
scoop install task scoop install task
``` ```
This installation method is community owned. After a new release of Task, it This installation method is community owned. After a new release of Task, it may
may take some time until it's available on Scoop. take some time until it's available on Scoop.
### AUR ### AUR
@@ -84,26 +85,29 @@ This installation method is community owned.
### Fedora ### Fedora
If you're on Fedora Linux you can install Task from the official 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`: [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)
repository using `dnf`:
```cmd ```cmd
sudo dnf install go-task sudo dnf install go-task
``` ```
This installation method is community owned. After a new release of Task, it This installation method is community owned. After a new release of Task, it may
may take some time until it's available in [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/). take some time until it's available in
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/).
### Nix ### Nix
If you're on NixOS or have Nix installed If you're on NixOS or have Nix installed you can install Task from
you can install Task from [nixpkgs](https://github.com/NixOS/nixpkgs): [nixpkgs](https://github.com/NixOS/nixpkgs):
```cmd ```cmd
nix-env -iA nixpkgs.go-task nix-env -iA nixpkgs.go-task
``` ```
This installation method is community owned. After a new release of Task, it This installation method is community owned. After a new release of Task, it may
may take some time until it's available in [nixpkgs](https://github.com/NixOS/nixpkgs). take some time until it's available in
[nixpkgs](https://github.com/NixOS/nixpkgs).
### npm ### npm
@@ -117,9 +121,8 @@ npm install -g @go-task/cli
### Winget ### Winget
If you are using Windows and installed the If you are using Windows and installed the
[winget](https://github.com/microsoft/winget-cli) package management tool, [winget](https://github.com/microsoft/winget-cli) package management tool, you
you can install Task from can install Task from [winget-pkgs](https://github.com/microsoft/winget-pkgs).
[winget-pkgs](https://github.com/microsoft/winget-pkgs).
```bash ```bash
winget install Task.Task winget install Task.Task
@@ -129,8 +132,8 @@ winget install Task.Task
### Binary ### Binary
You can download the binary from the [releases page on GitHub][releases] and You can download the binary from the [releases page on GitHub][releases] and add
add to your `$PATH`. to your `$PATH`.
DEB and RPM packages are also available. DEB and RPM packages are also available.
@@ -167,8 +170,7 @@ default.
### GitHub Actions ### GitHub Actions
If you want to install Task in GitHub Actions you can try using If you want to install Task in GitHub Actions you can try using
[this action](https://github.com/arduino/setup-task) [this action](https://github.com/arduino/setup-task) by the Arduino team:
by the Arduino team:
```yaml ```yaml
- name: Install Task - name: Install Task
@@ -184,8 +186,9 @@ This installation method is community owned.
### Go Modules ### Go Modules
Ensure that you have a supported version of [Go][go] properly installed and setup. You can find Ensure that you have a supported version of [Go][go] properly installed and
the minimum required version of Go in the [go.mod](https://github.com/go-task/task/blob/master/go.mod#L3) file. setup. You can find the minimum required version of Go in the
[go.mod](https://github.com/go-task/task/blob/master/go.mod#L3) file.
You can then install the latest release globally by running: You can then install the latest release globally by running:
@@ -269,6 +272,7 @@ Add the line and save the file:
Invoke-Expression -Command path/to/task.ps1 Invoke-Expression -Command path/to/task.ps1
``` ```
<!-- prettier-ignore-start -->
[go]: https://golang.org/ [go]: https://golang.org/
[snapcraft]: https://snapcraft.io/task [snapcraft]: https://snapcraft.io/task
[homebrew]: https://brew.sh/ [homebrew]: https://brew.sh/
@@ -277,3 +281,4 @@ Invoke-Expression -Command path/to/task.ps1
[godownloader]: https://github.com/goreleaser/godownloader [godownloader]: https://github.com/goreleaser/godownloader
[choco]: https://chocolatey.org/ [choco]: https://chocolatey.org/
[scoop]: https://scoop.sh/ [scoop]: https://scoop.sh/
<!-- prettier-ignore-end -->

14
docs/docs/intro.md
View File

@@ -40,13 +40,15 @@ guide to check the full schema documentation and Task features.
- [Easy installation](installation.md): just download a single binary, add to - [Easy installation](installation.md): just download a single binary, add to
`$PATH` and you're done! Or you can also install using [Homebrew][homebrew], `$PATH` and you're done! Or you can also install using [Homebrew][homebrew],
[Snapcraft][snapcraft], or [Scoop][scoop] if you want. [Snapcraft][snapcraft], or [Scoop][scoop] if you want.
- Available on CIs: by adding [this simple command](installation.md#install-script) - Available on CIs: by adding
to install on your CI script and you're ready to use Task as part of your CI pipeline; [this simple command](installation.md#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, - 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]. 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) - Great for code generation: you can easily
if a given set of files haven't changed since last run (based either on its [prevent a task from running](/usage#prevent-unnecessary-work) if a given set
timestamp or content). of files haven't changed since last run (based either on its timestamp or
content).
## Gold Sponsors ## Gold Sponsors
@@ -58,6 +60,7 @@ guide to check the full schema documentation and Task features.
</div> </div>
<!-- prettier-ignore-start -->
[make]: https://www.gnu.org/software/make/ [make]: https://www.gnu.org/software/make/
[go]: https://go.dev/ [go]: https://go.dev/
[yaml]: http://yaml.org/ [yaml]: http://yaml.org/
@@ -65,3 +68,4 @@ guide to check the full schema documentation and Task features.
[snapcraft]: https://snapcraft.io/ [snapcraft]: https://snapcraft.io/
[scoop]: https://scoop.sh/ [scoop]: https://scoop.sh/
[sh]: https://github.com/mvdan/sh [sh]: https://github.com/mvdan/sh
<!-- prettier-ignore-end -->

29
docs/docs/releasing.md
View File

@@ -5,13 +5,13 @@ sidebar_position: 10
# Releasing # Releasing
The release process of Task is done with the help of The release process of Task is done with the help of [GoReleaser][goreleaser].
[GoReleaser][goreleaser]. You can test the release process locally by calling You can test the release process locally by calling the `test-release` task of
the `test-release` task of the Taskfile. the Taskfile.
[GitHub Actions](https://github.com/go-task/task/actions) should release [GitHub Actions](https://github.com/go-task/task/actions) should release
artifacts automatically when a new Git tag is pushed to master artifacts automatically when a new Git tag is pushed to master (raw executables
(raw executables and DEB and RPM packages). and DEB and RPM packages).
Since v3.15.0, raw executables can also be reproduced and verified locally by 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 checking out a specific tag and calling `goreleaser build`, using the Go version
@@ -33,24 +33,26 @@ and then run `task npm:publish` to push it.
The [snap package][snappackage] requires to manual steps to release a new The [snap package][snappackage] requires to manual steps to release a new
version: version:
* Updating the current version on [snapcraft.yaml][snapcraftyaml]. - Updating the current version on [snapcraft.yaml][snapcraftyaml].
* Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel on - Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel
the [Snapcraft dashboard][snapcraftdashboard]. on the [Snapcraft dashboard][snapcraftdashboard].
# Scoop # Scoop
Scoop is a command-line package manager for the Windows operating system. Scoop is a command-line package manager for the Windows operating system. Scoop
Scoop package manifests are maintained by the community. package manifests are maintained by the community. Scoop owners usually take
Scoop owners usually take care of updating versions there by editing [this file](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json). 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. If you think its Task version is outdated, open an issue to let us know.
# Nix # Nix
Nix is a community owned installation method. Nix package maintainers usually take care Nix is a community owned installation method. Nix package maintainers usually
of updating versions there by editing 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). [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. If you think its Task version is outdated, open an issue to let us know.
<!-- prettier-ignore-start -->
[goreleaser]: https://goreleaser.com/ [goreleaser]: https://goreleaser.com/
[homebrewtap]: https://github.com/go-task/homebrew-tap [homebrewtap]: https://github.com/go-task/homebrew-tap
[gotaskrb]: https://github.com/go-task/homebrew-tap/blob/master/Formula/go-task.rb [gotaskrb]: https://github.com/go-task/homebrew-tap/blob/master/Formula/go-task.rb
@@ -58,3 +60,4 @@ If you think its Task version is outdated, open an issue to let us know.
[snappackage]: https://github.com/go-task/snap [snappackage]: https://github.com/go-task/snap
[snapcraftyaml]: https://github.com/go-task/snap/blob/master/snap/snapcraft.yaml#L2 [snapcraftyaml]: https://github.com/go-task/snap/blob/master/snap/snapcraft.yaml#L2
[snapcraftdashboard]: https://snapcraft.io/task/releases [snapcraftdashboard]: https://snapcraft.io/task/releases
<!-- prettier-ignore-end -->

38
docs/docs/taskfile_versions.md
View File

@@ -40,9 +40,8 @@ The variable priority order was also different:
## Version 2.0 ## Version 2.0
At version 2, we introduced the `version:` key, to allow us to evolve Task At version 2, we introduced the `version:` key, to allow us to evolve Task with
with new features without breaking existing Taskfiles. The new syntax is as new features without breaking existing Taskfiles. The new syntax is as follows:
follows:
```yaml ```yaml
version: '2' version: '2'
@@ -53,8 +52,8 @@ tasks:
- echo "Hello, World!" - echo "Hello, World!"
``` ```
Version 2 allows you to write global variables directly in the Taskfile, Version 2 allows you to write global variables directly in the Taskfile, if you
if you don't want to create a `Taskvars.yml`: don't want to create a `Taskvars.yml`:
```yaml ```yaml
version: '2' version: '2'
@@ -88,8 +87,8 @@ vars:
FOO: foo FOO: foo
BAR: bar BAR: bar
BAZ: baz BAZ: baz
FOOBAR: "{{.FOO}}{{.BAR}}" FOOBAR: '{{.FOO}}{{.BAR}}'
FOOBARBAZ: "{{.FOOBAR}}{{.BAZ}}" FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
tasks: tasks:
default: default:
@@ -99,9 +98,9 @@ tasks:
## Version 2.1 ## Version 2.1
Version 2.1 includes a global `output` option, to allow having more control Version 2.1 includes a global `output` option, to allow having more control over
over how commands output are printed to the console how commands output are printed to the console (see [documentation][output] for
(see [documentation][output] for more info): more info):
```yaml ```yaml
version: '2' version: '2'
@@ -137,8 +136,7 @@ tasks:
## Version 2.2 ## Version 2.2
Version 2.2 comes with a global `includes` options to include other Version 2.2 comes with a global `includes` options to include other Taskfiles:
Taskfiles:
```yaml ```yaml
version: '2' version: '2'
@@ -175,10 +173,10 @@ These are some major changes done on `v3`:
- Task's output will now be colored - Task's output will now be colored
- Added support for `.env` like files - Added support for `.env` like files
- Added `label:` setting to task so one can override how the task name - Added `label:` setting to task so one can override how the task name appear in
appear in the logs the logs
- A global `method:` was added to allow setting the default method, - A global `method:` was added to allow setting the default method, and Task's
and Task's default changed to `checksum` default changed to `checksum`
- Two magic variables were added when using `status:`: `CHECKSUM` and - Two magic variables were added when using `status:`: `CHECKSUM` and
`TIMESTAMP` which contains, respectively, the md5 checksum and greatest `TIMESTAMP` which contains, respectively, the md5 checksum and greatest
modification timestamp of the files listed on `sources:` modification timestamp of the files listed on `sources:`
@@ -220,10 +218,10 @@ tasks:
print: echo "Hello, World!" print: echo "Hello, World!"
``` ```
- There was a major refactor on how variables are handled. They're now easier - There was a major refactor on how variables are handled. They're now easier to
to understand. The `expansions:` setting was removed as it became unncessary. understand. The `expansions:` setting was removed as it became unncessary.
This is the order in which Task will process variables, each level can see This is the order in which Task will process variables, each level can see the
the variables set by the previous one and override those. variables set by the previous one and override those.
- Environment variables - Environment variables
- Global + CLI variables - Global + CLI variables
- Call variables - Call variables

15
docs/docs/translate.md
View File

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

381
docs/docs/usage.md
View File

@@ -7,10 +7,10 @@ sidebar_position: 3
## Getting started ## Getting started
Create a file called `Taskfile.yml` in the root of your project. Create a file called `Taskfile.yml` in the root of your project. The `cmds`
The `cmds` attribute should contain the commands of a task. attribute should contain the commands of a task. The example below allows
The example below allows compiling a Go app and uses [esbuild](https://esbuild.github.io/) to concat compiling a Go app and uses [esbuild](https://esbuild.github.io/) to concat and
and minify multiple CSS files into a single one. minify multiple CSS files into a single one.
```yaml ```yaml
version: '3' version: '3'
@@ -31,10 +31,10 @@ Running the tasks is as simple as running:
task assets build task assets build
``` ```
Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh Task uses [mvdan.cc/sh](https://mvdan.cc/sh/), a native Go sh interpreter. So
interpreter. So you can write sh/bash commands, and it will work even on you can write sh/bash commands, and it will work even on Windows, where `sh` or
Windows, where `sh` or `bash` are usually not available. Just remember any `bash` are usually not available. Just remember any executable called must be
executable called must be available by the OS or in PATH. available by the OS or in PATH.
If you omit a task name, "default" will be assumed. If you omit a task name, "default" will be assumed.
@@ -78,17 +78,16 @@ tasks:
``` ```
In this example, we can run `cd <service>` and `task up` and as long as the In this example, we can run `cd <service>` and `task up` and as long as the
`<service>` directory contains a `docker-compose.yml`, the Docker composition will be `<service>` directory contains a `docker-compose.yml`, the Docker composition
brought up. will be brought up.
### Running a global Taskfile ### Running a global Taskfile
If you call Task with the `--global` (alias `-g`) flag, it will look for your 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 home directory instead of your working directory. In short, Task will look for a
a Taskfile on either `$HOME/Taskfile.yml` or `$HOME/Taskfile.yaml` paths. Taskfile on either `$HOME/Taskfile.yml` or `$HOME/Taskfile.yaml` paths.
This is useful to have automation that you can run from anywhere in your This is useful to have automation that you can run from anywhere in your system!
system!
:::info :::info
@@ -132,8 +131,8 @@ tasks:
GREETING: Hey, there! GREETING: Hey, there!
``` ```
Additionally, you can set global environment variables that will be available Additionally, you can set global environment variables that will be available to
to all tasks: all tasks:
```yaml ```yaml
version: '3' version: '3'
@@ -149,8 +148,8 @@ tasks:
:::info :::info
`env` supports expansion and retrieving output from a shell command `env` supports expansion and retrieving output from a shell command just like
just like variables, as you can see in the [Variables](#variables) section. variables, as you can see in the [Variables](#variables) section.
::: :::
@@ -216,7 +215,8 @@ tasks:
:::info :::info
Please note that you are not currently able to use the `dotenv` key inside included Taskfiles. Please note that you are not currently able to use the `dotenv` key inside
included Taskfiles.
::: :::
@@ -235,18 +235,19 @@ includes:
The tasks described in the given Taskfiles will be available with the informed 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 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 `documentation/Taskfile.yml` or `task docker:build` to run the `build` task from
from the `DockerTasks.yml` file. the `DockerTasks.yml` file.
Relative paths are resolved relative to the directory containing the including Taskfile. Relative paths are resolved relative to the directory containing the including
Taskfile.
### OS-specific Taskfiles ### OS-specific Taskfiles
With `version: '2'`, task automatically includes any `Taskfile_{{OS}}.yml` With `version: '2'`, task automatically includes any `Taskfile_{{OS}}.yml` if it
if it exists (for example: `Taskfile_windows.yml`, `Taskfile_linux.yml` or exists (for example: `Taskfile_windows.yml`, `Taskfile_linux.yml` or
`Taskfile_darwin.yml`). Since this behavior was a bit too implicit, it `Taskfile_darwin.yml`). Since this behavior was a bit too implicit, it was
was removed on version 3, but you still can have a similar behavior by removed on version 3, but you still can have a similar behavior by explicitly
explicitly importing these files: importing these files:
```yaml ```yaml
version: '3' version: '3'
@@ -257,9 +258,9 @@ includes:
### Directory of included Taskfile ### Directory of included Taskfile
By default, included Taskfile's tasks are run in the current directory, even By default, included Taskfile's tasks are run in the current directory, even if
if the Taskfile is in another directory, but you can force its tasks to run the Taskfile is in another directory, but you can force its tasks to run in
in another directory by using this alternative syntax: another directory by using this alternative syntax:
```yaml ```yaml
version: '3' version: '3'
@@ -293,15 +294,16 @@ includes:
tasks: tasks:
greet: greet:
cmds: cmds:
- echo "This command can still be successfully executed if ./tests/Taskfile.yml does not exist" - echo "This command can still be successfully executed if
./tests/Taskfile.yml does not exist"
``` ```
### Internal includes ### Internal includes
Includes marked as internal will set all the tasks of the included file to be 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). internal as well (see the [Internal tasks](#internal-tasks) section below). This
This is useful when including utility tasks that are not intended to be used is useful when including utility tasks that are not intended to be used directly
directly by the user. by the user.
```yaml ```yaml
version: '3' version: '3'
@@ -314,8 +316,8 @@ includes:
### Vars of included Taskfiles ### Vars of included Taskfiles
You can also specify variables when including a Taskfile. This may be useful You can also specify variables when including a Taskfile. This may be useful for
for having reusable Taskfile that can be tweaked or even included more than once: having reusable Taskfile that can be tweaked or even included more than once:
```yaml ```yaml
version: '3' version: '3'
@@ -334,9 +336,9 @@ includes:
### Namespace aliases ### Namespace aliases
When including a Taskfile, you can give the namespace a list of `aliases`. When including a Taskfile, you can give the namespace a list of `aliases`. This
This works in the same way as [task aliases](#task-aliases) and can be used works in the same way as [task aliases](#task-aliases) and can be used together
together to create shorter and easier-to-type commands. to create shorter and easier-to-type commands.
```yaml ```yaml
version: '3' version: '3'
@@ -349,9 +351,10 @@ includes:
:::info :::info
Vars declared in the included Taskfile have preference over the Vars declared in the included Taskfile have preference over the variables in the
variables in the including Taskfile! If you want a variable in an included Taskfile to be overridable, including Taskfile! If you want a variable in an included Taskfile to be
use the [default function](https://go-task.github.io/slim-sprig/defaults.html): overridable, use the
[default function](https://go-task.github.io/slim-sprig/defaults.html):
`MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`. `MY_VAR: '{{.MY_VAR | default "my-default-value"}}'`.
::: :::
@@ -404,8 +407,8 @@ If the directory does not exist, `task` creates it.
> another. If you want to force tasks to run serially, take a look at the > another. If you want to force tasks to run serially, take a look at the
> [Calling Another Task](#calling-another-task) section below. > [Calling Another Task](#calling-another-task) section below.
You may have tasks that depend on others. Just pointing them on `deps` will You may have tasks that depend on others. Just pointing them on `deps` will make
make them run automatically before running the parent task: them run automatically before running the parent task:
```yaml ```yaml
version: '3' version: '3'
@@ -447,13 +450,13 @@ performance.
:::tip :::tip
You can also make the tasks given by the command line run in parallel by You can also make the tasks given by the command line run in parallel by using
using the `--parallel` flag (alias `-p`). Example: `task --parallel js css`. the `--parallel` flag (alias `-p`). Example: `task --parallel js css`.
::: :::
If you want to pass information to dependencies, you can do that the same If you want to pass information to dependencies, you can do that the same manner
manner as you would to [call another task](#calling-another-task): as you would to [call another task](#calling-another-task):
```yaml ```yaml
version: '3' version: '3'
@@ -462,9 +465,9 @@ tasks:
default: default:
deps: deps:
- task: echo_sth - task: echo_sth
vars: {TEXT: "before 1"} vars: { TEXT: 'before 1' }
- task: echo_sth - task: echo_sth
vars: {TEXT: "before 2"} vars: { TEXT: 'before 2' }
cmds: cmds:
- echo "after" - echo "after"
@@ -475,16 +478,17 @@ tasks:
## Platform specific tasks and commands ## Platform specific tasks and commands
If you want to restrict the running of tasks to explicit platforms, this can be achieved If you want to restrict the running of tasks to explicit platforms, this can be
using the `platforms:` key. Tasks can be restricted to a specific OS, architecture or a achieved using the `platforms:` key. Tasks can be restricted to a specific OS,
combination of both. architecture or a combination of both. On a mismatch, the task or command will
On a mismatch, the task or command will be skipped, and no error will be thrown. be skipped, and no error will be thrown.
The values allowed as OS or Arch are valid `GOOS` and `GOARCH` values, as The values allowed as OS or Arch are valid `GOOS` and `GOARCH` values, as
defined by the Go language defined by the Go language
[here](https://github.com/golang/go/blob/master/src/go/build/syslist.go). [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: The `build-windows` task below will run only on Windows, and on any
architecture:
```yaml ```yaml
version: '3' version: '3'
@@ -548,8 +552,8 @@ tasks:
## Calling another task ## Calling another task
When a task has many dependencies, they are executed concurrently. This will 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 often result in a faster build pipeline. However, in some situations, you may
to call other tasks serially. In this case, use the following syntax: need to call other tasks serially. In this case, use the following syntax:
```yaml ```yaml
version: '3' version: '3'
@@ -586,7 +590,7 @@ tasks:
greet-pessimistically: greet-pessimistically:
cmds: cmds:
- task: greet - task: greet
vars: {RECIPIENT: "Cruel World"} vars: { RECIPIENT: 'Cruel World' }
``` ```
The above syntax is also supported in `deps`. The above syntax is also supported in `deps`.
@@ -632,13 +636,13 @@ tasks:
- public/bundle.css - public/bundle.css
``` ```
`sources` and `generates` can be files or file patterns. When given, `sources` and `generates` can be files or file patterns. When given, Task will
Task will compare the checksum of the source files to determine if it's compare the checksum of the source files to determine if it's necessary to run
necessary to run the task. If not, it will just print a message like the task. If not, it will just print a message like `Task "js" is up to date`.
`Task "js" is up to date`.
If you prefer this check to be made by the modification timestamp of the files, If you prefer this check to be made by the modification timestamp of the files,
instead of its checksum (content), just set the `method` property to `timestamp`. instead of its checksum (content), just set the `method` property to
`timestamp`.
```yaml ```yaml
version: '3' version: '3'
@@ -664,8 +668,8 @@ example.
By default, task stores checksums on a local `.task` directory in the project's 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` 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 (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 that is committed it may make sense to commit the checksum of that task as well,
well, though). though).
If you want these files to be stored in another directory, you can set a 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 `TASK_TEMP_DIR` environment variable in your machine. It can contain a relative
@@ -681,14 +685,13 @@ export TASK_TEMP_DIR='~/.task'
:::info :::info
Each task has only one checksum stored for its `sources`. If you want Each task has only one checksum stored for its `sources`. If you want to
to distinguish a task by any of its input variables, you can add those distinguish a task by any of its input variables, you can add those variables as
variables as part of the task's label, and it will be considered a different part of the task's label, and it will be considered a different task.
task.
This is useful if you want to run a task once for each distinct set of This is useful if you want to run a task once for each distinct set of inputs
inputs until the sources actually change. For example, if the sources depend until the sources actually change. For example, if the sources depend on the
on the value of a variable, or you if you want the task to rerun if some arguments value of a variable, or you if you want the task to rerun if some arguments
change even if the source has not. change even if the source has not.
::: :::
@@ -701,16 +704,16 @@ The method `none` skips any validation and always run the task.
:::info :::info
For the `checksum` (default) or `timestamp` method to work, it is only necessary to For the `checksum` (default) or `timestamp` method to work, it is only necessary
inform the source files. to inform the source files. When the `timestamp` method is used, the last time
When the `timestamp` method is used, the last time of the running the task is considered as a generate. of the running the task is considered as a generate.
::: :::
### Using programmatic checks to indicate a task is up to date ### Using programmatic checks to indicate a task is up to date
Alternatively, you can inform a sequence of tests as `status`. If no error Alternatively, you can inform a sequence of tests as `status`. If no error is
is returned (exit status 0), the task is considered up-to-date: returned (exit status 0), the task is considered up-to-date:
```yaml ```yaml
version: '3' version: '3'
@@ -728,20 +731,20 @@ tasks:
- test -f directory/file2.txt - test -f directory/file2.txt
``` ```
Normally, you would use `sources` in combination with Normally, you would use `sources` in combination with `generates` - but for
`generates` - but for tasks that generate remote artifacts (Docker images, tasks that generate remote artifacts (Docker images, deploys, CD releases) the
deploys, CD releases) the checksum source and timestamps require either checksum source and timestamps require either access to the artifact or for an
access to the artifact or for an out-of-band refresh of the `.checksum` out-of-band refresh of the `.checksum` fingerprint file.
fingerprint file.
Two special variables `{{.CHECKSUM}}` and `{{.TIMESTAMP}}` are available Two special variables `{{.CHECKSUM}}` and `{{.TIMESTAMP}}` are available for
for interpolation within `status` commands, depending on the method assigned interpolation within `status` commands, depending on the method assigned to
to fingerprint the sources. Only `source` globs are fingerprinted. fingerprint the sources. Only `source` globs are fingerprinted.
Note that the `{{.TIMESTAMP}}` variable is a "live" Go `time.Time` struct, and 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. 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. 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 You can use `--force` or `-f` if you want to force a task to run even when
up-to-date. up-to-date.
@@ -749,7 +752,8 @@ up-to-date.
Also, `task --status [tasks]...` will exit with a non-zero exit code if any of Also, `task --status [tasks]...` will exit with a non-zero exit code if any of
the tasks are not up-to-date. the tasks are not up-to-date.
`status` can be combined with the [fingerprinting](#by-fingerprinting-locally-generated-files-and-their-sources) `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 to have a task run if either the the source/generated artifacts changes, or the
programmatic check fails: programmatic check fails:
@@ -775,11 +779,11 @@ tasks:
### Using programmatic checks to cancel the execution of a task and its dependencies ### Using programmatic checks to cancel the execution of a task and its dependencies
In addition to `status` checks, `preconditions` checks are In addition to `status` checks, `preconditions` checks are the logical inverse
the logical inverse of `status` checks. That is, if you need a certain set of of `status` checks. That is, if you need a certain set of conditions to be
conditions to be _true_ you can use the `preconditions` stanza. _true_ you can use the `preconditions` stanza. `preconditions` are similar to
`preconditions` are similar to `status` lines, except they support `sh` `status` lines, except they support `sh` expansion, and they SHOULD all
expansion, and they SHOULD all return 0. return 0.
```yaml ```yaml
version: '3' version: '3'
@@ -793,21 +797,20 @@ tasks:
# test existence of files # test existence of files
preconditions: preconditions:
- test -f .env - test -f .env
- sh: "[ 1 = 0 ]" - sh: '[ 1 = 0 ]'
msg: "One doesn't equal Zero, Halting" msg: "One doesn't equal Zero, Halting"
``` ```
Preconditions can set specific failure messages that can tell Preconditions can set specific failure messages that can tell a user what steps
a user what steps to take using the `msg` field. to take using the `msg` field.
If a task has a dependency on a sub-task with a precondition, and that 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 precondition is not met - the calling task will fail. Note that a task executed
executed with a failing precondition will not run unless `--force` is with a failing precondition will not run unless `--force` is given.
given.
Unlike `status`, which will skip a task if it is up to date and continue 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 executing tasks that depend on it, a `precondition` will fail a task, along with
with any other tasks that depend on it. any other tasks that depend on it.
```yaml ```yaml
version: '3' version: '3'
@@ -815,7 +818,7 @@ version: '3'
tasks: tasks:
task-will-fail: task-will-fail:
preconditions: preconditions:
- sh: "exit 1" - sh: 'exit 1'
task-will-also-fail: task-will-also-fail:
deps: deps:
@@ -829,17 +832,16 @@ tasks:
### Limiting when tasks run ### Limiting when tasks run
If a task executed by multiple `cmds` or multiple `deps` you can control If a task executed by multiple `cmds` or multiple `deps` you can control when it
when it is executed using `run`. `run` can also be set at the root is executed using `run`. `run` can also be set at the root of the Taskfile to
of the Taskfile to change the behavior of all the tasks unless explicitly change the behavior of all the tasks unless explicitly overridden.
overridden.
Supported values for `run`: Supported values for `run`:
* `always` (default) always attempt to invoke the task regardless of the - `always` (default) always attempt to invoke the task regardless of the number
number of previous executions of previous executions
* `once` only invoke this task once regardless of the number of references - `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 - `when_changed` only invokes the task once for each unique set of variables
passed into the task passed into the task
```yaml ```yaml
@@ -870,14 +872,16 @@ tasks:
## Variables ## Variables
When doing interpolation of variables, Task will look for the below. When doing interpolation of variables, Task will look for the below. They are
They are listed below in order of importance (i.e. most important first): listed below in order of importance (i.e. most important first):
- Variables declared in the task definition - Variables declared in the task definition
- Variables given while calling a task from another - Variables given while calling a task from another (See
(See [Calling another task](#calling-another-task) above) [Calling another task](#calling-another-task) above)
- Variables of the [included Taskfile](#including-other-taskfiles) (when the task is included) - Variables of the [included Taskfile](#including-other-taskfiles) (when the
- Variables of the [inclusion of the Taskfile](#vars-of-included-taskfiles) (when the task is included) 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) - Global variables (those declared in the `vars:` option in the Taskfile)
- Environment variables - Environment variables
@@ -894,8 +898,8 @@ A special variable `.TASK` is always available containing the task name.
::: :::
Since some shells do not support the above syntax to set environment variables 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 (Windows) tasks also accept a similar style when not at the beginning of the
the command. command.
```bash ```bash
$ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!" $ task write-file FILE=file.txt "CONTENT=Hello, World!" print "MESSAGE=All done!"
@@ -950,9 +954,8 @@ This works for all types of variables.
## Forwarding CLI arguments to commands ## Forwarding CLI arguments to commands
If `--` is given in the CLI, all following parameters are added to a If `--` is given in the CLI, all following parameters are added to a special
special `.CLI_ARGS` variable. This is useful to forward arguments to another `.CLI_ARGS` variable. This is useful to forward arguments to another command.
command.
The below example will run `yarn install`. The below example will run `yarn install`.
@@ -971,9 +974,9 @@ tasks:
## Doing task cleanup with `defer` ## Doing task cleanup with `defer`
With the `defer` keyword, it's possible to schedule cleanup to be run once With the `defer` keyword, it's possible to schedule cleanup to be run once the
the task finishes. The difference with just putting it as the last command is task finishes. The difference with just putting it as the last command is that
that this command will run even when the task fails. this command will run even when the task fails.
In the example below, `rm -rf tmpdir/` will run even if the third command fails: In the example below, `rm -rf tmpdir/` will run even if the third command fails:
@@ -1014,11 +1017,12 @@ commands are executed in the reverse order if you schedule multiple of them.
## Go's template engine ## Go's template engine
Task parse commands as [Go's template engine][gotemplate] before executing Task parse commands as [Go's template engine][gotemplate] before executing them.
them. Variables are accessible through dot syntax (`.VARNAME`). Variables are accessible through dot syntax (`.VARNAME`).
All functions by the Go's [slim-sprig lib](https://go-task.github.io/slim-sprig/) All functions by the Go's
are available. The following example gets the current date in a given format: [slim-sprig lib](https://go-task.github.io/slim-sprig/) are available. The
following example gets the current date in a given format:
```yaml ```yaml
version: '3' version: '3'
@@ -1033,21 +1037,22 @@ Task also adds the following functions:
- `OS`: Returns the operating system. Possible values are "windows", "linux", - `OS`: Returns the operating system. Possible values are "windows", "linux",
"darwin" (macOS) and "freebsd". "darwin" (macOS) and "freebsd".
- `ARCH`: return the architecture Task was compiled to: "386", "amd64", "arm" - `ARCH`: return the architecture Task was compiled to: "386", "amd64", "arm" or
or "s390x". "s390x".
- `splitLines`: Splits Unix (\n) and Windows (\r\n) styled newlines. - `splitLines`: Splits Unix (\n) and Windows (\r\n) styled newlines.
- `catLines`: Replaces Unix (\n) and Windows (\r\n) styled newlines with a space. - `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 `\` - `toSlash`: Does nothing on Unix, but on Windows converts a string from `\`
path format to `/`. path format to `/`.
- `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows - `fromSlash`: Opposite of `toSlash`. Does nothing on Unix, but on Windows
converts a string from `/` path format to `\`. converts a string from `/` path format to `\`.
- `exeExt`: Returns the right executable extension for the current OS - `exeExt`: Returns the right executable extension for the current OS (`".exe"`
(`".exe"` for Windows, `""` for others). for Windows, `""` for others).
- `shellQuote`: Quotes a string to make it safe for use in shell scripts. - `shellQuote`: Quotes a string to make it safe for use in shell scripts. Task
Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote) uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/syntax#Quote)
for this. The Bash dialect is assumed. for this. The Bash dialect is assumed.
- `splitArgs`: Splits a string as if it were a command's arguments. - `splitArgs`: Splits a string as if it were a command's arguments. Task uses
Task uses [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields) [this Go function](https://pkg.go.dev/mvdan.cc/sh/v3@v3.4.0/shell#Fields)
Example: Example:
@@ -1076,8 +1081,8 @@ tasks:
## Help ## Help
Running `task --list` (or `task -l`) lists all tasks with a description. Running `task --list` (or `task -l`) lists all tasks with a description. The
The following Taskfile: following Taskfile:
```yaml ```yaml
version: '3' version: '3'
@@ -1113,8 +1118,8 @@ If you want to see all tasks, there's a `--list-all` (alias `-a`) flag as well.
## Display summary of task ## Display summary of task
Running `task --summary task-name` will show a summary of a task. Running `task --summary task-name` will show a summary of a task. The following
The following Taskfile: Taskfile:
```yaml ```yaml
version: '3' version: '3'
@@ -1135,7 +1140,7 @@ tasks:
- your-build-tool - your-build-tool
``` ```
with running ``task --summary release`` would print the following output: with running `task --summary release` would print the following output:
``` ```
task: release task: release
@@ -1151,10 +1156,11 @@ dependencies:
commands: commands:
- your-release-tool - 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*. 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 ## Task aliases
@@ -1162,8 +1168,8 @@ 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 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 command line, when [calling sub-tasks](#calling-another-task) in your Taskfile
and when [including tasks](#including-other-taskfiles) with aliases from another and when [including tasks](#including-other-taskfiles) with aliases from another
Taskfile. They can also be used together with [namespace Taskfile. They can also be used together with
aliases](#namespace-aliases). [namespace aliases](#namespace-aliases).
```yaml ```yaml
version: '3' version: '3'
@@ -1182,9 +1188,9 @@ tasks:
## Overriding task name ## Overriding task name
Sometimes you may want to override the task name printed on the summary, up-to-date Sometimes you may want to override the task name printed on the summary,
messages to STDOUT, etc. In this case, you can just set `label:`, which can also up-to-date messages to STDOUT, etc. In this case, you can just set `label:`,
be interpolated with variables: which can also be interpolated with variables:
```yaml ```yaml
version: '3' version: '3'
@@ -1206,8 +1212,8 @@ tasks:
## Silent mode ## Silent mode
Silent mode disables the echoing of commands before Task runs it. Silent mode disables the echoing of commands before Task runs it. For the
For the following Taskfile: following Taskfile:
```yaml ```yaml
version: '3' version: '3'
@@ -1233,7 +1239,7 @@ Print something
There are four ways to enable silent mode: There are four ways to enable silent mode:
* At command level: - At command level:
```yaml ```yaml
version: '3' version: '3'
@@ -1245,7 +1251,7 @@ tasks:
silent: true silent: true
``` ```
* At task level: - At task level:
```yaml ```yaml
version: '3' version: '3'
@@ -1257,7 +1263,7 @@ tasks:
silent: true silent: true
``` ```
* Globally at Taskfile level: - Globally at Taskfile level:
```yaml ```yaml
version: '3' version: '3'
@@ -1270,7 +1276,7 @@ tasks:
- echo "Print something" - echo "Print something"
``` ```
* Or globally with `--silent` or `-s` flag - Or globally with `--silent` or `-s` flag
If you want to suppress STDOUT instead, just redirect a command to `/dev/null`: If you want to suppress STDOUT instead, just redirect a command to `/dev/null`:
@@ -1285,13 +1291,14 @@ tasks:
## Dry run mode ## Dry run mode
Dry run mode (`--dry`) compiles and steps through each task, printing the commands Dry run mode (`--dry`) compiles and steps through each task, printing the
that would be run without executing them. This is useful for debugging your Taskfiles. commands that would be run without executing them. This is useful for debugging
your Taskfiles.
## Ignore errors ## Ignore errors
You have the option to ignore errors during command execution. You have the option to ignore errors during command execution. Given the
Given the following Taskfile: following Taskfile:
```yaml ```yaml
version: '3' version: '3'
@@ -1303,8 +1310,9 @@ tasks:
- echo "Hello World" - echo "Hello World"
``` ```
Task will abort the execution after running `exit 1` because the status code `1` stands for `EXIT_FAILURE`. Task will abort the execution after running `exit 1` because the status code `1`
However, it is possible to continue with execution using `ignore_error`: stands for `EXIT_FAILURE`. However, it is possible to continue with execution
using `ignore_error`:
```yaml ```yaml
version: '3' version: '3'
@@ -1318,13 +1326,13 @@ tasks:
``` ```
`ignore_error` can also be set for a task, which means errors will be suppressed `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 for all commands. Nevertheless, keep in mind that this option will not propagate
called either by `deps` or `cmds`! to other tasks called either by `deps` or `cmds`!
## Output syntax ## Output syntax
By default, Task just redirects the STDOUT and STDERR of the running commands By default, Task just redirects the STDOUT and STDERR of the running commands to
to the shell in real-time. This is good for having live feedback for logging 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 printed by commands, but the output can become messy if you have multiple
commands running simultaneously and printing lots of stuff. commands running simultaneously and printing lots of stuff.
@@ -1350,11 +1358,12 @@ 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 finishes, so you will not have live feedback for commands that take a long time
to run. to run.
When using the `group` output, you can optionally provide a templated message When using the `group` output, you can optionally provide a templated message to
to print at the start and end of the group. This can be useful for instructing print at the start and end of the group. This can be useful for instructing CI
CI systems to group all of the output for a given task, such as with 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) [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). 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 ```yaml
version: '3' version: '3'
@@ -1378,8 +1387,9 @@ Hello, World!
::endgroup:: ::endgroup::
``` ```
When using the `group` output, you may swallow the output of the executed command When using the `group` output, you may swallow the output of the executed
on standard output and standard error if it does not fail (zero exit code). command on standard output and standard error if it does not fail (zero exit
code).
```yaml ```yaml
version: '3' version: '3'
@@ -1406,7 +1416,7 @@ 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 `[task-name] ` as the prefix, but you can customize the prefix for a command
with the `prefix:` attribute: with the `prefix:` attribute:
```yaml ```yaml
version: '3' version: '3'
output: prefixed output: prefixed
@@ -1415,16 +1425,16 @@ tasks:
default: default:
deps: deps:
- task: print - task: print
vars: {TEXT: foo} vars: { TEXT: foo }
- task: print - task: print
vars: {TEXT: bar} vars: { TEXT: bar }
- task: print - task: print
vars: {TEXT: baz} vars: { TEXT: baz }
print: print:
cmds: cmds:
- echo "{{.TEXT}}" - echo "{{.TEXT}}"
prefix: "print-{{.TEXT}}" prefix: 'print-{{.TEXT}}'
silent: true silent: true
``` ```
@@ -1466,8 +1476,8 @@ an issue about it.
## Short task syntax ## Short task syntax
Starting on Task v3, you can now write tasks with a shorter syntax if they Starting on Task v3, you can now write tasks with a shorter syntax if they have
have the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc): the default settings (e.g. no custom `env:`, `vars:`, `desc:`, `silent:` , etc):
```yaml ```yaml
version: '3' version: '3'
@@ -1484,7 +1494,8 @@ tasks:
It's possible to specify options to the It's possible to specify options to the
[`set`](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html) [`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) 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. builtins. This can be added at global, task or command level.
```yaml ```yaml
@@ -1507,12 +1518,14 @@ Keep in mind that not all options are available in the
## Watch tasks ## Watch tasks
With the flags `--watch` or `-w` task will watch for file changes With the flags `--watch` or `-w` task will watch for file changes and run the
and run the task again. This requires the `sources` attribute to be given, task again. This requires the `sources` attribute to be given, so task knows
so task knows which files to watch. which files to watch.
The default watch interval is 5 seconds, but it's possible to change it by 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 passing it either setting `interval: '500ms'` in the root of the Taskfile passing it as an
as an argument like `--interval=500ms`. argument like `--interval=500ms`.
<!-- prettier-ignore-start -->
[gotemplate]: https://golang.org/pkg/text/template/ [gotemplate]: https://golang.org/pkg/text/template/
<!-- prettier-ignore-end -->

11
docs/prettier.config.js
View File

@@ -1,4 +1,13 @@
module.exports = { module.exports = {
trailingComma: 'none', trailingComma: 'none',
singleQuote: true singleQuote: true,
overrides: [
{
files: '*.md',
options: {
printWidth: 80,
proseWrap: 'always'
}
}
]
}; };