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

6
README.md
View File

@ -18,10 +18,12 @@
<div align="center">
| [Appwrite][appwrite] |
| - |
| [Appwrite][appwrite] |
| ------------------------------------------------------ |
| [![Appwrite](/docs/static/img/appwrite.svg)][appwrite] |
</div>
<!-- prettier-ignore-start -->
[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
If `--` is given, all remaning arguments will be assigned to a special `CLI_ARGS`
variable
If `--` is given, all remaning arguments will be assigned to a special
`CLI_ARGS` variable
:::
| Short | Flag | Type | Default | Description |
| - | - | - | - | - |
| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed. |
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
| | `--summary` | `bool` | `false` | Show summary about a task. |
| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
| | `--version` | `bool` | `false` | Show Task version. |
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. |
| Short | Flag | Type | Default | Description |
| ----- | --------------------------- | -------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-c` | `--color` | `bool` | `true` | Colored output. Enabled by default. Set flag to `false` or use `NO_COLOR=1` to disable. |
| `-C` | `--concurrency` | `int` | `0` | Limit number tasks to run concurrently. Zero means unlimited. |
| `-d` | `--dir` | `string` | Working directory | Sets directory of execution. |
| `-n` | `--dry` | `bool` | `false` | Compiles and prints tasks in the order that they would be run, without executing them. |
| `-x` | `--exit-code` | `bool` | `false` | Pass-through the exit code of the task command. |
| `-f` | `--force` | `bool` | `false` | Forces execution even when the task is up-to-date. |
| `-g` | `--global` | `bool` | `false` | Runs global Taskfile, from `$HOME/Taskfile.{yml,yaml}`. |
| `-h` | `--help` | `bool` | `false` | Shows Task usage. |
| `-i` | `--init` | `bool` | `false` | Creates a new Taskfile.yml in the current folder. |
| `-I` | `--interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `-l` | `--list` | `bool` | `false` | Lists tasks with description of current Taskfile. |
| `-a` | `--list-all` | `bool` | `false` | Lists tasks with or without a description. |
| | `--sort` | `string` | `default` | Changes the order of the tasks when listed. |
| | `--json` | `bool` | `false` | See [JSON Output](#json-output) |
| `-o` | `--output` | `string` | Default set in the Taskfile or `intervealed` | Sets output style: [`interleaved`/`group`/`prefixed`]. |
| | `--output-group-begin` | `string` | | Message template to print before a task's grouped output. |
| | `--output-group-end` | `string` | | Message template to print after a task's grouped output. |
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| | `--status` | `bool` | `false` | Exits with non-zero exit code if any of the given tasks is not up-to-date. |
| | `--summary` | `bool` | `false` | Show summary about a task. |
| `-t` | `--taskfile` | `string` | `Taskfile.yml` or `Taskfile.yaml` | |
| `-v` | `--verbose` | `bool` | `false` | Enables verbose mode. |
| | `--version` | `bool` | `false` | Show Task version. |
| `-w` | `--watch` | `bool` | `false` | Enables watch of the given task. |
## 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
{
@ -68,7 +70,7 @@ When using the `--json` flag in combination with either the `--list` or `--list-
"column": 3,
"taskfile": "/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:
| Var | Description |
| - | - |
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `TASK` | The name of the current task. |
| `ROOT_DIR` | The absolute path of the root Taskfile. |
| `TASKFILE_DIR` | The absolute path of the included Taskfile. |
| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
| `TIMESTAMP` | The date object of the greatest timestamp of the files listes in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. |
| Var | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `TASK` | The name of the current task. |
| `ROOT_DIR` | The absolute path of the root Taskfile. |
| `TASKFILE_DIR` | The absolute path of the included Taskfile. |
| `USER_WORKING_DIR` | The absolute path of the directory `task` was called from. |
| `CHECKSUM` | The checksum of the files listed in `sources`. Only available within the `status` prop and if method is set to `checksum`. |
| `TIMESTAMP` | The date object of the greatest timestamp of the files listes in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. |
## ENV
Some environment variables can be overriden to adjust Task behavior.
| ENV | Default | Description |
| - | - | - |
| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
| `TASK_COLOR_RESET` | `0` | Color used for white. |
| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
| `TASK_COLOR_GREEN` | `32` | Color used for green. |
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
| `TASK_COLOR_RED` | `31` | Color used for red. |
| `FORCE_COLOR` | | Force color output usage. |
| ENV | Default | Description |
| -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. |
| `TASK_COLOR_RESET` | `0` | Color used for white. |
| `TASK_COLOR_BLUE` | `34` | Color used for blue. |
| `TASK_COLOR_GREEN` | `32` | Color used for green. |
| `TASK_COLOR_CYAN` | `36` | Color used for cyan. |
| `TASK_COLOR_YELLOW` | `33` | Color used for yellow. |
| `TASK_COLOR_MAGENTA` | `35` | Color used for magenta. |
| `TASK_COLOR_RED` | `31` | Color used for red. |
| `FORCE_COLOR` | | Force color output usage. |
## Taskfile Schema
| Attribute | Type | Default | Description |
| - | - | - | - |
| `version` | `string` | | Version of the Taskfile. The current version is `3`. |
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
| `vars` | [`map[string]Variable`](#variable) | | A set of global variables. |
| `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. |
| `tasks` | [`map[string]Task`](#task) | | A set of task definitions. |
| `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `run` | `string` | `always` | Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`. |
| `interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
| Attribute | Type | Default | Description |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version` | `string` | | Version of the Taskfile. The current version is `3`. |
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overriden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
| `includes` | [`map[string]Include`](#include) | | Additional Taskfiles to be included. |
| `vars` | [`map[string]Variable`](#variable) | | A set of global variables. |
| `env` | [`map[string]Variable`](#variable) | | A set of global environment variables. |
| `tasks` | [`map[string]Task`](#task) | | A set of task definitions. |
| `silent` | `bool` | `false` | Default 'silent' options for this Taskfile. If `false`, can be overidden with `true` in a task by task basis. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `run` | `string` | `always` | Default 'run' option for this Taskfile. Available options: `always`, `once` and `when_changed`. |
| `interval` | `string` | `5s` | Sets a different watch interval when using `--watch`, the default being 5 seconds. This string should be a valid [Go Duration](https://pkg.go.dev/time#ParseDuration). |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
### Include
| Attribute | Type | Default | Description |
| - | - | - | - |
| `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. |
| `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
| `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
| `internal` | `bool` | `false` | Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`. |
| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |
| Attribute | Type | Default | Description |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. |
| `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
| `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
| `internal` | `bool` | `false` | Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`. |
| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |
:::info
Informing only a string like below is equivalent to setting that value to the `taskfile` attribute.
Informing only a string like below is equivalent to setting that value to the
`taskfile` attribute.
```yaml
includes:
@ -148,10 +151,10 @@ includes:
### Variable
| Attribute | Type | Default | Description |
| - | - | - | - |
| *itself* | `string` | | A static value that will be set to the variable. |
| `sh` | `string` | | A shell command. The output (`STDOUT`) will be assigned to the variable. |
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------ |
| _itself_ | `string` | | A static value that will be set to the variable. |
| `sh` | `string` | | A shell command. The output (`STDOUT`) will be assigned to the variable. |
:::info
@ -168,32 +171,32 @@ vars:
### Task
| Attribute | Type | Default | Description |
| - | - | - | - |
| `cmds` | [`[]Command`](#command) | | A list of shell commands to be executed. |
| `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. |
| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. |
| `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. |
| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. |
| `aliases` | `[]string` | | A list of alternative names by which the task can be called. |
| `sources` | `[]string` | | A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. |
| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. |
| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. |
| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `silent` | `bool` | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden. |
| `interactive` | `bool` | `false` | Tells task that the command is interactive. |
| `internal` | `bool` | `false` | Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`. |
| `method` | `string` | `checksum` | Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task. |
| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. |
| `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Task will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
| Attribute | Type | Default | Description |
| --------------- | ---------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmds` | [`[]Command`](#command) | | A list of shell commands to be executed. |
| `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. |
| `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. |
| `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. |
| `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. |
| `aliases` | `[]string` | | A list of alternative names by which the task can be called. |
| `sources` | `[]string` | | A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. |
| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. |
| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. |
| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. |
| `dotenv` | `[]string` | | A list of `.env` file paths to be parsed. |
| `silent` | `bool` | `false` | Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`. When combined with the `--list` flag, task descriptions will be hidden. |
| `interactive` | `bool` | `false` | Tells task that the command is interactive. |
| `internal` | `bool` | `false` | Stops a task from being callable on the command line. It will also be omitted from the output when used with `--list`. |
| `method` | `string` | `checksum` | Defines which method is used to check the task is up-to-date. `timestamp` will compare the timestamp of the sources and generates files. `checksum` will check the checksum (You probably want to ignore the .task folder in your .gitignore file). `none` skips any validation and always run the task. |
| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. |
| `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Task will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
:::info
@ -216,17 +219,17 @@ tasks:
#### Command
| Attribute | Type | Default | Description |
| - | - | - | - |
| `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. |
| `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`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. |
| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Command will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `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`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. |
| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/master/src/go/build/syslist.go). Command will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
:::info
@ -244,10 +247,10 @@ tasks:
#### Dependency
| Attribute | Type | Default | Description |
| - | - | - | - |
| `task` | `string` | | The task to be execute as a dependency. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to this task. |
| Attribute | Type | Default | Description |
| --------- | ---------------------------------- | ------- | -------------------------------------------------------- |
| `task` | `string` | | The task to be execute as a dependency. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to this task. |
:::tip
@ -264,10 +267,10 @@ tasks:
#### Precondition
| Attribute | Type | Default | Description |
| - | - | - | - |
| `sh` | `string` | | Command to be executed. If a non-zero exit code is returned, the task errors without executing its commands. |
| `msg` | `string` | | Optional message to print if the precondition isn't met. |
| Attribute | Type | Default | Description |
| --------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `sh` | `string` | | Command to be executed. If a non-zero exit code is returned, the task errors without executing its commands. |
| `msg` | `string` | | Optional message to print if the precondition isn't met. |
:::tip

51
docs/docs/community.md
View File

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

71
docs/docs/contributing.md
View File

@ -11,21 +11,21 @@ before submitting a PR.
## Before you start
- **Check existing work** - Is there an existing PR? Are there issues discussing
the feature/change you want to make? Please make sure you consider/address these
discussions in your work.
the feature/change you want to make? Please make sure you consider/address
these discussions in your work.
- **Backwards compatibility** - Will your change break existing Taskfiles? It is
much more likely that your change will merged if it backwards compatible. Is
there an approach you can take that maintains this compatibility? If not,
consider opening an issue first so that API changes can be discussed before you
invest your time into a PR.
much more likely that your change will merged if it backwards compatible. Is
there an approach you can take that maintains this compatibility? If not,
consider opening an issue first so that API changes can be discussed before
you invest your time into a PR.
## 1. Setup
- **Go** - Task is written in [Go]. We always support the latest two major Go
versions, so make sure your version is recent enough.
- **Node.js** - [Node.js] is used to host Task's documentation server and is
required if you want to run this server locally.
- **Yarn** - [Yarn] is the Node.js package manager used by Task.
- **Go** - Task is written in [Go][go]. We always support the latest two major
Go versions, so make sure your version is recent enough.
- **Node.js** - [Node.js][nodejs] is used to host Task's documentation server
and is required if you want to run this server locally.
- **Yarn** - [Yarn][yarn] is the Node.js package manager used by Task.
## 2. Making changes
@ -45,15 +45,15 @@ invest your time into a PR.
### Running your changes
To run Task with working changes, you can use `go run ./cmd/task`. To run a
development build of task against a test Taskfile in `testdata`, you can use `go
run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`.
development build of task against a test Taskfile in `testdata`, you can use
`go run ./cmd/task --dir ./testdata/<my_test_dir> <task_name>`.
### Updating documentation
Task uses [Docusaurus] to host a documentation server. This can be setup and run
locally by using `task docs` (requires `nodejs` & `yarn`). All content is
written in Markdown and is located in the `docs/docs` directory. All Markdown
documents should have an 80 character line wrap limit.
Task uses [Docusaurus][docusaurus] to host a documentation server. This can be
setup and run locally by using `task docs` (requires `nodejs` & `yarn`). All
content is written in Markdown and is located in the `docs/docs` directory. All
Markdown documents should have an 80 character line wrap limit.
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
@ -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
the [Taskfile Styleguide](./styleguide.md).
If you added a new field, command or flag, ensure that you add it to the [API
Reference](./api_reference.md). New fields also need to be added to the [JSON
Schema]. The descriptions for fields in the API reference and the schema should
match.
If you added a new field, command or flag, ensure that you add it to the
[API Reference](./api_reference.md). New fields also need to be added to the
[JSON Schema][json-schema]. The descriptions for fields in the API reference and
the schema should match.
### Writing tests
@ -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?
Take a look at the list of [open issues]. We have a [good first issue] label for
simpler issues that are ideal for first time contributions.
Take a look at the list of [open issues][open-issues]. We have a [good first
issue][good-first-issue] label for simpler issues that are ideal for first time
contributions.
All kinds of contributions are welcome, whether its a typo fix or a shiny new
feature. You can also contribute by upvoting/commenting on issues, helping to
@ -112,18 +113,18 @@ answer questions or contributing to other [community projects](./community.md).
> I'm stuck, where can I get help?
If you have questions, feel free to ask them in the `#help` forum channel on our
[Discord server] or open a [Discussion] on GitHub.
[Discord server][discord-server] or open a [Discussion][discussion] on GitHub.
---
[Go]: https://go.dev
[Node.js]: https://nodejs.org/en/
[Yarn]: https://yarnpkg.com/
[Docusaurus]: https://docusaurus.io
[JSON Schema]:
https://github.com/go-task/task/blob/master/docs/static/schema.json
[open issues]: https://github.com/go-task/task/issues
[good first issue]:
https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[Discord server]: https://discord.gg/6TY36E39UK
[Discussion]: https://github.com/go-task/task/discussions
<!-- prettier-ignore-start -->
[go]: https://go.dev
[nodejs]: https://nodejs.org/en/
[yarn]: https://yarnpkg.com/
[docusaurus]: https://docusaurus.io
[json-schema]: https://github.com/go-task/task/blob/master/docs/static/schema.json
[open-issues]: https://github.com/go-task/task/issues
[good-first-issue]: https://github.com/go-task/task/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22
[discord-server]: https://discord.gg/6TY36E39UK
[discussion]: https://github.com/go-task/task/discussions
<!-- 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
higher priority on issues or something similar.
Companies who donate at least $50/month will be featured as a "Gold Sponsor"
in the website homepage and on the GitHub repository README. Make contact with
[@andreynering] with the logo you want to be shown.
Suspect businesses (gambling, casinos, etc) won't be allowed, though.
Companies who donate at least $50/month will be featured as a "Gold Sponsor" in
the website homepage and on the GitHub repository README. Make contact with
[@andreynering] with the logo you want to be shown. Suspect businesses
(gambling, casinos, etc) won't be allowed, though.
## GitHub Sponsors
The preferred way to donate to the maintainers is via GitHub Sponsors.
Just use the following links to do your donation:
The preferred way to donate to the maintainers is via GitHub Sponsors. Just use
the following links to do your donation:
- [@andreynering](https://github.com/sponsors/andreynering)
- [@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
[using this QR Code](/img/pix.png).
<!-- prettier-ignore-start -->
[@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
detect windows and run the command in Powershell directly.
- 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
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#97](https://github.com/mvdan/sh/issues/97)
[Git Bash]: https://gitforwindows.org/
[WSL]: https://learn.microsoft.com/en-us/windows/wsl/install
<!-- prettier-ignore-start -->
[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
```
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:
```bash
@ -29,9 +31,8 @@ brew install go-task
### Snap
Task is available in [Snapcraft][snapcraft], but keep in mind that your
Linux distribution should allow classic confinement for Snaps to Task work
right:
Task is available in [Snapcraft][snapcraft], but keep in mind that your Linux
distribution should allow classic confinement for Snaps to Task work right:
```bash
sudo snap install task --classic
@ -39,8 +40,8 @@ sudo snap install task --classic
### Chocolatey
If you're on Windows and have [Chocolatey][choco] installed, getting
Task is as simple as running:
If you're on Windows and have [Chocolatey][choco] installed, getting Task is as
simple as running:
```bash
choco install go-task
@ -50,15 +51,15 @@ This installation method is community owned.
### Scoop
If you're on Windows and have [Scoop][scoop] installed, getting
Task is as simple as running:
If you're on Windows and have [Scoop][scoop] installed, getting Task is as
simple as running:
```cmd
scoop install task
```
This installation method is community owned. After a new release of Task, it
may take some time until it's available on Scoop.
This installation method is community owned. After a new release of Task, it may
take some time until it's available on Scoop.
### AUR
@ -84,26 +85,29 @@ This installation method is community owned.
### Fedora
If you're on Fedora Linux you can install Task from the official
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/) repository using `dnf`:
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/)
repository using `dnf`:
```cmd
sudo dnf install go-task
```
This installation method is community owned. After a new release of Task, it
may take some time until it's available in [Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/).
This installation method is community owned. After a new release of Task, it may
take some time until it's available in
[Fedora](https://packages.fedoraproject.org/pkgs/golang-github-task/go-task/).
### Nix
If you're on NixOS or have Nix installed
you can install Task from [nixpkgs](https://github.com/NixOS/nixpkgs):
If you're on NixOS or have Nix installed you can install Task from
[nixpkgs](https://github.com/NixOS/nixpkgs):
```cmd
nix-env -iA nixpkgs.go-task
```
This installation method is community owned. After a new release of Task, it
may take some time until it's available in [nixpkgs](https://github.com/NixOS/nixpkgs).
This installation method is community owned. After a new release of Task, it may
take some time until it's available in
[nixpkgs](https://github.com/NixOS/nixpkgs).
### npm
@ -117,9 +121,8 @@ npm install -g @go-task/cli
### Winget
If you are using Windows and installed the
[winget](https://github.com/microsoft/winget-cli) package management tool,
you can install Task from
[winget-pkgs](https://github.com/microsoft/winget-pkgs).
[winget](https://github.com/microsoft/winget-cli) package management tool, you
can install Task from [winget-pkgs](https://github.com/microsoft/winget-pkgs).
```bash
winget install Task.Task
@ -129,8 +132,8 @@ winget install Task.Task
### Binary
You can download the binary from the [releases page on GitHub][releases] and
add to your `$PATH`.
You can download the binary from the [releases page on GitHub][releases] and add
to your `$PATH`.
DEB and RPM packages are also available.
@ -167,8 +170,7 @@ default.
### GitHub Actions
If you want to install Task in GitHub Actions you can try using
[this action](https://github.com/arduino/setup-task)
by the Arduino team:
[this action](https://github.com/arduino/setup-task) by the Arduino team:
```yaml
- name: Install Task
@ -184,8 +186,9 @@ This installation method is community owned.
### Go Modules
Ensure that you have a supported version of [Go][go] properly installed and setup. You can find
the minimum required version of Go in the [go.mod](https://github.com/go-task/task/blob/master/go.mod#L3) file.
Ensure that you have a supported version of [Go][go] properly installed and
setup. You can find the minimum required version of Go in the
[go.mod](https://github.com/go-task/task/blob/master/go.mod#L3) file.
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
```
<!-- prettier-ignore-start -->
[go]: https://golang.org/
[snapcraft]: https://snapcraft.io/task
[homebrew]: https://brew.sh/
@ -277,3 +281,4 @@ Invoke-Expression -Command path/to/task.ps1
[godownloader]: https://github.com/goreleaser/godownloader
[choco]: https://chocolatey.org/
[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
`$PATH` and you're done! Or you can also install using [Homebrew][homebrew],
[Snapcraft][snapcraft], or [Scoop][scoop] if you want.
- Available on CIs: by adding [this simple command](installation.md#install-script)
to install on your CI script and you're ready to use Task as part of your CI pipeline;
- Available on CIs: by adding
[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,
Task also supports Windows thanks to [this shell interpreter for Go][sh].
- Great for code generation: you can easily [prevent a task from running](/usage#prevent-unnecessary-work)
if a given set of files haven't changed since last run (based either on its
timestamp or content).
- Great for code generation: you can easily
[prevent a task from running](/usage#prevent-unnecessary-work) if a given set
of files haven't changed since last run (based either on its timestamp or
content).
## Gold Sponsors
@ -58,6 +60,7 @@ guide to check the full schema documentation and Task features.
</div>
<!-- prettier-ignore-start -->
[make]: https://www.gnu.org/software/make/
[go]: https://go.dev/
[yaml]: http://yaml.org/
@ -65,3 +68,4 @@ guide to check the full schema documentation and Task features.
[snapcraft]: https://snapcraft.io/
[scoop]: https://scoop.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
The release process of Task is done with the help of
[GoReleaser][goreleaser]. You can test the release process locally by calling
the `test-release` task of the Taskfile.
The release process of Task is done with the help of [GoReleaser][goreleaser].
You can test the release process locally by calling the `test-release` task of
the Taskfile.
[GitHub Actions](https://github.com/go-task/task/actions) should release
artifacts automatically when a new Git tag is pushed to master
(raw executables and DEB and RPM packages).
artifacts automatically when a new Git tag is pushed to master (raw executables
and DEB and RPM packages).
Since v3.15.0, raw executables can also be reproduced and verified locally by
checking out a specific tag and calling `goreleaser build`, using the Go version
@ -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
version:
* Updating the current version on [snapcraft.yaml][snapcraftyaml].
* Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel on
the [Snapcraft dashboard][snapcraftdashboard].
- Updating the current version on [snapcraft.yaml][snapcraftyaml].
- Moving both `amd64`, `armhf` and `arm64` new artifacts to the stable channel
on the [Snapcraft dashboard][snapcraftdashboard].
# Scoop
Scoop is a command-line package manager for the Windows operating system.
Scoop package manifests are maintained by the community.
Scoop owners usually take care of updating versions there by editing [this file](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json).
Scoop is a command-line package manager for the Windows operating system. Scoop
package manifests are maintained by the community. Scoop owners usually take
care of updating versions there by editing
[this file](https://github.com/ScoopInstaller/Main/blob/master/bucket/task.json).
If you think its Task version is outdated, open an issue to let us know.
# Nix
Nix is a community owned installation method. Nix package maintainers usually take care
of updating versions there by editing
Nix is a community owned installation method. Nix package maintainers usually
take care of updating versions there by editing
[this file](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/development/tools/go-task/default.nix).
If you think its Task version is outdated, open an issue to let us know.
<!-- prettier-ignore-start -->
[goreleaser]: https://goreleaser.com/
[homebrewtap]: https://github.com/go-task/homebrew-tap
[gotaskrb]: https://github.com/go-task/homebrew-tap/blob/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
[snapcraftyaml]: https://github.com/go-task/snap/blob/master/snap/snapcraft.yaml#L2
[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
At version 2, we introduced the `version:` key, to allow us to evolve Task
with new features without breaking existing Taskfiles. The new syntax is as
follows:
At version 2, we introduced the `version:` key, to allow us to evolve Task with
new features without breaking existing Taskfiles. The new syntax is as follows:
```yaml
version: '2'
@ -53,8 +52,8 @@ tasks:
- echo "Hello, World!"
```
Version 2 allows you to write global variables directly in the Taskfile,
if you don't want to create a `Taskvars.yml`:
Version 2 allows you to write global variables directly in the Taskfile, if you
don't want to create a `Taskvars.yml`:
```yaml
version: '2'
@ -88,8 +87,8 @@ vars:
FOO: foo
BAR: bar
BAZ: baz
FOOBAR: "{{.FOO}}{{.BAR}}"
FOOBARBAZ: "{{.FOOBAR}}{{.BAZ}}"
FOOBAR: '{{.FOO}}{{.BAR}}'
FOOBARBAZ: '{{.FOOBAR}}{{.BAZ}}'
tasks:
default:
@ -99,9 +98,9 @@ tasks:
## Version 2.1
Version 2.1 includes a global `output` option, to allow having more control
over how commands output are printed to the console
(see [documentation][output] for more info):
Version 2.1 includes a global `output` option, to allow having more control over
how commands output are printed to the console (see [documentation][output] for
more info):
```yaml
version: '2'
@ -137,8 +136,7 @@ tasks:
## Version 2.2
Version 2.2 comes with a global `includes` options to include other
Taskfiles:
Version 2.2 comes with a global `includes` options to include other Taskfiles:
```yaml
version: '2'
@ -175,10 +173,10 @@ These are some major changes done on `v3`:
- Task's output will now be colored
- Added support for `.env` like files
- Added `label:` setting to task so one can override how the task name
appear in the logs
- A global `method:` was added to allow setting the default method,
and Task's default changed to `checksum`
- Added `label:` setting to task so one can override how the task name appear in
the logs
- A global `method:` was added to allow setting the default method, and Task's
default changed to `checksum`
- Two magic variables were added when using `status:`: `CHECKSUM` and
`TIMESTAMP` which contains, respectively, the md5 checksum and greatest
modification timestamp of the files listed on `sources:`
@ -220,10 +218,10 @@ tasks:
print: echo "Hello, World!"
```
- There was a major refactor on how variables are handled. They're now easier
to understand. The `expansions:` setting was removed as it became unncessary.
This is the order in which Task will process variables, each level can see
the variables set by the previous one and override those.
- There was a major refactor on how variables are handled. They're now easier to
understand. The `expansions:` setting was removed as it became unncessary.
This is the order in which Task will process variables, each level can see the
variables set by the previous one and override those.
- Environment variables
- Global + CLI variables
- Call variables

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.
Do NOT edit translated markdown files directly on the GitHub repository!
We use [Crowdin][crowdin] to allow contributors on work on translations.
The repository is periodically updated with progress from Crowdin.
Do NOT edit translated markdown files directly on the GitHub repository! We use
[Crowdin][crowdin] to allow contributors on work on translations. The repository
is periodically updated with progress from Crowdin.
If you want to have access to the Crowdin project to be able to suggest
translations, please ask for access on the
[#translations channel on our Discord server][discord].
If a given language is not being shown to Crowdin yet, just ask and we can
configure it.
translations, please ask for access on the [#translations channel on our Discord
server][discord]. If a given language is not being shown to Crowdin yet, just
ask and we can configure it.
<!-- prettier-ignore-start -->
[crowdin]: https://crowdin.com/project/taskfile
[discord]: https://discord.gg/6TY36E39UK
<!-- prettier-ignore-end -->

381
docs/docs/usage.md
View File

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

11
docs/prettier.config.js
View File

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