v3.42.0

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## Unreleased
+## v3.42.0 - 2025-03-08
 
 - Made `--init` less verbose by default and respect `--silent` and `--verbose`
   flags (#2009, #2011 by @HeCorr).

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-task/cli",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@go-task/cli",
-  "version": "3.41.0",
+  "version": "3.42.0",
   "description": "A task runner / simpler Make alternative written in Go",
   "scripts": {
     "postinstall": "go-npm install",

website/docs/changelog.mdx

@@ -5,6 +5,89 @@ sidebar_position: 14
 
 # Changelog
 
+## v3.42.0 - 2025-03-08
+
+- Made `--init` less verbose by default and respect `--silent` and `--verbose`
+  flags (#2009, #2011 by @HeCorr).
+- `--init` now accepts a file name or directory as an argument (#2008, #2018 by
+  @HeCorr).
+- Fix a bug where an HTTP node's location was being mutated incorrectly (#2007
+  by @jeongukjae).
+- Fixed a bug where allowed values didn't work with dynamic var (#2032, #2033 by
+  @vmaerten).
+- Use only the relevant checker (timestamp or checksum) to improve performance
+  (#2029, #2031 by @vmaerten).
+- Print warnings when attempting to enable an inactive experiment or an active
+  experiment with an invalid value (#1979, #2049 by @pd93).
+- Refactored the experiments package and added tests (#2049 by @pd93).
+- Show allowed values when a variable with an enum is missing (#2027, #2052 by
+  @vmaerten).
+- Refactored how snippets in error work and added tests (#2068 by @pd93).
+- Fixed a bug where errors decoding commands were sometimes unhelpful (#2068 by
+  @pd93).
+- Fixed a bug in the Taskfile schema where `defer` statements in the shorthand
+  `cmds` syntax were not considered valid (#2068 by @pd93).
+- Refactored how task sorting functions work (#1798 by @pd93).
+- Added a new `.taskrc.yml` (or `.taskrc.yaml`) file to let users enable
+  experiments (similar to `.env`) (#1982 by @vmaerten).
+- Added new [Getting Started docs](https://taskfile.dev/getting-started) (#2086
+  by @pd93).
+- Allow `matrix` to use references to other variables (#2065, #2069 by @pd93).
+- Fixed a bug where, when a dynamic variable is provided, even if it is not
+  used, all other variables become unavailable in the templating system within
+  the include (#2092 by @vmaerten).
+
+#### Package API
+
+Unlike our CLI tool,
+[Task's package API is not currently stable](https://taskfile.dev/reference/package).
+In an effort to ease the pain of breaking changes for our users, we will be
+providing changelogs for our package API going forwards. The hope is that these
+changes will provide a better long-term experience for our users and allow to
+stabilize the API in the future. #121 now tracks this piece of work.
+
+- Bumped the minimum required Go version to 1.23 (#2059 by @pd93).
+- [`task.InitTaskfile`](https://pkg.go.dev/github.com/go-task/task/v3#InitTaskfile)
+  (#2011, ff8c913 by @HeCorr and @pd93)
+  - No longer accepts an `io.Writer` (output is now the caller's
+    responsibility).
+  - The path argument can now be a filename OR a directory.
+  - The function now returns the full path of the generated file.
+- [`TaskfileDecodeError.WithFileInfo`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskfileDecodeError.WithFileInfo)
+  now accepts a string instead of the arguments required to generate a snippet
+  (#2068 by @pd93).
+  - The caller is now expected to create the snippet themselves (see below).
+- [`TaskfileSnippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet)
+  and related code moved from the `errors` package to the `taskfile` package
+  (#2068 by @pd93).
+- Renamed `TaskMissingRequiredVars` to
+  [`TaskMissingRequiredVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskMissingRequiredVarsError)
+  (#2052 by @vmaerten).
+- Renamed `TaskNotAllowedVars` to
+  [`TaskNotAllowedVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskNotAllowedVarsError)
+  (#2052 by @vmaerten).
+- The
+  [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
+  is now constructed using the functional options pattern (#2082 by @pd93).
+- Removed our internal `logger.Logger` from the entire `taskfile` package (#2082
+  by @pd93).
+  - Users are now expected to pass a custom debug/prompt functions into
+    [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
+    if they want this functionality by using the new
+    [`WithDebugFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithDebugFunc)
+    and
+    [`WithPromptFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithPromptFunc)
+    functional options.
+- Remove `Range` functions in the `taskfile/ast` package in favour of new
+  iterator functions (#1798 by @pd93).
+- `ast.Call` was moved from the `taskfile/ast` package to the main `task`
+  package (#2084 by @pd93).
+- `ast.Tasks.FindMatchingTasks` was moved from the `taskfile/ast` package to the
+  `task.Executor.FindMatchingTasks` in the main `task` package (#2084 by @pd93).
+- The `Compiler` and its `GetVariables` and `FastGetVariables` methods were
+  moved from the `internal/compiler` package to the main `task` package (#2084
+  by @pd93).
+
 ## v3.41.0 - 2025-01-18
 
 - Fixed an issue where dynamic variables were not properly logged in verbose

website/versioned_docs/version-latest/changelog.mdx

@@ -5,6 +5,89 @@ sidebar_position: 14
 
 # Changelog
 
+## v3.42.0 - 2025-03-08
+
+- Made `--init` less verbose by default and respect `--silent` and `--verbose`
+  flags (#2009, #2011 by @HeCorr).
+- `--init` now accepts a file name or directory as an argument (#2008, #2018 by
+  @HeCorr).
+- Fix a bug where an HTTP node's location was being mutated incorrectly (#2007
+  by @jeongukjae).
+- Fixed a bug where allowed values didn't work with dynamic var (#2032, #2033 by
+  @vmaerten).
+- Use only the relevant checker (timestamp or checksum) to improve performance
+  (#2029, #2031 by @vmaerten).
+- Print warnings when attempting to enable an inactive experiment or an active
+  experiment with an invalid value (#1979, #2049 by @pd93).
+- Refactored the experiments package and added tests (#2049 by @pd93).
+- Show allowed values when a variable with an enum is missing (#2027, #2052 by
+  @vmaerten).
+- Refactored how snippets in error work and added tests (#2068 by @pd93).
+- Fixed a bug where errors decoding commands were sometimes unhelpful (#2068 by
+  @pd93).
+- Fixed a bug in the Taskfile schema where `defer` statements in the shorthand
+  `cmds` syntax were not considered valid (#2068 by @pd93).
+- Refactored how task sorting functions work (#1798 by @pd93).
+- Added a new `.taskrc.yml` (or `.taskrc.yaml`) file to let users enable
+  experiments (similar to `.env`) (#1982 by @vmaerten).
+- Added new [Getting Started docs](https://taskfile.dev/getting-started) (#2086
+  by @pd93).
+- Allow `matrix` to use references to other variables (#2065, #2069 by @pd93).
+- Fixed a bug where, when a dynamic variable is provided, even if it is not
+  used, all other variables become unavailable in the templating system within
+  the include (#2092 by @vmaerten).
+
+#### Package API
+
+Unlike our CLI tool,
+[Task's package API is not currently stable](https://taskfile.dev/reference/package).
+In an effort to ease the pain of breaking changes for our users, we will be
+providing changelogs for our package API going forwards. The hope is that these
+changes will provide a better long-term experience for our users and allow to
+stabilize the API in the future. #121 now tracks this piece of work.
+
+- Bumped the minimum required Go version to 1.23 (#2059 by @pd93).
+- [`task.InitTaskfile`](https://pkg.go.dev/github.com/go-task/task/v3#InitTaskfile)
+  (#2011, ff8c913 by @HeCorr and @pd93)
+  - No longer accepts an `io.Writer` (output is now the caller's
+    responsibility).
+  - The path argument can now be a filename OR a directory.
+  - The function now returns the full path of the generated file.
+- [`TaskfileDecodeError.WithFileInfo`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskfileDecodeError.WithFileInfo)
+  now accepts a string instead of the arguments required to generate a snippet
+  (#2068 by @pd93).
+  - The caller is now expected to create the snippet themselves (see below).
+- [`TaskfileSnippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet)
+  and related code moved from the `errors` package to the `taskfile` package
+  (#2068 by @pd93).
+- Renamed `TaskMissingRequiredVars` to
+  [`TaskMissingRequiredVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskMissingRequiredVarsError)
+  (#2052 by @vmaerten).
+- Renamed `TaskNotAllowedVars` to
+  [`TaskNotAllowedVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskNotAllowedVarsError)
+  (#2052 by @vmaerten).
+- The
+  [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
+  is now constructed using the functional options pattern (#2082 by @pd93).
+- Removed our internal `logger.Logger` from the entire `taskfile` package (#2082
+  by @pd93).
+  - Users are now expected to pass a custom debug/prompt functions into
+    [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader)
+    if they want this functionality by using the new
+    [`WithDebugFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithDebugFunc)
+    and
+    [`WithPromptFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithPromptFunc)
+    functional options.
+- Remove `Range` functions in the `taskfile/ast` package in favour of new
+  iterator functions (#1798 by @pd93).
+- `ast.Call` was moved from the `taskfile/ast` package to the main `task`
+  package (#2084 by @pd93).
+- `ast.Tasks.FindMatchingTasks` was moved from the `taskfile/ast` package to the
+  `task.Executor.FindMatchingTasks` in the main `task` package (#2084 by @pd93).
+- The `Compiler` and its `GetVariables` and `FastGetVariables` methods were
+  moved from the `internal/compiler` package to the main `task` package (#2084
+  by @pd93).
+
 ## v3.41.0 - 2025-01-18
 
 - Fixed an issue where dynamic variables were not properly logged in verbose

website/versioned_docs/version-latest/community.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /community/
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # Community

website/versioned_docs/version-latest/contributing.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /contributing/
-sidebar_position: 11
+sidebar_position: 12
 ---
 
 # Contributing

website/versioned_docs/version-latest/deprecations/deprecations.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /deprecations/
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Deprecations

website/versioned_docs/version-latest/experiments/experiments.mdx

@@ -1,8 +1,11 @@
 ---
 slug: /experiments/
-sidebar_position: 6
+sidebar_position: 7
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # Experiments
 
 :::caution
@@ -39,7 +42,7 @@ Which method you use depends on how you intend to use the experiment:
 1. Prefixing your task commands with the relevant environment variable(s). For
    example, `TASK_X_{FEATURE}=1 task {my-task}`. This is intended for one-off
    invocations of Task to test out experimental features.
-1. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
+2. Adding the relevant environment variable(s) in your "dotfiles" (e.g.
    `.bashrc`, `.zshrc` etc.). This will permanently enable experimental features
    for your personal environment.
 
@@ -47,15 +50,33 @@ Which method you use depends on how you intend to use the experiment:
    export TASK_X_FEATURE=1
    ```
 
-1. Creating a `.env` file in the same directory as your root Taskfile that
+3. Creating a `.env` or a `.task-experiments.yml` file in the same directory as
-   contains the relevant environment variable(s). This allows you to enable an
+   your root Taskfile.\
-   experimental feature at a project level. If you commit the `.env` file to
+   The `.env` file should contain the relevant environment
-   source control then other users of your project will also have these
+   variable(s), while the `.task-experiments.yml` file should use a YAML format
-   experiments enabled.
+   where each experiment is defined as a key with a corresponding value.
 
-   ```shell title=".env"
+   This allows you to enable an experimental feature at a project level. If you
-   TASK_X_FEATURE=1
+   commit this file to source control, then other users of your project will
-   ```
+   also have these experiments enabled.
+
+   If both files are present, the values in the `.task-experiments.yml` file
+   will take precedence.
+
+    <Tabs values={[ {label: '.task-experiments.yml', value: 'yaml'}, {label: '.env', value: 'env'}]}>
+     <TabItem value="yaml">
+       ```yaml title=".taskrc.yml"
+        experiments:
+          FEATURE: 1
+       ```
+     </TabItem>
+
+        <TabItem value="env">
+       ```shell title=".env"
+       TASK_X_FEATURE=1
+       ```
+     </TabItem>
+    </Tabs>
 
 ## Workflow
 

website/versioned_docs/version-latest/getting_started.mdx

@@ -0,0 +1,143 @@
+---
+slug: /getting-started/
+sidebar_position: 3
+---
+
+# Getting Started
+
+The following guide will help introduce you to the basics of Task. We'll cover
+how to create a Taskfile, how to write a basic task and how to call it. If you
+haven't installed Task yet, head over to our [installation
+guide][installation].
+
+## Creating your first Taskfile
+
+Once Task is installed, you can create your first Taskfile by running:
+
+```shell
+task --init
+```
+
+This will create a file called `Taskfile.yml` in the current directory. If you
+want to create the file in another directory, you can pass an absolute or
+relative path to the directory into the command:
+
+```shell
+task --init ./subdirectory
+```
+
+Or if you want the Taskfile to have a specific name, you can pass in the name of
+the file:
+
+```shell
+task --init Custom.yml
+```
+
+This will create a Taskfile that looks something like this:
+
+```yaml
+version: '3'
+
+vars:
+  GREETING: Hello, World!
+
+tasks:
+  default:
+    cmds:
+      - echo "{{.GREETING}}"
+    silent: true
+```
+
+As you can see, all Taskfiles are written in [YAML format][yaml]. The `version`
+attribute specifies the minimum version of Task that can be used to run this
+file. The `vars` attribute is used to define variables that can be used in
+tasks. In this case, we are creating a string variable called `GREETING` with a
+value of `Hello, World!`.
+
+Finally, the `tasks` attribute is used to define the tasks that can be run. In
+this case, we have a task called `default` that echoes the value of the
+`GREETING` variable. The `silent` attribute is set to `true`, which means that
+the task metadata will not be printed when the task is run - only the output of
+the commands.
+
+## Calling a task
+
+To call the task, you simply invoke `task` followed by the name of the task you
+want to run. In this case, the name of the task is `default`, so you should run:
+
+```shell
+task default
+```
+
+Note that we don't have to specify the name of the Taskfile. Task will
+automatically look for a file called `Taskfile.yml` (or any of Task's [supported
+file names][supported-file-names]) in the current directory. Additionally, tasks
+with the name `default` are special. They can also be run without specifying the
+task name.
+
+If you created a Taskfile in a different directory, you can run it by passing
+the absolute or relative path to the directory as an argument using the `--dir`
+flag:
+
+```shell
+task --dir ./subdirectory
+```
+
+Or if you created a Taskfile with a different name, you can run it by passing
+the name of the Taskfile as an argument using the `--taskfile` flag:
+
+```shell
+task --taskfile Custom.yml
+```
+
+## Adding a build task
+
+Let's create a task to build a program in Go. Start by adding a new task called
+`build` below the existing `default` task. We can then add a `cmds` attribute
+with a single command to build the program.
+
+Task uses [mvdan/sh][mvdan/sh], a native Go sh interpreter. So you can write
+sh/bash-like commands - even in environments where `sh` or `bash` are usually
+not available (like Windows). Just remember any executables called must be
+available as a built-in or in the system's `PATH`.
+
+When you're done, it should look something like this:
+
+```yaml
+version: '3'
+
+vars:
+  GREETING: Hello, World!
+
+tasks:
+  default:
+    cmds:
+      - echo "{{.GREETING}}"
+    silent: true
+
+  build:
+    cmds:
+      - go build ./cmd/main.go
+```
+
+Call the task by running:
+
+```shell
+task build
+```
+
+That's about it for the basics, but there's _so much_ more that you can do with
+Task. Check out the rest of the documentation to learn more about all the
+features Task has to offer! We recommend taking a look at the [usage
+guide][usage] next. Alternatively, you can check out our reference docs for the
+[Taskfile schema][schema] and [CLI][cli].
+
+{/* prettier-ignore-start */}
+[yaml]: https://yaml.org/
+[installation]: /installation/
+[supported-file-names]: /usage/#supported-file-names
+[mvdan/sh]: https://github.com/mvdan/sh
+[usage]: /usage/
+[schema]: /reference/schema/
+[cli]: /reference/cli/
+{/* prettier-ignore-end */}

website/versioned_docs/version-latest/integrations.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /integrations/
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Integrations

website/versioned_docs/version-latest/intro.mdx

@@ -17,24 +17,6 @@ Since it's written in [Go][go], Task is just a single binary and has no other
 dependencies, which means you don't need to mess with any complicated install
 setups just to use a build tool.
 
-Once [installed](/installation), you just need to describe your build tasks
-using a simple [YAML][yaml] schema in a file called `Taskfile.yml`:
-
-```yaml title="Taskfile.yml"
-version: '3'
-
-tasks:
-  hello:
-    cmds:
-      - echo 'Hello World from Task!'
-    silent: true
-```
-
-And call it by running `task hello` from your terminal.
-
-The above example is just the start, you can take a look at the [usage](/usage)
-guide to check the full schema documentation and Task features.
-
 ## Features
 
 - [Easy installation](/installation): just download a single binary, add to
@@ -50,6 +32,15 @@ guide to check the full schema documentation and Task features.
   of files haven't changed since last run (based either on its timestamp or
   content).
 
+## Documentation
+
+- If you're new to Task, we recommend taking a look at our [getting started
+  guide][getting-started] for an quick introduction.
+- You can also browse our [usage documentation][usage] for more details on how
+  all the features work.
+- Or use our quick reference documentation for the [Taskfile schema][schema] or
+  [CLI][cli].
+
 ## Gold Sponsors
 
 <table class="gold-sponsors">
@@ -70,4 +61,8 @@ guide to check the full schema documentation and Task features.
 [snapcraft]: https://snapcraft.io/
 [scoop]: https://scoop.sh/
 [sh]: https://github.com/mvdan/sh
+[getting-started]: /getting-started/
+[usage]: /usage/
+[schema]: /reference/schema/
+[cli]: /reference/cli/
 {/* prettier-ignore-end */}

website/versioned_docs/version-latest/reference/_category_.yml

@@ -1,2 +1,2 @@
-position: 4
+position: 5
 label: Reference

website/versioned_docs/version-latest/reference/cli.mdx

@@ -16,10 +16,10 @@ task [--flags] [tasks...] [-- CLI_ARGS...]
 If `--` is given, all remaining arguments will be assigned to a special
 `CLI_ARGS` variable
 
-## Flags
-
 :::
 
+## Flags
+
 | 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.                                                                                                      |
@@ -45,7 +45,7 @@ If `--` is given, all remaining arguments will be assigned to a special
 | `-y`  | `--yes`                     | `bool`   | `false`                                      | Assume "yes" as answer to all prompts.                                                                                                                                                       |
 |       | `--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`            |                                                                                                                                                                                              |
+| `-t`  | `--taskfile`                | `string` |                                              | Taskfile path to run.<br />Check the list of default filenames [here](../usage/#supported-file-names).                                                                                        |
 | `-v`  | `--verbose`                 | `bool`   | `false`                                      | Enables verbose mode.                                                                                                                                                                        |
 |       | `--version`                 | `bool`   | `false`                                      | Show Task version.                                                                                                                                                                           |
 | `-w`  | `--watch`                   | `bool`   | `false`                                      | Enables watch of the given task.

website/versioned_docs/version-latest/styleguide.mdx

@@ -1,9 +1,9 @@
 ---
 slug: /styleguide/
-sidebar_position: 10
+sidebar_position: 11
 ---
 
-# Style guide
+# Style Guide
 
 This is the official style guide for `Taskfile.yml` files. It provides basic
 instructions for keeping your Taskfiles clean and familiar to other users.

website/versioned_docs/version-latest/taskfile_versions.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /taskfile-versions/
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Taskfile Versions

website/versioned_docs/version-latest/usage.mdx

@@ -1,6 +1,6 @@
 ---
 slug: /usage/
-sidebar_position: 3
+sidebar_position: 4
 ---
 
 import Tabs from '@theme/Tabs';
@@ -8,56 +8,29 @@ import TabItem from '@theme/TabItem';
 
 # Usage
 
-## Getting started
+## Running Taskfiles
 
-Create a file called `Taskfile.yml` in the root of your project. The `cmds`
+Specific Taskfiles can be called by specifying the `--taskfile` flag. If you
-attribute should contain the commands of a task. The example below allows
+don't specify a Taskfile, Task will automatically look for a file with one of
-compiling a Go app and uses [esbuild](https://esbuild.github.io/) to concat and
+the [supported file names](#supported-file-names) in the current directory. If
-minify multiple CSS files into a single one.
+you want to search in a different directory, you can use the `--dir` flag.
 
-```yaml
+### Supported file names
-version: '3'
 
-tasks:
+Task looks for files with the following names, in order of priority:
-  build:
-    cmds:
-      - go build -v -i main.go
 
-  assets:
+- `Taskfile.yml`
-    cmds:
+- `taskfile.yml`
-      - esbuild --bundle --minify css/index.css > public/bundle.css
+- `Taskfile.yaml`
-```
+- `taskfile.yaml`
+- `Taskfile.dist.yml`
+- `taskfile.dist.yml`
+- `Taskfile.dist.yaml`
+- `taskfile.dist.yaml`
 
-Running the tasks is as simple as running:
+The `.dist` variants allow projects to have one committed file (`.dist`) while
-
+still allowing individual users to override the Taskfile by adding an additional
-```shell
+`Taskfile.yml` (which would be in your `.gitignore`).
-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.
-
-If you omit a task name, "default" will be assumed.
-
-## Supported file names
-
-Task will look for the following file names, in order of priority:
-
-- Taskfile.yml
-- taskfile.yml
-- Taskfile.yaml
-- taskfile.yaml
-- Taskfile.dist.yml
-- taskfile.dist.yml
-- Taskfile.dist.yaml
-- taskfile.dist.yaml
-
-The intention of having the `.dist` variants is to allow projects to have one
-committed version (`.dist`) while still allowing individual users to override
-the Taskfile by adding an additional `Taskfile.yml` (which would be on
-`.gitignore`).
 
 ### Running a Taskfile from a subdirectory
 
@@ -263,11 +236,7 @@ Taskfile.
 
 ### OS-specific Taskfiles
 
-With `version: '2'`, task automatically includes any `Taskfile_{{OS}}.yml` if it
+You can include OS-specific Taskfiles by using a templating function:
-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'
@@ -442,7 +411,7 @@ If you run `task -a` it will print:
 task: Found multiple tasks (greet) included by "lib"
 ```
 
-If you the included Taskfile has a task with the same name as a task in the main Taskfile,
+If the included Taskfile has a task with the same name as a task in the main Taskfile,
 you may want to exclude it from the flattened tasks.
 
 You can do this by using the [`excludes` option](#exclude-tasks-from-being-included).
@@ -1443,6 +1412,27 @@ darwin/amd64
 darwin/arm64
 ```
 
+You can also use references to other variables as long as they are also lists:
+
+```yaml
+version: "3"
+
+vars:
+  OS_VAR: ["windows", "linux", "darwin"]
+  ARCH_VAR: ["amd64", "arm64"]
+
+tasks:
+  default:
+    cmds:
+      - for:
+          matrix:
+            OS:
+              ref: .OS_VAR
+            ARCH:
+              ref: .ARCH_VAR
+        cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+```
+
 ### Looping over your task's sources
 
 You are also able to loop over the sources of your task: