diff --git a/CHANGELOG.md b/CHANGELOG.md index a048eaa7..8c9dcc5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## v3.39.0 - 2024-09-07 - Added [Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence) diff --git a/package-lock.json b/package-lock.json index f29a4462..a38398e8 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.38.0", + "version": "3.39.0", "lockfileVersion": 2, "requires": true, "packages": { diff --git a/package.json b/package.json index 995e9eec..d29ef49f 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.38.0", + "version": "3.39.0", "description": "A task runner / simpler Make alternative written in Go", "scripts": { "postinstall": "go-npm install", diff --git a/website/docs/changelog.mdx b/website/docs/changelog.mdx index 39b6126a..47dcf1d7 100644 --- a/website/docs/changelog.mdx +++ b/website/docs/changelog.mdx @@ -5,6 +5,37 @@ sidebar_position: 14 # Changelog +## v3.39.0 - 2024-09-07 + +- Added + [Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence) + (#1038, #1633 by @vmaerten). +- Added a CI lint job to ensure that the docs are updated correctly (#1719 by + @vmaerten). +- Updated minimum required Go version to 1.22 (#1758 by @pd93). +- Expose a new `EXIT_CODE` special variable on `defer:` when a command finishes + with a non-zero exit code (#1484, #1762 by @dorimon-1 and @andreynering). +- Expose a new `ALIAS` special variable, which will contain the alias used to + call the current task. Falls back to the task name. (#1764 by @DanStory). +- Fixed `TASK_REMOTE_DIR` environment variable not working when the path was + absolute. (#1715 by @vmaerten). +- Added an option to declare an included Taskfile as flattened (#1704 by + @vmaerten). +- Added a new + [`--completion` flag](https://taskfile.dev/installation/#setup-completions) to + output completion scripts for various shells (#293, #1157 by @pd93). + - This is now the preferred way to install completions. + - The completion scripts in the `completion` directory + [are now deprecated](https://taskfile.dev/deprecations/completion-scripts/). +- Added the ability to + [loop over a matrix of values](https://taskfile.dev/usage/#looping-over-a-matrix) + (#1766, #1767, #1784 by @pd93). +- Fixed a bug in fish completion where aliases were not displayed (#1781, #1782 + by @vmaerten). +- Fixed panic when having a flattened included Taskfile that contains a + `default` task (#1777, #1778 by @vmaerten). +- Optimized file existence checks for remote Taskfiles (#1713 by @vmaerten). + ## v3.38.0 - 2024-06-30 - Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering). diff --git a/website/versioned_docs/version-latest/changelog.mdx b/website/versioned_docs/version-latest/changelog.mdx index 39b6126a..47dcf1d7 100644 --- a/website/versioned_docs/version-latest/changelog.mdx +++ b/website/versioned_docs/version-latest/changelog.mdx @@ -5,6 +5,37 @@ sidebar_position: 14 # Changelog +## v3.39.0 - 2024-09-07 + +- Added + [Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence) + (#1038, #1633 by @vmaerten). +- Added a CI lint job to ensure that the docs are updated correctly (#1719 by + @vmaerten). +- Updated minimum required Go version to 1.22 (#1758 by @pd93). +- Expose a new `EXIT_CODE` special variable on `defer:` when a command finishes + with a non-zero exit code (#1484, #1762 by @dorimon-1 and @andreynering). +- Expose a new `ALIAS` special variable, which will contain the alias used to + call the current task. Falls back to the task name. (#1764 by @DanStory). +- Fixed `TASK_REMOTE_DIR` environment variable not working when the path was + absolute. (#1715 by @vmaerten). +- Added an option to declare an included Taskfile as flattened (#1704 by + @vmaerten). +- Added a new + [`--completion` flag](https://taskfile.dev/installation/#setup-completions) to + output completion scripts for various shells (#293, #1157 by @pd93). + - This is now the preferred way to install completions. + - The completion scripts in the `completion` directory + [are now deprecated](https://taskfile.dev/deprecations/completion-scripts/). +- Added the ability to + [loop over a matrix of values](https://taskfile.dev/usage/#looping-over-a-matrix) + (#1766, #1767, #1784 by @pd93). +- Fixed a bug in fish completion where aliases were not displayed (#1781, #1782 + by @vmaerten). +- Fixed panic when having a flattened included Taskfile that contains a + `default` task (#1777, #1778 by @vmaerten). +- Optimized file existence checks for remote Taskfiles (#1713 by @vmaerten). + ## v3.38.0 - 2024-06-30 - Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering). diff --git a/website/versioned_docs/version-latest/deprecations/completion_scripts.mdx b/website/versioned_docs/version-latest/deprecations/completion_scripts.mdx new file mode 100644 index 00000000..fef7408b --- /dev/null +++ b/website/versioned_docs/version-latest/deprecations/completion_scripts.mdx @@ -0,0 +1,25 @@ +--- +slug: /deprecations/completion-scripts/ +--- + +# Completion Scripts + +:::warning + +This deprecation breaks the following functionality: + +- Any direct references to the completion scripts in the Task git repository + +::: + +Direct use of the completion scripts in the `completion/*` directory of the +[github.com/go-task/task][task] Git repository is deprecated. Any shell +configuration that directly refers to these scripts will potentially break in +the future as the scripts may be moved or deleted entirely. Any configuration +should be updated to use the [new method for generating shell +completions][completions] instead. + +{/* prettier-ignore-start */} +[completions]: ../installation.mdx#setup-completions +[task]: https://github.com/go-task/task +{/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/experiments/env_precedence.mdx b/website/versioned_docs/version-latest/experiments/env_precedence.mdx new file mode 100644 index 00000000..535a676e --- /dev/null +++ b/website/versioned_docs/version-latest/experiments/env_precedence.mdx @@ -0,0 +1,74 @@ +--- +slug: '/experiments/env-precedence' +--- + +# Env Precedence (#1038) + +:::caution + +All experimental features are subject to breaking changes and/or removal _at any +time_. We strongly recommend that you do not use these features in a production +environment. They are intended for testing and feedback only. + +::: + +:::warning + +This experiment breaks the following functionality: + +- environment variable will take precedence over OS environment variables + +::: + +:::info + +To enable this experiment, set the environment variable: +`TASK_X_ENV_PRECEDENCE=1`. Check out [our guide to enabling +experiments][enabling-experiments] for more information. + +::: + +Before this experiment, the OS variable took precedence over the task +environment variable. This experiment changes the precedence to make the task +environment variable take precedence over the OS variable. + +Consider the following example: + +```yml +version: '3' + +tasks: + default: + env: + KEY: 'other' + cmds: + - echo "$KEY" +``` +Running `KEY=some task` before this experiment, the output would be `some`, but +after this experiment, the output would be `other`. + +If you still want to get the OS variable, you can use the template function env +like follow : `{{env "OS_VAR"}}`. + +```yml +version: '3' + +tasks: + default: + env: + KEY: 'other' + cmds: + - echo "$KEY" + - echo {{env "KEY"}} +``` +Running `KEY=some task`, the output would be `other` and `some`. + +Like other variables/envs, you can also fall back to a given value using the +default template function: +```yml +MY_ENV: '{{.MY_ENV | default "fallback"}}' +``` + +{/* prettier-ignore-start */} +[enabling-experiments]: ./experiments.mdx#enabling-experiments +{/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/installation.mdx b/website/versioned_docs/version-latest/installation.mdx index e0ac516b..d4b76f36 100644 --- a/website/versioned_docs/version-latest/installation.mdx +++ b/website/versioned_docs/version-latest/installation.mdx @@ -3,6 +3,9 @@ slug: /installation/ sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Installation Task offers many installation methods. Check out the available methods below. @@ -247,65 +250,76 @@ released binary. ## Setup completions -Download the autocompletion file corresponding to your shell. +Some installation methods will automatically install completions too, but if +this isn't working for you or your chosen method doesn't include them, you can +run `task --completion ` to output a completion script for any supported +shell. There are a couple of ways these completions can be added to your shell +config: -[All completions are available on the Task repository](https://github.com/go-task/task/tree/main/completion). +### Option 1. Load the completions in your shell's startup config (Recommended) -### Bash +This method loads the completion script from the currently installed version of +task every time you create a new shell. This ensures that your completions are +always up-to-date. -First, ensure that you installed bash-completion using your package manager. + -Make the completion file executable: + +```shell title="~/.bashrc" +eval "$(task --completion bash)" +``` + + +```shell title="~/.zshrc" +eval "$(task --completion zsh)" +``` + + + +```shell title="~/.config/fish/config.fish" +task --completion fish | source +``` + + + +```powershell title="$PROFILE\Microsoft.PowerShell_profile.ps1" +Invoke-Expression (&task --completion powershell) +``` + + +### Option 2. Copy the script to your shell's completions directory + +This method requires you to manually update the completions whenever Task is +updated. However, it is useful if you want to modify the completions yourself. + + + + ```shell -chmod +x path/to/task.bash +task --completion bash > /etc/bash_completion.d/task ``` + -After, add this to your `~/.bash_profile`: - + ```shell -source path/to/task.bash +task --completion zsh > /usr/local/share/zsh/site-functions/_task ``` + -### ZSH - -Put the `_task` file somewhere in your `$FPATH`: - + ```shell -mv path/to/_task /usr/local/share/zsh/site-functions/_task -``` - -Ensure that the following is present in your `~/.zshrc`: - -```shell -autoload -U compinit -compinit -i -``` - -ZSH version 5.7 or later is recommended. - -### Fish - -Move the `task.fish` completion script: - -```shell -mv path/to/task.fish ~/.config/fish/completions/task.fish -``` - -### PowerShell - -Open your profile script with: - -```powershell -mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue -notepad $profile -``` - -Add the line and save the file: - -```shell -Invoke-Expression -Command path/to/task.ps1 +task --completion fish > ~/.config/fish/completions/task.fish ``` + {/* prettier-ignore-start */} [go]: https://golang.org/ diff --git a/website/versioned_docs/version-latest/reference/schema.mdx b/website/versioned_docs/version-latest/reference/schema.mdx index 7d37a315..e67a033c 100644 --- a/website/versioned_docs/version-latest/reference/schema.mdx +++ b/website/versioned_docs/version-latest/reference/schema.mdx @@ -8,7 +8,7 @@ toc_max_heading_level: 5 # Schema Reference | Attribute | Type | Default | Description | -| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|------------|------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `version` | `string` | | Version of the Taskfile. The current version is `3`. | | `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. | | `method` | `string` | `checksum` | Default method in this Taskfile. Can be overridden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. | @@ -26,10 +26,11 @@ toc_max_heading_level: 5 ## 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. | +| `flatten` | `bool` | `false` | If `true`, the tasks from the included Taskfile will be available in the including Taskfile without a namespace. If a task with the same name already exists in the including Taskfile, an error will be thrown. | | `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. | diff --git a/website/versioned_docs/version-latest/reference/templating.mdx b/website/versioned_docs/version-latest/reference/templating.mdx index b85870aa..33df58e8 100644 --- a/website/versioned_docs/version-latest/reference/templating.mdx +++ b/website/versioned_docs/version-latest/reference/templating.mdx @@ -101,10 +101,13 @@ engine. If you define a variable with the same name as a special variable, the special variable will be overridden. | Var | Description | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. | | `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. | +| `CLI_SILENT` | A boolean containing whether the `--silent` flag was set. | +| `CLI_VERBOSE` | A boolean containing whether the `--verbose` flag was set. | | `TASK` | The name of the current task. | +| `ALIAS` | The alias used for the current task, otherwise matches `TASK`. | | `TASK_EXE` | The Task executable name or path. | | `ROOT_TASKFILE` | The absolute path of the root Taskfile. | | `ROOT_DIR` | The absolute path of the root Taskfile directory. | @@ -115,6 +118,7 @@ special variable will be overridden. | `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. | | `TASK_VERSION` | The current version of task. | | `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. | +| `EXIT_CODE` | Available exclusively inside the `defer:` command. Contains the failed command exit code. Only set when non-zero. | ## Functions diff --git a/website/versioned_docs/version-latest/usage.mdx b/website/versioned_docs/version-latest/usage.mdx index 66fb3f3a..e05f7268 100644 --- a/website/versioned_docs/version-latest/usage.mdx +++ b/website/versioned_docs/version-latest/usage.mdx @@ -334,6 +334,117 @@ includes: internal: true ``` +### Flatten includes + +You can flatten the included Taskfile tasks into the main Taskfile by using the `flatten` option. +It means that the included Taskfile tasks will be available without the namespace. + + + + + + + ```yaml + version: '3' + + includes: + lib: + taskfile: ./Included.yml + flatten: true + + tasks: + greet: + cmds: + - echo "Greet" + - task: foo + ``` + + + + + + ```yaml + version: '3' + + tasks: + foo: + cmds: + - echo "Foo" + ``` + + + + + +If you run `task -a` it will print : + +```sh +task: Available tasks for this project: +* greet: +* foo +``` + +You can run `task foo` directly without the namespace. + +You can also reference the task in other tasks without the namespace. So if you run `task greet` it will run `greet` and `foo` tasks and the output will be : + +```text +``` + +If multiple tasks have the same name, an error will be thrown: + + + + + + ```yaml + version: '3' + includes: + lib: + taskfile: ./Included.yml + flatten: true + + tasks: + greet: + cmds: + - echo "Greet" + - task: foo + ``` + + + + + + ```yaml + version: '3' + + tasks: + greet: + cmds: + - echo "Foo" + ``` + + + + +If you run `task -a` it will print: +```text +task: Found multiple tasks (greet) included by "lib" + +``` + + + + + ### Vars of included Taskfiles You can also specify variables when including a Taskfile. This may be useful for @@ -1181,14 +1292,14 @@ tasks: ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar bar: cmds: - - 'echo {{.MYVAR}}' # <-- FOO is just the letter 'A' + - 'echo {{.FOO}}' # <-- FOO is just the letter 'A' ``` ## Looping over values -As of v3.28.0, Task allows you to loop over certain values and execute a command -for each. There are a number of ways to do this depending on the type of value -you want to loop over. +Task allows you to loop over certain values and execute a command for each. +There are a number of ways to do this depending on the type of value you want to +loop over. ### Looping over a static list @@ -1205,6 +1316,37 @@ tasks: cmd: cat {{ .ITEM }} ``` +### Looping over a matrix + +If you need to loop over all permutations of multiple lists, you can use the +`matrix` property. This should be familiar to anyone who has used a matrix in a +CI/CD pipeline. + +```yaml +version: '3' + +tasks: + default: + silent: true + cmds: + - for: + matrix: + OS: ["windows", "linux", "darwin"] + ARCH: ["amd64", "arm64"] + cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}" +``` + +This will output: + +```txt +windows/amd64 +windows/arm64 +linux/amd64 +linux/arm64 +darwin/amd64 +darwin/arm64 +``` + ### Looping over your task's sources You are also able to loop over the sources of your task: @@ -1520,6 +1662,20 @@ commands are executed in the reverse order if you schedule multiple of them. ::: +A special variable `.EXIT_CODE` is exposed when a command exited with a non-zero +exit code. You can check its presence to know if the task completed successfully +or not: + +```yaml +version: '3' + +tasks: + default: + cmds: + - defer: echo '{{if .EXIT_CODE}}Failed with {{.EXIT_CODE}}!{{else}}Success!{{end}}' + - exit 1 +``` + ## Help Running `task --list` (or `task -l`) lists all tasks with a description. The