v3.39.0

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## v3.39.0 - 2024-09-07
 
 - Added
   [Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence)

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",

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).

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).

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 */}

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 */}

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.
-
-[All completions are available on the Task repository](https://github.com/go-task/task/tree/main/completion).
+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 <shell>` to output a completion script for any supported
+shell. There are a couple of ways these completions can be added to your shell
+config:
 
-### Bash
+### Option 1. Load the completions in your shell's startup config (Recommended)
 
-First, ensure that you installed bash-completion using your package manager.
+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.
 
-Make the completion file executable:
+<Tabs values={[ {label: 'bash', value: '1'}, {label: 'zsh', value: '2'},
+    {label: 'fish', value: '3'},
+    {label: 'powershell', value: '4'}
+  ]}>
 
-```shell
-chmod +x path/to/task.bash
+<TabItem value="1">
+```shell title="~/.bashrc"
+eval "$(task --completion bash)"
 ```
+</TabItem>
 
-After, add this to your `~/.bash_profile`:
-
-```shell
-source path/to/task.bash
+<TabItem value="2">
+```shell title="~/.zshrc"
+eval "$(task --completion zsh)"
 ```
+</TabItem>
 
-### ZSH
-
-Put the `_task` file somewhere in your `$FPATH`:
-
-```shell
-mv path/to/_task /usr/local/share/zsh/site-functions/_task
+<TabItem value="3">
+```shell title="~/.config/fish/config.fish"
+task --completion fish | source
 ```
+</TabItem>
 
-Ensure that the following is present in your `~/.zshrc`:
-
-```shell
-autoload -U compinit
-compinit -i
+<TabItem value="4">
+```powershell title="$PROFILE\Microsoft.PowerShell_profile.ps1"
+Invoke-Expression (&task --completion powershell)
 ```
+</TabItem></Tabs>
 
-ZSH version 5.7 or later is recommended.
+### Option 2. Copy the script to your shell's completions directory
 
-### Fish
+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.
 
-Move the `task.fish` completion script:
+<Tabs
+  values={[
+    {label: 'bash', value: '1'},
+    {label: 'zsh', value: '2'},
+    {label: 'fish', value: '3'}
+  ]}>
 
+<TabItem value="1">
 ```shell
-mv path/to/task.fish ~/.config/fish/completions/task.fish
+task --completion bash > /etc/bash_completion.d/task
 ```
+</TabItem>
 
-### PowerShell
-
-Open your profile script with:
-
-```powershell
-mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue
-notepad $profile
+<TabItem value="2">
+```shell
+task --completion zsh  > /usr/local/share/zsh/site-functions/_task
 ```
+</TabItem>
 
-Add the line and save the file:
-
+<TabItem value="3">
 ```shell
-Invoke-Expression -Command path/to/task.ps1
+task --completion fish > ~/.config/fish/completions/task.fish
 ```
+</TabItem></Tabs>
 
 {/* prettier-ignore-start */}
 [go]: https://golang.org/

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.                                                                                                                                                                                                    |

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