diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 00000000..1fcfbd40 --- /dev/null +++ b/.prettierignore @@ -0,0 +1 @@ +docs/docs/changelog.md diff --git a/.prettierrc.yml b/.prettierrc.yml new file mode 100644 index 00000000..fc53a2b0 --- /dev/null +++ b/.prettierrc.yml @@ -0,0 +1,7 @@ +trailingComma: none +singleQuote: true +overrides: + - files: "*.md" + options: + printWidth: 80 + proseWrap: always diff --git a/CHANGELOG.md b/CHANGELOG.md index d726cfca..e5180811 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/README.md b/README.md index c2ed9ad1..9abaa7c7 100644 --- a/README.md +++ b/README.md @@ -18,10 +18,12 @@
-| [Appwrite][appwrite] | -| - | +| [Appwrite][appwrite] | +| ------------------------------------------------------ | | [![Appwrite](/docs/static/img/appwrite.svg)][appwrite] |
+ [appwrite]: https://appwrite.io/?utm_source=task_github&utm_medium=social&utm_campaign=task_oss_fund + diff --git a/docs/.prettierignore b/docs/.prettierignore new file mode 100644 index 00000000..1cc39a66 --- /dev/null +++ b/docs/.prettierignore @@ -0,0 +1 @@ +docs/changelog.md diff --git a/docs/docs/api_reference.md b/docs/docs/api_reference.md index 21de4743..7ccea11a 100644 --- a/docs/docs/api_reference.md +++ b/docs/docs/api_reference.md @@ -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 diff --git a/docs/docs/community.md b/docs/docs/community.md index 713f05ce..3402ea33 100644 --- a/docs/docs/community.md +++ b/docs/docs/community.md @@ -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. diff --git a/docs/docs/contributing.md b/docs/docs/contributing.md index c11006fd..3abee2bc 100644 --- a/docs/docs/contributing.md +++ b/docs/docs/contributing.md @@ -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/ `. +development build of task against a test Taskfile in `testdata`, you can use +`go run ./cmd/task --dir ./testdata/ `. ### 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 + +[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 + diff --git a/docs/docs/donate.md b/docs/docs/donate.md index 995bc2bd..52331d69 100644 --- a/docs/docs/donate.md +++ b/docs/docs/donate.md @@ -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). + [@andreynering]: https://github.com/andreynering + diff --git a/docs/docs/faq.md b/docs/docs/faq.md index b9697587..f404489e 100644 --- a/docs/docs/faq.md +++ b/docs/docs/faq.md @@ -41,7 +41,7 @@ around this limitation using one of the following methods: - Use something like `{{if eq OS "windows"}}powershell {{end}}` to detect windows and run the command in Powershell directly. - Use a shell on Windows that supports these commands as builtins, such as [Git - Bash] 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 + +[git-bash]: https://gitforwindows.org/ +[wsl]: https://learn.microsoft.com/en-us/windows/wsl/install + diff --git a/docs/docs/installation.md b/docs/docs/installation.md index 45ea922c..03748179 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -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 ``` + [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/ + diff --git a/docs/docs/intro.md b/docs/docs/intro.md index b01e5c17..5e3d14fb 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -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. + [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 + diff --git a/docs/docs/releasing.md b/docs/docs/releasing.md index 6ab76961..fb694ad1 100644 --- a/docs/docs/releasing.md +++ b/docs/docs/releasing.md @@ -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. + [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 + diff --git a/docs/docs/taskfile_versions.md b/docs/docs/taskfile_versions.md index bf5e34f9..e92ee5c8 100644 --- a/docs/docs/taskfile_versions.md +++ b/docs/docs/taskfile_versions.md @@ -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 diff --git a/docs/docs/translate.md b/docs/docs/translate.md index 40de8640..0bc97b2f 100644 --- a/docs/docs/translate.md +++ b/docs/docs/translate.md @@ -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. + [crowdin]: https://crowdin.com/project/taskfile [discord]: https://discord.gg/6TY36E39UK + diff --git a/docs/docs/usage.md b/docs/docs/usage.md index 2407b129..0b3353f1 100644 --- a/docs/docs/usage.md +++ b/docs/docs/usage.md @@ -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 ` and `task up` and as long as the -`` directory contains a `docker-compose.yml`, the Docker composition will be -brought up. +`` 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`. + [gotemplate]: https://golang.org/pkg/text/template/ + diff --git a/docs/prettier.config.js b/docs/prettier.config.js index 503a9326..8751bb83 100644 --- a/docs/prettier.config.js +++ b/docs/prettier.config.js @@ -1,4 +1,13 @@ module.exports = { trailingComma: 'none', - singleQuote: true + singleQuote: true, + overrides: [ + { + files: '*.md', + options: { + printWidth: 80, + proseWrap: 'always' + } + } + ] };