v3.42.1

* fix: stop dotenv trying to fetch variables when no dotenv specified

* fix: set special variables to "" when they can't be calculated

.github/workflows/lint.yml

@@ -13,7 +13,7 @@ jobs:
     name: Lint
     strategy:
       matrix:
-        go-version: [1.22.x, 1.23.x]
+        go-version: [1.23.x, 1.24.x]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/setup-go@v5
@@ -25,7 +25,7 @@ jobs:
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v6
         with:
-          version: v1.60.1
+          version: v1.64.2
 
   lint-jsonschema:
     runs-on: ubuntu-latest

.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: 1.22.x
+          go-version: 1.23.x
 
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
     name: Test
     strategy:
       matrix:
-        go-version: [1.22.x, 1.23.x]
+        go-version: [1.23.x, 1.24.x]
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{matrix.platform}}
     steps:

.golangci.yml

@@ -9,10 +9,11 @@ linters:
     - goimports
     - gofmt
     - gofumpt
+    - mirror
     - misspell
     - noctx
     - paralleltest
-    - tenv
+    - usetesting
     - thelper
     - tparallel
 
@@ -29,6 +30,8 @@ linters-settings:
             desc: "Use github.com/go-task/task/v3/errors instead"
   goimports:
     local-prefixes: github.com/go-task
+  gofumpt:
+    module-path: github.com/go-task/task/v3
   gofmt:
     rewrite-rules:
       - pattern: 'interface{}'

.goreleaser.yml

@@ -43,7 +43,7 @@ archives:
       - completion/**/*
     format_overrides:
       - goos: windows
-        format: zip
+        formats: [zip]
 
 release:
   draft: true

.nvmrc

@@ -1 +1 @@
-22.13.1
+22.14.0

CHANGELOG.md

@@ -1,9 +1,16 @@
 # Changelog
 
-## Unreleased
+## v3.42.1 - 2025-03-10
+
+- Fixed a bug where some special variables caused a type error when used global
+  variables (#2106, #2107 by @pd93).
+
+## 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
@@ -13,6 +20,73 @@
 - 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
 

Taskfile.yml

@@ -120,6 +120,22 @@ tasks:
     cmds:
       - go install github.com/goreleaser/goreleaser/v2@latest
 
+  gorelease:install:
+    desc: "Installs gorelease: https://pkg.go.dev/golang.org/x/exp/cmd/gorelease"
+    status:
+      - command -v gorelease
+    cmds:
+      - go install golang.org/x/exp/cmd/gorelease@latest
+
+  api:check:
+    desc: Checks what changes have been made to the public API
+    deps: [gorelease:install]
+    vars:
+      LATEST:
+        sh: git describe --tags --abbrev=0
+    cmds:
+      - gorelease -base={{.LATEST}}
+
   release:*:
     desc: Prepare the project for a new release
     summary: |

args/args.go

@@ -3,17 +3,18 @@ package args
 import (
 	"strings"
 
+	"github.com/go-task/task/v3"
 	"github.com/go-task/task/v3/taskfile/ast"
 )
 
 // Parse parses command line argument: tasks and global variables
-func Parse(args ...string) ([]*ast.Call, *ast.Vars) {
-	calls := []*ast.Call{}
+func Parse(args ...string) ([]*task.Call, *ast.Vars) {
+	calls := []*task.Call{}
 	globals := ast.NewVars()
 
 	for _, arg := range args {
 		if !strings.Contains(arg, "=") {
-			calls = append(calls, &ast.Call{Task: arg})
+			calls = append(calls, &task.Call{Task: arg})
 			continue
 		}
 

args/args_test.go

@@ -6,6 +6,7 @@ import (
 
 	"github.com/stretchr/testify/assert"
 
+	"github.com/go-task/task/v3"
 	"github.com/go-task/task/v3/args"
 	"github.com/go-task/task/v3/taskfile/ast"
 )
@@ -15,12 +16,12 @@ func TestArgs(t *testing.T) {
 
 	tests := []struct {
 		Args            []string
-		ExpectedCalls   []*ast.Call
+		ExpectedCalls   []*task.Call
 		ExpectedGlobals *ast.Vars
 	}{
 		{
 			Args: []string{"task-a", "task-b", "task-c"},
-			ExpectedCalls: []*ast.Call{
+			ExpectedCalls: []*task.Call{
 				{Task: "task-a"},
 				{Task: "task-b"},
 				{Task: "task-c"},
@@ -28,7 +29,7 @@ func TestArgs(t *testing.T) {
 		},
 		{
 			Args: []string{"task-a", "FOO=bar", "task-b", "task-c", "BAR=baz", "BAZ=foo"},
-			ExpectedCalls: []*ast.Call{
+			ExpectedCalls: []*task.Call{
 				{Task: "task-a"},
 				{Task: "task-b"},
 				{Task: "task-c"},
@@ -56,7 +57,7 @@ func TestArgs(t *testing.T) {
 		},
 		{
 			Args: []string{"task-a", "CONTENT=with some spaces"},
-			ExpectedCalls: []*ast.Call{
+			ExpectedCalls: []*task.Call{
 				{Task: "task-a"},
 			},
 			ExpectedGlobals: ast.NewVars(
@@ -70,7 +71,7 @@ func TestArgs(t *testing.T) {
 		},
 		{
 			Args: []string{"FOO=bar", "task-a", "task-b"},
-			ExpectedCalls: []*ast.Call{
+			ExpectedCalls: []*task.Call{
 				{Task: "task-a"},
 				{Task: "task-b"},
 			},
@@ -85,15 +86,15 @@ func TestArgs(t *testing.T) {
 		},
 		{
 			Args:          nil,
-			ExpectedCalls: []*ast.Call{},
+			ExpectedCalls: []*task.Call{},
 		},
 		{
 			Args:          []string{},
-			ExpectedCalls: []*ast.Call{},
+			ExpectedCalls: []*task.Call{},
 		},
 		{
 			Args:          []string{"FOO=bar", "BAR=baz"},
-			ExpectedCalls: []*ast.Call{},
+			ExpectedCalls: []*task.Call{},
 			ExpectedGlobals: ast.NewVars(
 				&ast.VarElement{
 					Key: "FOO",

call.go

@@ -1,9 +1,11 @@
-package ast
+package task
+
+import "github.com/go-task/task/v3/taskfile/ast"
 
 // Call is the parameters to a task call
 type Call struct {
 	Task     string
-	Vars     *Vars
+	Vars     *ast.Vars
 	Silent   bool
 	Indirect bool // True if the task was called by another task
 }

cmd/task/task.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/spf13/pflag"
@@ -13,6 +14,7 @@ import (
 	"github.com/go-task/task/v3/args"
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/experiments"
+	"github.com/go-task/task/v3/internal/filepathext"
 	"github.com/go-task/task/v3/internal/flags"
 	"github.com/go-task/task/v3/internal/logger"
 	"github.com/go-task/task/v3/internal/sort"
@@ -77,18 +79,28 @@ func run() error {
 		if err != nil {
 			return err
 		}
-
-		if err := task.InitTaskfile(os.Stdout, wd); err != nil {
+		args, _, err := getArgs()
+		if err != nil {
+			return err
+		}
+		path := wd
+		if len(args) > 0 {
+			name := args[0]
+			if filepathext.IsExtOnly(name) {
+				name = filepathext.SmartJoin(filepath.Dir(name), "Taskfile"+filepath.Ext(name))
+			}
+			path = filepathext.SmartJoin(wd, name)
+		}
+		finalPath, err := task.InitTaskfile(path)
+		if err != nil {
 			return err
 		}
-
 		if !flags.Silent {
 			if flags.Verbose {
 				log.Outf(logger.Default, "%s\n", task.DefaultTaskfile)
 			}
-			log.Outf(logger.Green, "%s created in the current directory\n", task.DefaultTaskFilename)
+			log.Outf(logger.Green, "Taskfile created: %s\n", filepathext.TryAbsToRel(finalPath))
 		}
-
 		return nil
 	}
 
@@ -113,12 +125,12 @@ func run() error {
 		log.Warnf("%s\n", err.Error())
 	}
 
-	var taskSorter sort.TaskSorter
+	var taskSorter sort.Sorter
 	switch flags.TaskSort {
 	case "none":
-		taskSorter = &sort.Noop{}
+		taskSorter = nil
 	case "alphanumeric":
-		taskSorter = &sort.AlphaNumeric{}
+		taskSorter = sort.AlphaNumeric
 	}
 
 	e := task.Executor{
@@ -189,7 +201,7 @@ func run() error {
 	}
 
 	var (
-		calls   []*ast.Call
+		calls   []*task.Call
 		globals *ast.Vars
 	)
 
@@ -202,7 +214,7 @@ func run() error {
 
 	// If there are no calls, run the default task instead
 	if len(calls) == 0 {
-		calls = append(calls, &ast.Call{Task: "default"})
+		calls = append(calls, &task.Call{Task: "default"})
 	}
 
 	globals.Set("CLI_ARGS", ast.Var{Value: cliArgs})

compiler.go

@@ -1,4 +1,4 @@
-package compiler
+package task
 
 import (
 	"bytes"
@@ -36,16 +36,16 @@ func (c *Compiler) GetTaskfileVariables() (*ast.Vars, error) {
 	return c.getVariables(nil, nil, true)
 }
 
-func (c *Compiler) GetVariables(t *ast.Task, call *ast.Call) (*ast.Vars, error) {
+func (c *Compiler) GetVariables(t *ast.Task, call *Call) (*ast.Vars, error) {
 	return c.getVariables(t, call, true)
 }
 
-func (c *Compiler) FastGetVariables(t *ast.Task, call *ast.Call) (*ast.Vars, error) {
+func (c *Compiler) FastGetVariables(t *ast.Task, call *Call) (*ast.Vars, error) {
 	return c.getVariables(t, call, false)
 }
 
-func (c *Compiler) getVariables(t *ast.Task, call *ast.Call, evaluateShVars bool) (*ast.Vars, error) {
-	result := GetEnviron()
+func (c *Compiler) getVariables(t *ast.Task, call *Call, evaluateShVars bool) (*ast.Vars, error) {
+	result := env.GetEnviron()
 	specialVars, err := c.getSpecialVars(t, call)
 	if err != nil {
 		return nil, err
@@ -103,30 +103,42 @@ func (c *Compiler) getVariables(t *ast.Task, call *ast.Call, evaluateShVars bool
 		taskRangeFunc = getRangeFunc(dir)
 	}
 
-	if err := c.TaskfileEnv.Range(rangeFunc); err != nil {
-		return nil, err
-	}
-	if err := c.TaskfileVars.Range(rangeFunc); err != nil {
-		return nil, err
-	}
-	if t != nil {
-		if err := t.IncludeVars.Range(rangeFunc); err != nil {
+	for k, v := range c.TaskfileEnv.All() {
+		if err := rangeFunc(k, v); err != nil {
 			return nil, err
 		}
-		if err := t.IncludedTaskfileVars.Range(taskRangeFunc); err != nil {
+	}
+	for k, v := range c.TaskfileVars.All() {
+		if err := rangeFunc(k, v); err != nil {
 			return nil, err
 		}
 	}
+	if t != nil {
+		for k, v := range t.IncludeVars.All() {
+			if err := rangeFunc(k, v); err != nil {
+				return nil, err
+			}
+		}
+		for k, v := range t.IncludedTaskfileVars.All() {
+			if err := taskRangeFunc(k, v); err != nil {
+				return nil, err
+			}
+		}
+	}
 
 	if t == nil || call == nil {
 		return result, nil
 	}
 
-	if err := call.Vars.Range(rangeFunc); err != nil {
-		return nil, err
+	for k, v := range call.Vars.All() {
+		if err := rangeFunc(k, v); err != nil {
+			return nil, err
+		}
 	}
-	if err := t.Vars.Range(taskRangeFunc); err != nil {
-		return nil, err
+	for k, v := range t.Vars.All() {
+		if err := taskRangeFunc(k, v); err != nil {
+			return nil, err
+		}
 	}
 
 	return result, nil
@@ -184,7 +196,7 @@ func (c *Compiler) ResetCache() {
 	c.dynamicCache = nil
 }
 
-func (c *Compiler) getSpecialVars(t *ast.Task, call *ast.Call) (map[string]string, error) {
+func (c *Compiler) getSpecialVars(t *ast.Task, call *Call) (map[string]string, error) {
 	allVars := map[string]string{
 		"TASK_EXE":         filepath.ToSlash(os.Args[0]),
 		"ROOT_TASKFILE":    filepathext.SmartJoin(c.Dir, c.Entrypoint),
@@ -197,9 +209,16 @@ func (c *Compiler) getSpecialVars(t *ast.Task, call *ast.Call) (map[string]strin
 		allVars["TASK_DIR"] = filepathext.SmartJoin(c.Dir, t.Dir)
 		allVars["TASKFILE"] = t.Location.Taskfile
 		allVars["TASKFILE_DIR"] = filepath.Dir(t.Location.Taskfile)
+	} else {
+		allVars["TASK"] = ""
+		allVars["TASK_DIR"] = ""
+		allVars["TASKFILE"] = ""
+		allVars["TASKFILE_DIR"] = ""
 	}
 	if call != nil {
 		allVars["ALIAS"] = call.Task
+	} else {
+		allVars["ALIAS"] = ""
 	}
 
 	return allVars, nil

errors/error_taskfile_decode.go

@@ -2,36 +2,18 @@ package errors
 
 import (
 	"bytes"
-	"embed"
+	"cmp"
 	"errors"
 	"fmt"
 	"regexp"
 	"strings"
 
-	"github.com/alecthomas/chroma/v2"
-	"github.com/alecthomas/chroma/v2/quick"
-	"github.com/alecthomas/chroma/v2/styles"
 	"github.com/fatih/color"
 	"gopkg.in/yaml.v3"
 )
 
-//go:embed themes/*.xml
-var embedded embed.FS
-
 var typeErrorRegex = regexp.MustCompile(`line \d+: (.*)`)
 
-func init() {
-	r, err := embedded.Open("themes/task.xml")
-	if err != nil {
-		panic(err)
-	}
-	style, err := chroma.NewXMLStyle(r)
-	if err != nil {
-		panic(err)
-	}
-	styles.Register(style)
-}
-
 type (
 	TaskfileDecodeError struct {
 		Message  string
@@ -39,15 +21,9 @@ type (
 		Line     int
 		Column   int
 		Tag      string
-		Snippet  TaskfileSnippet
+		Snippet  string
 		Err      error
 	}
-	TaskfileSnippet struct {
-		Lines     []string
-		StartLine int
-		EndLine   int
-		Padding   int
-	}
 )
 
 func NewTaskfileDecodeError(err error, node *yaml.Node) *TaskfileDecodeError {
@@ -88,38 +64,44 @@ func (err *TaskfileDecodeError) Error() string {
 		}
 	}
 	fmt.Fprintln(buf, color.RedString("file: %s:%d:%d", err.Location, err.Line, err.Column))
+	fmt.Fprint(buf, err.Snippet)
+	return buf.String()
+}
 
-	// Print the snippet
-	maxLineNumberDigits := digits(err.Snippet.EndLine)
-	lineNumberSpacer := strings.Repeat(" ", maxLineNumberDigits)
-	columnSpacer := strings.Repeat(" ", err.Column-1)
-	for i, line := range err.Snippet.Lines {
-		currentLine := err.Snippet.StartLine + i + 1
+func (err *TaskfileDecodeError) Debug() string {
+	const indentWidth = 2
+	buf := &bytes.Buffer{}
+	fmt.Fprintln(buf, "TaskfileDecodeError:")
 
-		lineIndicator := " "
-		if currentLine == err.Line {
-			lineIndicator = ">"
-		}
-		columnIndicator := "^"
+	// Recursively loop through the error chain and print any details
+	var debug func(error, int)
+	debug = func(err error, indent int) {
+		indentStr := strings.Repeat(" ", indent*indentWidth)
 
-		// Print each line
-		lineIndicator = color.RedString(lineIndicator)
-		columnIndicator = color.RedString(columnIndicator)
-		lineNumberFormat := fmt.Sprintf("%%%dd", maxLineNumberDigits)
-		lineNumber := fmt.Sprintf(lineNumberFormat, currentLine)
-		fmt.Fprintf(buf, "%s %s | %s", lineIndicator, lineNumber, line)
-
-		// Print the column indicator
-		if currentLine == err.Line {
-			fmt.Fprintf(buf, "\n  %s | %s%s", lineNumberSpacer, columnSpacer, columnIndicator)
+		// Nothing left to unwrap
+		if err == nil {
+			fmt.Fprintf(buf, "%sEnd of chain\n", indentStr)
+			return
 		}
 
-		// If there are more lines to print, add a newline
-		if i < len(err.Snippet.Lines)-1 {
-			fmt.Fprintln(buf)
+		// Taskfile decode error
+		decodeErr := &TaskfileDecodeError{}
+		if errors.As(err, &decodeErr) {
+			fmt.Fprintf(buf, "%s%s (%s:%d:%d)\n",
+				indentStr,
+				cmp.Or(decodeErr.Message, "<no_message>"),
+				decodeErr.Location,
+				decodeErr.Line,
+				decodeErr.Column,
+			)
+			debug(errors.Unwrap(err), indent+1)
+			return
 		}
+
+		fmt.Fprintf(buf, "%s%s\n", indentStr, err)
+		debug(errors.Unwrap(err), indent+1)
 	}
-
+	debug(err, 0)
 	return buf.String()
 }
 
@@ -141,23 +123,9 @@ func (err *TaskfileDecodeError) WithTypeMessage(t string) *TaskfileDecodeError {
 	return err
 }
 
-func (err *TaskfileDecodeError) WithFileInfo(location string, b []byte, padding int) *TaskfileDecodeError {
-	buf := &bytes.Buffer{}
-	if err := quick.Highlight(buf, string(b), "yaml", "terminal", "task"); err != nil {
-		buf.WriteString(string(b))
-	}
-	lines := strings.Split(buf.String(), "\n")
-	start := max(err.Line-1-padding, 0)
-	end := min(err.Line+padding, len(lines)-1)
-
+func (err *TaskfileDecodeError) WithFileInfo(location string, snippet string) *TaskfileDecodeError {
 	err.Location = location
-	err.Snippet = TaskfileSnippet{
-		Lines:     lines[start:end],
-		StartLine: start,
-		EndLine:   end,
-		Padding:   padding,
-	}
-
+	err.Snippet = snippet
 	return err
 }
 
@@ -168,12 +136,3 @@ func extractTypeErrorMessage(message string) string {
 	}
 	return message
 }
-
-func digits(number int) int {
-	count := 0
-	for number != 0 {
-		number /= 10
-		count += 1
-	}
-	return count
-}

errors/errors_task.go

@@ -141,21 +141,37 @@ func (err *TaskCancelledNoTerminalError) Code() int {
 	return CodeTaskCancelled
 }
 
-// TaskMissingRequiredVars is returned when a task is missing required variables.
-type TaskMissingRequiredVars struct {
+// TaskMissingRequiredVarsError is returned when a task is missing required variables.
+
+type MissingVar struct {
+	Name          string
+	AllowedValues []string
+}
+type TaskMissingRequiredVarsError struct {
 	TaskName    string
-	MissingVars []string
+	MissingVars []MissingVar
 }
 
-func (err *TaskMissingRequiredVars) Error() string {
+func (v MissingVar) String() string {
+	if len(v.AllowedValues) == 0 {
+		return v.Name
+	}
+	return fmt.Sprintf("%s (allowed values: %v)", v.Name, v.AllowedValues)
+}
+
+func (err *TaskMissingRequiredVarsError) Error() string {
+	var vars []string
+	for _, v := range err.MissingVars {
+		vars = append(vars, v.String())
+	}
+
 	return fmt.Sprintf(
 		`task: Task %q cancelled because it is missing required variables: %s`,
 		err.TaskName,
-		strings.Join(err.MissingVars, ", "),
-	)
+		strings.Join(vars, ", "))
 }
 
-func (err *TaskMissingRequiredVars) Code() int {
+func (err *TaskMissingRequiredVarsError) Code() int {
 	return CodeTaskMissingRequiredVars
 }
 
@@ -165,12 +181,12 @@ type NotAllowedVar struct {
 	Name  string
 }
 
-type TaskNotAllowedVars struct {
+type TaskNotAllowedVarsError struct {
 	TaskName       string
 	NotAllowedVars []NotAllowedVar
 }
 
-func (err *TaskNotAllowedVars) Error() string {
+func (err *TaskNotAllowedVarsError) Error() string {
 	var builder strings.Builder
 
 	builder.WriteString(fmt.Sprintf("task: Task %q cancelled because it is missing required variables:\n", err.TaskName))
@@ -181,6 +197,6 @@ func (err *TaskNotAllowedVars) Error() string {
 	return builder.String()
 }
 
-func (err *TaskNotAllowedVars) Code() int {
+func (err *TaskNotAllowedVarsError) Code() int {
 	return CodeTaskNotAllowedVars
 }

go.mod

@@ -1,6 +1,6 @@
 module github.com/go-task/task/v3
 
-go 1.22.0
+go 1.23.0
 
 require (
 	github.com/Ladicle/tabwriter v1.0.0
@@ -9,10 +9,10 @@ require (
 	github.com/chainguard-dev/git-urls v1.0.2
 	github.com/davecgh/go-spew v1.1.1
 	github.com/dominikbraun/graph v0.23.0
-	github.com/elliotchance/orderedmap/v2 v2.7.0
+	github.com/elliotchance/orderedmap/v3 v3.1.0
 	github.com/fatih/color v1.18.0
 	github.com/go-git/go-billy/v5 v5.6.2
-	github.com/go-git/go-git/v5 v5.13.2
+	github.com/go-git/go-git/v5 v5.14.0
 	github.com/go-task/slim-sprig/v3 v3.0.0
 	github.com/go-task/template v0.1.0
 	github.com/joho/godotenv v1.5.1
@@ -21,25 +21,25 @@ require (
 	github.com/otiai10/copy v1.14.1
 	github.com/radovskyb/watcher v1.0.7
 	github.com/sajari/fuzzy v1.0.0
-	github.com/spf13/pflag v1.0.5
+	github.com/spf13/pflag v1.0.6
 	github.com/stretchr/testify v1.10.0
 	github.com/zeebo/xxh3 v1.0.2
-	golang.org/x/sync v0.10.0
-	golang.org/x/term v0.28.0
+	golang.org/x/sync v0.12.0
+	golang.org/x/term v0.30.0
 	gopkg.in/yaml.v3 v3.0.1
-	mvdan.cc/sh/v3 v3.10.0
+	mvdan.cc/sh/v3 v3.11.0
 )
 
 require (
 	dario.cat/mergo v1.0.0 // indirect
-	github.com/Microsoft/go-winio v0.6.1 // indirect
+	github.com/Microsoft/go-winio v0.6.2 // indirect
 	github.com/ProtonMail/go-crypto v1.1.5 // indirect
-	github.com/cloudflare/circl v1.3.7 // indirect
-	github.com/cyphar/filepath-securejoin v0.3.6 // indirect
+	github.com/cloudflare/circl v1.6.0 // indirect
+	github.com/cyphar/filepath-securejoin v0.4.1 // indirect
 	github.com/dlclark/regexp2 v1.11.4 // indirect
 	github.com/emirpasic/gods v1.18.1 // indirect
 	github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 // indirect
-	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
+	github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 // indirect
 	github.com/jbenet/go-context v0.0.0-20150711004518-d14ea06fba99 // indirect
 	github.com/kevinburke/ssh_config v1.2.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.7 // indirect
@@ -50,13 +50,13 @@ require (
 	github.com/pjbgf/sha1cd v0.3.2 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
-	github.com/skeema/knownhosts v1.3.0 // indirect
+	github.com/skeema/knownhosts v1.3.1 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
-	golang.org/x/crypto v0.32.0 // indirect
-	golang.org/x/mod v0.18.0 // indirect
-	golang.org/x/net v0.34.0 // indirect
-	golang.org/x/sys v0.29.0 // indirect
-	golang.org/x/tools v0.22.0 // indirect
+	golang.org/x/crypto v0.35.0 // indirect
+	golang.org/x/mod v0.22.0 // indirect
+	golang.org/x/net v0.35.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
+	golang.org/x/tools v0.27.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 )

go.sum

@@ -7,14 +7,12 @@ github.com/Masterminds/semver/v3 v3.3.1/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lpr
 github.com/Microsoft/go-winio v0.5.2/go.mod h1:WpS1mjBmmwHBEWmogvA2mj8546UReBk4v8QkMxJ6pZY=
 github.com/Microsoft/go-winio v0.6.1 h1:9/kr64B9VUZrLm5YYwbGtUJnMgqWVOdUAXu6Migciow=
 github.com/Microsoft/go-winio v0.6.1/go.mod h1:LRdKpFKfdobln8UmuiYcKPot9D2v6svN5+sAH+4kjUM=
-github.com/ProtonMail/go-crypto v1.1.3 h1:nRBOetoydLeUb4nHajyO2bKqMLfWQ/ZPwkXqXxPxCFk=
-github.com/ProtonMail/go-crypto v1.1.3/go.mod h1:rA3QumHc/FZ8pAHreoekgiAbzpNsfQAosU5td4SnOrE=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
 github.com/ProtonMail/go-crypto v1.1.5 h1:eoAQfK2dwL+tFSFpr7TbOaPNUbPiJj4fLYwwGE1FQO4=
 github.com/ProtonMail/go-crypto v1.1.5/go.mod h1:rA3QumHc/FZ8pAHreoekgiAbzpNsfQAosU5td4SnOrE=
-github.com/alecthomas/assert/v2 v2.7.0 h1:QtqSACNS3tF7oasA8CU6A6sXZSBDqnm7RfpLl9bZqbE=
-github.com/alecthomas/assert/v2 v2.7.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
-github.com/alecthomas/chroma/v2 v2.14.0 h1:R3+wzpnUArGcQz7fCETQBzO5n9IMNi13iIs46aU4V9E=
-github.com/alecthomas/chroma/v2 v2.14.0/go.mod h1:QolEbTfmUHIMVpBqxeDnNBj2uoeI4EbYP4i6n68SG4I=
+github.com/alecthomas/assert/v2 v2.11.0 h1:2Q9r3ki8+JYXvGsDyBXwH3LcJ+WK5D0gc5E8vS6K3D0=
+github.com/alecthomas/assert/v2 v2.11.0/go.mod h1:Bze95FyfUr7x34QZrjL+XP+0qgp/zg8yS+TtBj1WA3k=
 github.com/alecthomas/chroma/v2 v2.15.0 h1:LxXTQHFoYrstG2nnV9y2X5O94sOBzf0CIUpSTbpxvMc=
 github.com/alecthomas/chroma/v2 v2.15.0/go.mod h1:gUhVLrPDXPtp/f+L1jo9xepo9gL4eLwRuGAunSZMkio=
 github.com/alecthomas/repr v0.4.0 h1:GhI2A8MACjfegCPVq9f1FLvIBS+DrQ2KQBFZP1iFzXc=
@@ -27,23 +25,25 @@ github.com/chainguard-dev/git-urls v1.0.2 h1:pSpT7ifrpc5X55n4aTTm7FFUE+ZQHKiqpiw
 github.com/chainguard-dev/git-urls v1.0.2/go.mod h1:rbGgj10OS7UgZlbzdUQIQpT0k/D4+An04HJY7Ol+Y/o=
 github.com/cloudflare/circl v1.3.7 h1:qlCDlTPz2n9fu58M0Nh1J/JzcFpfgkFHHX3O35r5vcU=
 github.com/cloudflare/circl v1.3.7/go.mod h1:sRTcRWXGLrKw6yIGJ+l7amYJFfAXbZG0kBSc8r4zxgA=
+github.com/cloudflare/circl v1.6.0 h1:cr5JKic4HI+LkINy2lg3W2jF8sHCVTBncJr5gIIq7qk=
+github.com/cloudflare/circl v1.6.0/go.mod h1:uddAzsPgqdMAYatqJ0lsjX1oECcQLIlRpzZh3pJrofs=
 github.com/creack/pty v1.1.23 h1:4M6+isWdcStXEf15G/RbrMPOQj1dZ7HPZCGwE4kOeP0=
 github.com/creack/pty v1.1.23/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE=
 github.com/cyphar/filepath-securejoin v0.3.6 h1:4d9N5ykBnSp5Xn2JkhocYDkOpURL/18CYMpo6xB9uWM=
 github.com/cyphar/filepath-securejoin v0.3.6/go.mod h1:Sdj7gXlvMcPZsbhwhQ33GguGLDGQL7h7bg04C/+u9jI=
+github.com/cyphar/filepath-securejoin v0.4.1 h1:JyxxyPEaktOD+GAnqIqTf9A8tHyAG22rowi7HkoSU1s=
+github.com/cyphar/filepath-securejoin v0.4.1/go.mod h1:Sdj7gXlvMcPZsbhwhQ33GguGLDGQL7h7bg04C/+u9jI=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
-github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/dlclark/regexp2 v1.11.4 h1:rPYF9/LECdNymJufQKmri9gV604RvvABwgOA8un7yAo=
 github.com/dlclark/regexp2 v1.11.4/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
 github.com/dominikbraun/graph v0.23.0 h1:TdZB4pPqCLFxYhdyMFb1TBdFxp8XLcJfTTBQucVPgCo=
 github.com/dominikbraun/graph v0.23.0/go.mod h1:yOjYyogZLY1LSG9E33JWZJiq5k83Qy2C6POAuiViluc=
-github.com/elazarl/goproxy v1.2.3 h1:xwIyKHbaP5yfT6O9KIeYJR5549MXRQkoQMRXGztz8YQ=
-github.com/elazarl/goproxy v1.2.3/go.mod h1:YfEbZtqP4AetfO6d40vWchF3znWX7C7Vd6ZMfdL8z64=
-github.com/elliotchance/orderedmap/v2 v2.7.0 h1:WHuf0DRo63uLnldCPp9ojm3gskYwEdIIfAUVG5KhoOc=
-github.com/elliotchance/orderedmap/v2 v2.7.0/go.mod h1:85lZyVbpGaGvHvnKa7Qhx7zncAdBIBq6u56Hb1PRU5Q=
+github.com/elazarl/goproxy v1.4.0 h1:4GyuSbFa+s26+3rmYNSuUVsx+HgPrV1bk1jXI0l9wjM=
+github.com/elazarl/goproxy v1.4.0/go.mod h1:X/5W/t+gzDyLfHW4DrMdpjqYjpXsURlBt9lpBDxZZZQ=
+github.com/elliotchance/orderedmap/v3 v3.1.0 h1:j4DJ5ObEmMBt/lcwIecKcoRxIQUEnw0L804lXYDt/pg=
+github.com/elliotchance/orderedmap/v3 v3.1.0/go.mod h1:G+Hc2RwaZvJMcS4JpGCOyViCnGeKf0bTYCGTO4uhjSo=
 github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc=
 github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ=
 github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
@@ -52,16 +52,14 @@ github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c=
 github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU=
 github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376 h1:+zs/tPmkDkHx3U66DAb0lQFJrpS6731Oaa12ikc+DiI=
 github.com/go-git/gcfg v1.5.1-0.20230307220236-3a3c6141e376/go.mod h1:an3vInlBmSxCcxctByoQdvwPiA7DTK7jaaFDBTtu0ic=
-github.com/go-git/go-billy/v5 v5.6.1 h1:u+dcrgaguSSkbjzHwelEjc0Yj300NUevrrPphk/SoRA=
-github.com/go-git/go-billy/v5 v5.6.1/go.mod h1:0AsLr1z2+Uksi4NlElmMblP5rPcDZNRCD8ujZCRR2BE=
 github.com/go-git/go-billy/v5 v5.6.2 h1:6Q86EsPXMa7c3YZ3aLAQsMA0VlWmy43r6FHqa/UNbRM=
 github.com/go-git/go-billy/v5 v5.6.2/go.mod h1:rcFC2rAsp/erv7CMz9GczHcuD0D32fWzH+MJAU+jaUU=
 github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399 h1:eMje31YglSBqCdIqdhKBW8lokaMrL3uTkpGYlE2OOT4=
 github.com/go-git/go-git-fixtures/v4 v4.3.2-0.20231010084843-55a94097c399/go.mod h1:1OCfN199q1Jm3HZlxleg+Dw/mwps2Wbk9frAWm+4FII=
-github.com/go-git/go-git/v5 v5.13.1 h1:DAQ9APonnlvSWpvolXWIuV6Q6zXy2wHbN4cVlNR5Q+M=
-github.com/go-git/go-git/v5 v5.13.1/go.mod h1:qryJB4cSBoq3FRoBRf5A77joojuBcmPJ0qu3XXXVixc=
 github.com/go-git/go-git/v5 v5.13.2 h1:7O7xvsK7K+rZPKW6AQR1YyNhfywkv7B8/FsP3ki6Zv0=
 github.com/go-git/go-git/v5 v5.13.2/go.mod h1:hWdW5P4YZRjmpGHwRH2v3zkWcNl6HeXaXQEMGb3NJ9A=
+github.com/go-git/go-git/v5 v5.14.0 h1:/MD3lCrGjCen5WfEAzKg00MJJffKhC8gzS80ycmCi60=
+github.com/go-git/go-git/v5 v5.14.0/go.mod h1:Z5Xhoia5PcWA3NF8vRLURn9E5FRhSl7dGj9ItW3Wk5k=
 github.com/go-quicktest/qt v1.101.0 h1:O1K29Txy5P2OK0dGo59b7b0LR6wKfIhttaAhHUyn7eI=
 github.com/go-quicktest/qt v1.101.0/go.mod h1:14Bz/f7NwaXPtdYEgzsx46kqSxVwTbzVZsDC26tQJow=
 github.com/go-task/slim-sprig/v3 v3.0.0 h1:sUs3vkvUymDpBKi3qH1YSqBQk9+9D/8M2mN1vB6EwHI=
@@ -70,6 +68,8 @@ github.com/go-task/template v0.1.0 h1:ym/r2G937RZA1bsgiWedNnY9e5kxDT+3YcoAnuIetT
 github.com/go-task/template v0.1.0/go.mod h1:RgwRaZK+kni/hJJ7/AaOE2lPQFPbAdji/DyhC6pxo4k=
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da h1:oI5xCqsCo564l8iNU+DwB5epxmsaqB+rhGL0m5jtYqE=
 github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da/go.mod h1:cIg4eruTrX1D+g88fzRXU5OdNfaM+9IcxsU14FzY7Hc=
+github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8 h1:f+oWsMOmNPc8JmEHVZIycC7hBoQxHH9pNKQORJNozsQ=
+github.com/golang/groupcache v0.0.0-20241129210726-2c02b8208cf8/go.mod h1:wcDNUvekVysuuOpQKo3191zZyTpiI6se1N1ULghS0sw=
 github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
 github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
 github.com/hexops/gotextdiff v1.0.3 h1:gitA9+qJrrTCsiCl7+kh75nPqQt1cx4ZkudSTLoUqJM=
@@ -102,16 +102,10 @@ github.com/muesli/cancelreader v0.2.2 h1:3I4Kt4BQjOR54NavqnDogx/MIoWBFa0StPA8ELU
 github.com/muesli/cancelreader v0.2.2/go.mod h1:3XuTXfFS2VjM+HTLZY9Ak0l6eUKfijIfMUZ4EgX0QYo=
 github.com/onsi/gomega v1.34.1 h1:EUMJIKUjM8sKjYbtxQI9A4z2o+rruxnzNvpknOXie6k=
 github.com/onsi/gomega v1.34.1/go.mod h1:kU1QgUvBDLXBJq618Xvm2LUX6rSAfRaFRTcdOeDLwwY=
-github.com/otiai10/copy v1.14.0 h1:dCI/t1iTdYGtkvCuBG2BgR6KZa83PTclw4U5n2wAllU=
-github.com/otiai10/copy v1.14.0/go.mod h1:ECfuL02W+/FkTWZWgQqXPWZgW9oeKCSQ5qVfSc4qc4w=
 github.com/otiai10/copy v1.14.1 h1:5/7E6qsUMBaH5AnQ0sSLzzTg1oTECmcCmT6lvF45Na8=
 github.com/otiai10/copy v1.14.1/go.mod h1:oQwrEDDOci3IM8dJF0d8+jnbfPDllW6vUjNc3DoZm9I=
-github.com/otiai10/mint v1.5.1 h1:XaPLeE+9vGbuyEHem1JNk3bYc7KKqyI/na0/mLd/Kks=
-github.com/otiai10/mint v1.5.1/go.mod h1:MJm72SBthJjz8qhefc4z1PYEieWmy8Bku7CjcAqyUSM=
 github.com/otiai10/mint v1.6.3 h1:87qsV/aw1F5as1eH1zS/yqHY85ANKVMgkDrf9rcxbQs=
 github.com/otiai10/mint v1.6.3/go.mod h1:MJm72SBthJjz8qhefc4z1PYEieWmy8Bku7CjcAqyUSM=
-github.com/pjbgf/sha1cd v0.3.0 h1:4D5XXmUUBUl/xQ6IjCkEAbqXskkq/4O7LmGn0AqMDs4=
-github.com/pjbgf/sha1cd v0.3.0/go.mod h1:nZ1rrWOcGJ5uZgEEVL1VUM9iRQiZvWdbZjkKyFzPPsI=
 github.com/pjbgf/sha1cd v0.3.2 h1:a9wb0bp1oC2TGwStyn0Umc/IGKQnEgF0vVaZ8QF8eo4=
 github.com/pjbgf/sha1cd v0.3.2/go.mod h1:zQWigSxVmsHEZow5qaLtPYxpcKMMQpa09ixqBxuCS6A=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
@@ -129,8 +123,10 @@ github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3/go.mod h1:A0bzQcvG
 github.com/sirupsen/logrus v1.7.0/go.mod h1:yWOB1SBYBC5VeMP7gHvWumXLIWorT60ONWic61uBYv0=
 github.com/skeema/knownhosts v1.3.0 h1:AM+y0rI04VksttfwjkSTNQorvGqmwATnvnAHpSgc0LY=
 github.com/skeema/knownhosts v1.3.0/go.mod h1:sPINvnADmT/qYH1kfv+ePMmOBTH6Tbl7b5LvTDjFK7M=
-github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
-github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/skeema/knownhosts v1.3.1 h1:X2osQ+RAjK76shCbvhHHHVl3ZlgDm8apHEHFqRjnBY8=
+github.com/skeema/knownhosts v1.3.1/go.mod h1:r7KTdC8l4uxWRyK2TpQZ/1o5HaSzh06ePQNxPwTcfiY=
+github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
+github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
 github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
@@ -145,21 +141,24 @@ github.com/zeebo/assert v1.3.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN
 github.com/zeebo/xxh3 v1.0.2 h1:xZmwmqxHZA8AI603jOQ0tMqmBr9lPeFwGg6d+xy9DC0=
 github.com/zeebo/xxh3 v1.0.2/go.mod h1:5NWz9Sef7zIDm2JHfFlcQvNekmcEl9ekUZQQKCYaDcA=
 golang.org/x/crypto v0.0.0-20220622213112-05595931fe9d/go.mod h1:IxCIyHEi3zRg3s0A5j5BB6A9Jmi73HwBIUl50j+osU4=
-golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
-golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
 golang.org/x/crypto v0.32.0 h1:euUpcYgM8WcP71gNpTqQCn6rC2t6ULUPiOzfWaXVVfc=
 golang.org/x/crypto v0.32.0/go.mod h1:ZnnJkOaASj8g0AjIduWNlq2NRxL0PlBrbKVyZ6V/Ugc=
+golang.org/x/crypto v0.35.0 h1:b15kiHdrGCHrP6LvwaQ3c03kgNhhiMgvlhxHQhmg2Xs=
+golang.org/x/crypto v0.35.0/go.mod h1:dy7dXNW32cAb/6/PRuTNsix8T+vJAqvuIy5Bli/x0YQ=
 golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8=
 golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY=
 golang.org/x/mod v0.18.0 h1:5+9lSbEzPSdWkH32vYPBwEpX8KwDbM52Ud9xBUvNlb0=
 golang.org/x/mod v0.18.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.22.0/go.mod h1:6SkKJ3Xj0I0BrPOZoBy3bdMptDDU9oJrpohJ3eWZ1fY=
 golang.org/x/net v0.0.0-20211112202133-69e39bad7dc2/go.mod h1:9nx3DQGgdP8bBQD5qxJ1jj9UTztislL4KSBs9R2vV5Y=
-golang.org/x/net v0.33.0 h1:74SYHlV8BIgHIFC/LrYkOGIwL19eTYXQ5wc6TBuO36I=
-golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
 golang.org/x/net v0.34.0 h1:Mb7Mrk043xzHgnRM88suvJFwzVrRfHEHJEl5/71CKw0=
 golang.org/x/net v0.34.0/go.mod h1:di0qlW3YNM5oh6GqDGQr92MyTozJPmybPK4Ev/Gm31k=
-golang.org/x/sync v0.10.0 h1:3NQrjDixjgGwUOCaF8w2+VYHv0Ve/vGYSbdkTa98gmQ=
-golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/net v0.35.0 h1:T5GQRQb2y08kTAByq9L4/bz8cipCdA8FbRTXewonqY8=
+golang.org/x/net v0.35.0/go.mod h1:EglIi67kWsHKlRzzVMUD93VMSWGFOMSZgxFjparz1Qk=
+golang.org/x/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w=
+golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sync v0.12.0 h1:MHc5BpPuC30uJk597Ri8TV3CNZcTLu6B6z4lJy+g6Jw=
+golang.org/x/sync v0.12.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20191026070338-33540a1f6037/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
 golang.org/x/sys v0.0.0-20210124154548-22da62e12c0c/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
@@ -169,21 +168,22 @@ golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
-golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
-golang.org/x/sys v0.29.0 h1:TPYlXGxvx1MGTn2GiZDhnjPA9wZzZeGKHHmKhHYvgaU=
-golang.org/x/sys v0.29.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.30.0 h1:QjkSwP/36a20jFYWkSue1YwXzLmsV5Gfq7Eiy72C1uc=
+golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
 golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
-golang.org/x/term v0.27.0 h1:WP60Sv1nlK1T6SupCHbXzSaN0b9wUmsPoRS9b61A23Q=
-golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM=
-golang.org/x/term v0.28.0 h1:/Ts8HFuMR2E6IP/jlo7QVLZHggjKQbhu/7H0LJFr3Gg=
-golang.org/x/term v0.28.0/go.mod h1:Sw/lC2IAUZ92udQNf3WodGtn4k/XoLyZoh8v/8uiwek=
+golang.org/x/term v0.29.0 h1:L6pJp37ocefwRRtYPKSWOWzOtWSxVajvz2ldH/xi3iU=
+golang.org/x/term v0.29.0/go.mod h1:6bl4lRlvVuDgSf3179VpIxBF0o10JUpXWOnI7nErv7s=
+golang.org/x/term v0.30.0 h1:PQ39fJZ+mfadBm0y5WlL4vlM7Sx1Hgf13sMIY2+QS9Y=
+golang.org/x/term v0.30.0/go.mod h1:NYYFdzHoI5wRh/h5tDMdMqCqPJZEuNqVR5xJLd/n67g=
 golang.org/x/text v0.3.6/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
 golang.org/x/text v0.21.0 h1:zyQAAkrwaneQ066sspRyJaG9VNi/YJ1NfzcGB3hZ/qo=
 golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
 golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
 golang.org/x/tools v0.22.0 h1:gqSGLZqv+AI9lIQzniJ0nZDRG5GBPsSi+DRNHWNz6yA=
 golang.org/x/tools v0.22.0/go.mod h1:aCwcsjqvq7Yqt6TNyX7QMU2enbQ/Gt0bo6krSeEri+c=
+golang.org/x/tools v0.27.0/go.mod h1:sUi0ZgbwW9ZPAq26Ekut+weQPR5eIM6GQLQ1Yjm1H0Q=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
 gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
@@ -196,3 +196,5 @@ gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 mvdan.cc/sh/v3 v3.10.0 h1:v9z7N1DLZ7owyLM/SXZQkBSXcwr2IGMm2LY2pmhVXj4=
 mvdan.cc/sh/v3 v3.10.0/go.mod h1:z/mSSVyLFGZzqb3ZIKojjyqIx/xbmz/UHdCSv9HmqXY=
+mvdan.cc/sh/v3 v3.11.0 h1:q5h+XMDRfUGUedCqFFsjoFjrhwf2Mvtt1rkMvVz0blw=
+mvdan.cc/sh/v3 v3.11.0/go.mod h1:LRM+1NjoYCzuq/WZ6y44x14YNAI0NK7FLPeQSaFagGg=

help.go

@@ -128,18 +128,14 @@ func (e *Executor) ListTaskNames(allTasks bool) error {
 		w = e.Stdout
 	}
 
-	// Get the list of tasks and sort them
-	tasks := e.Taskfile.Tasks.Values()
-
 	// Sort the tasks
 	if e.TaskSorter == nil {
-		e.TaskSorter = &sort.AlphaNumericWithRootTasksFirst{}
+		e.TaskSorter = sort.AlphaNumericWithRootTasksFirst
 	}
-	e.TaskSorter.Sort(tasks)
 
 	// Create a list of task names
 	taskNames := make([]string, 0, e.Taskfile.Tasks.Len())
-	for _, task := range tasks {
+	for task := range e.Taskfile.Tasks.Values(e.TaskSorter) {
 		if (allTasks || task.Desc != "") && !task.Internal {
 			taskNames = append(taskNames, strings.TrimRight(task.Task, ":"))
 			for _, alias := range task.Aliases {

init.go

@@ -1,7 +1,6 @@
 package task
 
 import (
-	"io"
 	"os"
 
 	"github.com/go-task/task/v3/errors"
@@ -22,19 +21,31 @@ tasks:
     silent: true
 `
 
-const DefaultTaskFilename = "Taskfile.yml"
+const defaultTaskFilename = "Taskfile.yml"
 
-// InitTaskfile creates a new Taskfile
-func InitTaskfile(w io.Writer, dir string) error {
-	f := filepathext.SmartJoin(dir, DefaultTaskFilename)
-
-	if _, err := os.Stat(f); err == nil {
-		return errors.TaskfileAlreadyExistsError{}
+// InitTaskfile creates a new Taskfile at path.
+//
+// path can be either a file path or a directory path.
+// If path is a directory, path/Taskfile.yml will be created.
+//
+// The final file path is always returned and may be different from the input path.
+func InitTaskfile(path string) (string, error) {
+	fi, err := os.Stat(path)
+	if err == nil && !fi.IsDir() {
+		return path, errors.TaskfileAlreadyExistsError{}
 	}
 
-	if err := os.WriteFile(f, []byte(DefaultTaskfile), 0o644); err != nil {
-		return err
+	if fi != nil && fi.IsDir() {
+		path = filepathext.SmartJoin(path, defaultTaskFilename)
+		// path was a directory, so check if Taskfile.yml exists in it
+		if _, err := os.Stat(path); err == nil {
+			return path, errors.TaskfileAlreadyExistsError{}
+		}
 	}
 
-	return nil
+	if err := os.WriteFile(path, []byte(DefaultTaskfile), 0o644); err != nil {
+		return path, err
+	}
+
+	return path, nil
 }

init_test.go

@@ -1,7 +1,6 @@
 package task_test
 
 import (
-	"io"
 	"os"
 	"testing"
 
@@ -9,7 +8,7 @@ import (
 	"github.com/go-task/task/v3/internal/filepathext"
 )
 
-func TestInit(t *testing.T) {
+func TestInitDir(t *testing.T) {
 	t.Parallel()
 
 	const dir = "testdata/init"
@@ -20,12 +19,34 @@ func TestInit(t *testing.T) {
 		t.Errorf("Taskfile.yml should not exist")
 	}
 
-	if err := task.InitTaskfile(io.Discard, dir); err != nil {
+	if _, err := task.InitTaskfile(dir); err != nil {
 		t.Error(err)
 	}
 
 	if _, err := os.Stat(file); err != nil {
 		t.Errorf("Taskfile.yml should exist")
 	}
+
+	_ = os.Remove(file)
+}
+
+func TestInitFile(t *testing.T) {
+	t.Parallel()
+
+	const dir = "testdata/init"
+	file := filepathext.SmartJoin(dir, "Tasks.yml")
+
+	_ = os.Remove(file)
+	if _, err := os.Stat(file); err == nil {
+		t.Errorf("Tasks.yml should not exist")
+	}
+
+	if _, err := task.InitTaskfile(file); err != nil {
+		t.Error(err)
+	}
+
+	if _, err := os.Stat(file); err != nil {
+		t.Errorf("Tasks.yml should exist")
+	}
 	_ = os.Remove(file)
 }

internal/compiler/env.go

@@ -1,20 +0,0 @@
-package compiler
-
-import (
-	"os"
-	"strings"
-
-	"github.com/go-task/task/v3/taskfile/ast"
-)
-
-// GetEnviron the all return all environment variables encapsulated on a
-// ast.Vars
-func GetEnviron() *ast.Vars {
-	m := ast.NewVars()
-	for _, e := range os.Environ() {
-		keyVal := strings.SplitN(e, "=", 2)
-		key, val := keyVal[0], keyVal[1]
-		m.Set(key, ast.Var{Value: val})
-	}
-	return m
-}

internal/deepcopy/deepcopy.go

@@ -3,7 +3,7 @@ package deepcopy
 import (
 	"reflect"
 
-	"github.com/elliotchance/orderedmap/v2"
+	"github.com/elliotchance/orderedmap/v3"
 )
 
 type Copier[T any] interface {

internal/env/env.go

@@ -3,6 +3,7 @@ package env
 import (
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/go-task/task/v3/internal/experiments"
 	"github.com/go-task/task/v3/taskfile/ast"
@@ -10,6 +11,18 @@ import (
 
 const taskVarPrefix = "TASK_"
 
+// GetEnviron the all return all environment variables encapsulated on a
+// ast.Vars
+func GetEnviron() *ast.Vars {
+	m := ast.NewVars()
+	for _, e := range os.Environ() {
+		keyVal := strings.SplitN(e, "=", 2)
+		key, val := keyVal[0], keyVal[1]
+		m.Set(key, ast.Var{Value: val})
+	}
+	return m
+}
+
 func Get(t *ast.Task) []string {
 	if t.Env == nil {
 		return nil

internal/experiments/errors.go

@@ -2,13 +2,16 @@ package experiments
 
 import (
 	"fmt"
+	"strconv"
 	"strings"
+
+	"github.com/go-task/task/v3/internal/slicesext"
 )
 
 type InvalidValueError struct {
 	Name          string
-	AllowedValues []string
-	Value         string
+	AllowedValues []int
+	Value         int
 }
 
 func (err InvalidValueError) Error() string {
@@ -16,7 +19,7 @@ func (err InvalidValueError) Error() string {
 		"task: Experiment %q has an invalid value %q (allowed values: %s)",
 		err.Name,
 		err.Value,
-		strings.Join(err.AllowedValues, ", "),
+		strings.Join(slicesext.Convert(err.AllowedValues, strconv.Itoa), ", "),
 	)
 }
 

internal/experiments/experiment.go

@@ -3,18 +3,24 @@ package experiments
 import (
 	"fmt"
 	"slices"
+	"strconv"
 )
 
 type Experiment struct {
-	Name          string   // The name of the experiment.
-	AllowedValues []string // The values that can enable this experiment.
-	Value         string   // The version of the experiment that is enabled.
+	Name          string // The name of the experiment.
+	AllowedValues []int  // The values that can enable this experiment.
+	Value         int    // The version of the experiment that is enabled.
 }
 
 // New creates a new experiment with the given name and sets the values that can
 // enable it.
-func New(xName string, allowedValues ...string) Experiment {
-	value := getEnv(xName)
+func New(xName string, allowedValues ...int) Experiment {
+	value := experimentConfig.Experiments[xName]
+
+	if value == 0 {
+		value, _ = strconv.Atoi(getEnv(xName))
+	}
+
 	x := Experiment{
 		Name:          xName,
 		AllowedValues: allowedValues,
@@ -24,21 +30,21 @@ func New(xName string, allowedValues ...string) Experiment {
 	return x
 }
 
-func (x *Experiment) Enabled() bool {
+func (x Experiment) Enabled() bool {
 	return slices.Contains(x.AllowedValues, x.Value)
 }
 
-func (x *Experiment) Active() bool {
+func (x Experiment) Active() bool {
 	return len(x.AllowedValues) > 0
 }
 
 func (x Experiment) Valid() error {
-	if !x.Active() && x.Value != "" {
+	if !x.Active() && x.Value != 0 {
 		return &InactiveError{
 			Name: x.Name,
 		}
 	}
-	if !x.Enabled() && x.Value != "" {
+	if !x.Enabled() && x.Value != 0 {
 		return &InvalidValueError{
 			Name:          x.Name,
 			AllowedValues: x.AllowedValues,
@@ -50,7 +56,7 @@ func (x Experiment) Valid() error {
 
 func (x Experiment) String() string {
 	if x.Enabled() {
-		return fmt.Sprintf("on (%s)", x.Value)
+		return fmt.Sprintf("on (%d)", x.Value)
 	}
 	return "off"
 }

internal/experiments/experiment_test.go

@@ -1,6 +1,7 @@
 package experiments_test
 
 import (
+	"strconv"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -15,8 +16,8 @@ func TestNew(t *testing.T) {
 	)
 	tests := []struct {
 		name          string
-		allowedValues []string
-		value         string
+		allowedValues []int
+		value         int
 		wantEnabled   bool
 		wantActive    bool
 		wantValid     error
@@ -28,7 +29,7 @@ func TestNew(t *testing.T) {
 		},
 		{
 			name:        `[] allowed, value="1"`,
-			value:       "1",
+			value:       1,
 			wantEnabled: false,
 			wantActive:  false,
 			wantValid: &experiments.InactiveError{
@@ -37,33 +38,33 @@ func TestNew(t *testing.T) {
 		},
 		{
 			name:          `[1] allowed, value=""`,
-			allowedValues: []string{"1"},
+			allowedValues: []int{1},
 			wantEnabled:   false,
 			wantActive:    true,
 		},
 		{
 			name:          `[1] allowed, value="1"`,
-			allowedValues: []string{"1"},
-			value:         "1",
+			allowedValues: []int{1},
+			value:         1,
 			wantEnabled:   true,
 			wantActive:    true,
 		},
 		{
 			name:          `[1] allowed, value="2"`,
-			allowedValues: []string{"1"},
-			value:         "2",
+			allowedValues: []int{1},
+			value:         2,
 			wantEnabled:   false,
 			wantActive:    true,
 			wantValid: &experiments.InvalidValueError{
 				Name:          exampleExperiment,
-				AllowedValues: []string{"1"},
-				Value:         "2",
+				AllowedValues: []int{1},
+				Value:         2,
 			},
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			t.Setenv(exampleExperimentEnv, tt.value)
+			t.Setenv(exampleExperimentEnv, strconv.Itoa(tt.value))
 			x := experiments.New(exampleExperiment, tt.allowedValues...)
 			assert.Equal(t, exampleExperiment, x.Name)
 			assert.Equal(t, tt.wantEnabled, x.Enabled())

internal/experiments/experiments.go

@@ -6,13 +6,24 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/Masterminds/semver/v3"
 	"github.com/joho/godotenv"
 	"github.com/spf13/pflag"
+	"gopkg.in/yaml.v3"
 )
 
 const envPrefix = "TASK_X_"
 
-// A set of experiments that can be enabled or disabled.
+var defaultConfigFilenames = []string{
+	".taskrc.yml",
+	".taskrc.yaml",
+}
+
+type experimentConfigFile struct {
+	Experiments map[string]int `yaml:"experiments"`
+	Version     *semver.Version
+}
+
 var (
 	GentleForce     Experiment
 	RemoteTaskfiles Experiment
@@ -22,15 +33,19 @@ var (
 )
 
 // An internal list of all the initialized experiments used for iterating.
-var xList []Experiment
+var (
+	xList            []Experiment
+	experimentConfig experimentConfigFile
+)
 
 func init() {
 	readDotEnv()
-	GentleForce = New("GENTLE_FORCE", "1")
-	RemoteTaskfiles = New("REMOTE_TASKFILES", "1")
+	experimentConfig = readConfig()
+	GentleForce = New("GENTLE_FORCE", 1)
+	RemoteTaskfiles = New("REMOTE_TASKFILES", 1)
 	AnyVariables = New("ANY_VARIABLES")
-	MapVariables = New("MAP_VARIABLES", "1", "2")
-	EnvPrecedence = New("ENV_PRECEDENCE", "1")
+	MapVariables = New("MAP_VARIABLES", 1, 2)
+	EnvPrecedence = New("ENV_PRECEDENCE", 1)
 }
 
 // Validate checks if any experiments have been enabled while being inactive.
@@ -53,7 +68,7 @@ func getEnv(xName string) string {
 	return os.Getenv(envName)
 }
 
-func getEnvFilePath() string {
+func getFilePath(filename string) string {
 	// Parse the CLI flags again to get the directory/taskfile being run
 	// We use a flagset here so that we can parse a subset of flags without exiting on error.
 	var dir, taskfile string
@@ -64,18 +79,18 @@ func getEnvFilePath() string {
 	_ = fs.Parse(os.Args[1:])
 	// If the directory is set, find a .env file in that directory.
 	if dir != "" {
-		return filepath.Join(dir, ".env")
+		return filepath.Join(dir, filename)
 	}
 	// If the taskfile is set, find a .env file in the directory containing the Taskfile.
 	if taskfile != "" {
-		return filepath.Join(filepath.Dir(taskfile), ".env")
+		return filepath.Join(filepath.Dir(taskfile), filename)
 	}
 	// Otherwise just use the current working directory.
-	return ".env"
+	return filename
 }
 
 func readDotEnv() {
-	env, _ := godotenv.Read(getEnvFilePath())
+	env, _ := godotenv.Read(getFilePath(".env"))
 	// If the env var is an experiment, set it.
 	for key, value := range env {
 		if strings.HasPrefix(key, envPrefix) {
@@ -83,3 +98,27 @@ func readDotEnv() {
 		}
 	}
 }
+
+func readConfig() experimentConfigFile {
+	var cfg experimentConfigFile
+
+	var content []byte
+	var err error
+	for _, filename := range defaultConfigFilenames {
+		path := getFilePath(filename)
+		content, err = os.ReadFile(path)
+		if err == nil {
+			break
+		}
+	}
+
+	if err != nil {
+		return experimentConfigFile{}
+	}
+
+	if err := yaml.Unmarshal(content, &cfg); err != nil {
+		return experimentConfigFile{}
+	}
+
+	return cfg
+}

internal/filepathext/filepathext.go

@@ -55,3 +55,9 @@ func TryAbsToRel(abs string) string {
 
 	return rel
 }
+
+// IsExtOnly checks whether path points to a file with no name but with
+// an extension, i.e. ".yaml"
+func IsExtOnly(path string) bool {
+	return filepath.Base(path) == filepath.Ext(path)
+}

internal/slicesext/slicesext.go

@@ -18,3 +18,15 @@ func UniqueJoin[T cmp.Ordered](ss ...[]T) []T {
 	slices.Sort(r)
 	return slices.Compact(r)
 }
+
+func Convert[T, U any](s []T, f func(T) U) []U {
+	// Create a new slice with the same length as the input slice
+	result := make([]U, len(s))
+
+	// Convert each element using the provided function
+	for i, v := range s {
+		result[i] = f(v)
+	}
+
+	return result
+}

internal/slicesext/slicesext_test.go

@@ -0,0 +1,86 @@
+package slicesext
+
+import (
+	"math"
+	"strconv"
+	"testing"
+)
+
+func TestConvertIntToString(t *testing.T) {
+	t.Parallel()
+	input := []int{1, 2, 3, 4, 5}
+	expected := []string{"1", "2", "3", "4", "5"}
+	result := Convert(input, strconv.Itoa)
+
+	if len(result) != len(expected) {
+		t.Errorf("Expected length %d, got %d", len(expected), len(result))
+	}
+
+	for i := range expected {
+		if result[i] != expected[i] {
+			t.Errorf("At index %d: expected %v, got %v", i, expected[i], result[i])
+		}
+	}
+}
+
+func TestConvertStringToInt(t *testing.T) {
+	t.Parallel()
+	input := []string{"1", "2", "3", "4", "5"}
+	expected := []int{1, 2, 3, 4, 5}
+	result := Convert(input, func(s string) int {
+		n, _ := strconv.Atoi(s)
+		return n
+	})
+
+	if len(result) != len(expected) {
+		t.Errorf("Expected length %d, got %d", len(expected), len(result))
+	}
+
+	for i := range expected {
+		if result[i] != expected[i] {
+			t.Errorf("At index %d: expected %v, got %v", i, expected[i], result[i])
+		}
+	}
+}
+
+func TestConvertFloatToInt(t *testing.T) {
+	t.Parallel()
+	input := []float64{1.1, 2.2, 3.7, 4.5, 5.9}
+	expected := []int{1, 2, 4, 5, 6}
+	result := Convert(input, func(f float64) int {
+		return int(math.Round(f))
+	})
+
+	if len(result) != len(expected) {
+		t.Errorf("Expected length %d, got %d", len(expected), len(result))
+	}
+
+	for i := range expected {
+		if result[i] != expected[i] {
+			t.Errorf("At index %d: expected %v, got %v", i, expected[i], result[i])
+		}
+	}
+}
+
+func TestConvertEmptySlice(t *testing.T) {
+	t.Parallel()
+	input := []int{}
+	result := Convert(input, strconv.Itoa)
+
+	if len(result) != 0 {
+		t.Errorf("Expected empty slice, got length %d", len(result))
+	}
+}
+
+func TestConvertNilSlice(t *testing.T) {
+	t.Parallel()
+	var input []int
+	result := Convert(input, strconv.Itoa)
+
+	if result == nil {
+		t.Error("Expected non-nil empty slice, got nil")
+	}
+	if len(result) != 0 {
+		t.Errorf("Expected empty slice, got length %d", len(result))
+	}
+}

internal/sort/sorter.go

@@ -1,44 +1,39 @@
 package sort
 
 import (
+	"slices"
 	"sort"
 	"strings"
-
-	"github.com/go-task/task/v3/taskfile/ast"
 )
 
-type TaskSorter interface {
-	Sort([]*ast.Task)
+// A Sorter is any function that sorts a set of tasks.
+type Sorter func(items []string, namespaces []string) []string
+
+// AlphaNumeric sorts the JSON output so that tasks are in alpha numeric order
+// by task name.
+func AlphaNumeric(items []string, namespaces []string) []string {
+	slices.Sort(items)
+	return items
 }
 
-type Noop struct{}
-
-func (s *Noop) Sort(tasks []*ast.Task) {}
-
-type AlphaNumeric struct{}
-
-// Tasks that are not namespaced should be listed before tasks that are.
-// We detect this by searching for a ':' in the task name.
-func (s *AlphaNumeric) Sort(tasks []*ast.Task) {
-	sort.Slice(tasks, func(i, j int) bool {
-		return tasks[i].Task < tasks[j].Task
-	})
-}
-
-type AlphaNumericWithRootTasksFirst struct{}
-
-// Tasks that are not namespaced should be listed before tasks that are.
-// We detect this by searching for a ':' in the task name.
-func (s *AlphaNumericWithRootTasksFirst) Sort(tasks []*ast.Task) {
-	sort.Slice(tasks, func(i, j int) bool {
-		iContainsColon := strings.Contains(tasks[i].Task, ":")
-		jContainsColon := strings.Contains(tasks[j].Task, ":")
+// AlphaNumericWithRootTasksFirst sorts the JSON output so that tasks are in
+// alpha numeric order by task name. It will also ensure that tasks that are not
+// namespaced will be listed before tasks that are. We detect this by searching
+// for a ':' in the task name.
+func AlphaNumericWithRootTasksFirst(items []string, namespaces []string) []string {
+	if len(namespaces) > 0 {
+		return AlphaNumeric(items, namespaces)
+	}
+	sort.Slice(items, func(i, j int) bool {
+		iContainsColon := strings.Contains(items[i], ":")
+		jContainsColon := strings.Contains(items[j], ":")
 		if iContainsColon == jContainsColon {
-			return tasks[i].Task < tasks[j].Task
+			return items[i] < items[j]
 		}
 		if !iContainsColon && jContainsColon {
 			return true
 		}
 		return false
 	})
+	return items
 }

internal/sort/sorter_test.go

@@ -4,39 +4,37 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
-
-	"github.com/go-task/task/v3/taskfile/ast"
 )
 
 func TestAlphaNumericWithRootTasksFirst_Sort(t *testing.T) {
 	t.Parallel()
 
-	task1 := &ast.Task{Task: "task1"}
-	task2 := &ast.Task{Task: "task2"}
-	task3 := &ast.Task{Task: "ns1:task3"}
-	task4 := &ast.Task{Task: "ns2:task4"}
-	task5 := &ast.Task{Task: "task5"}
-	task6 := &ast.Task{Task: "ns3:task6"}
+	item1 := "a-item1"
+	item2 := "m-item2"
+	item3 := "ns1:item3"
+	item4 := "ns2:item4"
+	item5 := "z-item5"
+	item6 := "ns3:item6"
 
 	tests := []struct {
 		name  string
-		tasks []*ast.Task
-		want  []*ast.Task
+		items []string
+		want  []string
 	}{
 		{
-			name:  "no namespace tasks sorted alphabetically first",
-			tasks: []*ast.Task{task3, task2, task1},
-			want:  []*ast.Task{task1, task2, task3},
+			name:  "no namespace items sorted alphabetically first",
+			items: []string{item3, item2, item1},
+			want:  []string{item1, item2, item3},
 		},
 		{
-			name:  "namespace tasks sorted alphabetically after non-namespaced tasks",
-			tasks: []*ast.Task{task3, task4, task5},
-			want:  []*ast.Task{task5, task3, task4},
+			name:  "namespace items sorted alphabetically after non-namespaced items",
+			items: []string{item3, item4, item5},
+			want:  []string{item5, item3, item4},
 		},
 		{
-			name:  "all tasks sorted alphabetically with root tasks first",
-			tasks: []*ast.Task{task6, task5, task4, task3, task2, task1},
-			want:  []*ast.Task{task1, task2, task5, task3, task4, task6},
+			name:  "all items sorted alphabetically with root items first",
+			items: []string{item6, item5, item4, item3, item2, item1},
+			want:  []string{item1, item2, item5, item3, item4, item6},
 		},
 	}
 
@@ -44,9 +42,8 @@ func TestAlphaNumericWithRootTasksFirst_Sort(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			s := &AlphaNumericWithRootTasksFirst{}
-			s.Sort(tt.tasks)
-			assert.Equal(t, tt.want, tt.tasks)
+			AlphaNumericWithRootTasksFirst(tt.items, nil)
+			assert.Equal(t, tt.want, tt.items)
 		})
 	}
 }
@@ -54,22 +51,22 @@ func TestAlphaNumericWithRootTasksFirst_Sort(t *testing.T) {
 func TestAlphaNumeric_Sort(t *testing.T) {
 	t.Parallel()
 
-	task1 := &ast.Task{Task: "task1"}
-	task2 := &ast.Task{Task: "task2"}
-	task3 := &ast.Task{Task: "ns1:task3"}
-	task4 := &ast.Task{Task: "ns2:task4"}
-	task5 := &ast.Task{Task: "task5"}
-	task6 := &ast.Task{Task: "ns3:task6"}
+	item1 := "a-item1"
+	item2 := "m-item2"
+	item3 := "ns1:item3"
+	item4 := "ns2:item4"
+	item5 := "z-item5"
+	item6 := "ns3:item6"
 
 	tests := []struct {
 		name  string
-		tasks []*ast.Task
-		want  []*ast.Task
+		items []string
+		want  []string
 	}{
 		{
-			name:  "all tasks sorted alphabetically",
-			tasks: []*ast.Task{task3, task2, task5, task1, task4, task6},
-			want:  []*ast.Task{task3, task4, task6, task1, task2, task5},
+			name:  "all items sorted alphabetically",
+			items: []string{item3, item2, item5, item1, item4, item6},
+			want:  []string{item1, item2, item3, item4, item6, item5},
 		},
 	}
 
@@ -77,9 +74,8 @@ func TestAlphaNumeric_Sort(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			t.Parallel()
 
-			s := &AlphaNumeric{}
-			s.Sort(tt.tasks)
-			assert.Equal(t, tt.tasks, tt.want)
+			AlphaNumeric(tt.items, nil)
+			assert.Equal(t, tt.want, tt.items)
 		})
 	}
 }

internal/summary/summary.go

@@ -7,10 +7,10 @@ import (
 	"github.com/go-task/task/v3/taskfile/ast"
 )
 
-func PrintTasks(l *logger.Logger, t *ast.Taskfile, c []*ast.Call) {
+func PrintTasks(l *logger.Logger, t *ast.Taskfile, c []string) {
 	for i, call := range c {
 		PrintSpaceBetweenSummaries(l, i)
-		if task, ok := t.Tasks.Get(call.Task); ok {
+		if task, ok := t.Tasks.Get(call); ok {
 			PrintTask(l, task)
 		}
 	}

internal/summary/summary_test.go

@@ -179,7 +179,8 @@ func TestPrintAllWithSpaces(t *testing.T) {
 
 	summary.PrintTasks(&l,
 		&ast.Taskfile{Tasks: tasks},
-		[]*ast.Call{{Task: "t1"}, {Task: "t2"}, {Task: "t3"}})
+		[]string{"t1", "t2", "t3"},
+	)
 
 	assert.True(t, strings.HasPrefix(buffer.String(), "task: t1"))
 	assert.Contains(t, buffer.String(), "\n(task does not have description or summary)\n\n\ntask: t2")

internal/templater/funcs.go

@@ -1,6 +1,7 @@
 package templater
 
 import (
+	"maps"
 	"path/filepath"
 	"runtime"
 	"strings"
@@ -60,13 +61,9 @@ func init() {
 				cap += len(m)
 			}
 			result := make(map[string]any, cap)
-			for k, v := range base {
-				result[k] = v
-			}
+			maps.Copy(result, base)
 			for _, m := range v {
-				for k, v := range m {
-					result[k] = v
-				}
+				maps.Copy(result, m)
 			}
 			return result
 		},
@@ -84,7 +81,5 @@ func init() {
 	taskFuncs["ExeExt"] = taskFuncs["exeExt"]
 
 	templateFuncs = template.FuncMap(sprig.TxtFuncMap())
-	for k, v := range taskFuncs {
-		templateFuncs[k] = v
-	}
+	maps.Copy(templateFuncs, taskFuncs)
 }

internal/templater/templater.go

@@ -141,10 +141,9 @@ func ReplaceVarsWithExtra(vars *ast.Vars, cache *Cache, extra map[string]any) *a
 	}
 
 	newVars := ast.NewVars()
-	_ = vars.Range(func(k string, v ast.Var) error {
+	for k, v := range vars.All() {
 		newVars.Set(k, ReplaceVarWithExtra(v, cache, extra))
-		return nil
-	})
+	}
 
 	return newVars
 }

internal/version/version.go

@@ -12,7 +12,7 @@ var (
 
 func init() {
 	info, ok := debug.ReadBuildInfo()
-	if !ok || info.Main.Version == "" {
+	if !ok || info.Main.Version == "(devel)" || info.Main.Version == "" {
 		version = "unknown"
 	} else {
 		if version == "" {

package-lock.json

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

package.json

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

requires.go

@@ -12,16 +12,19 @@ func (e *Executor) areTaskRequiredVarsSet(t *ast.Task) error {
 		return nil
 	}
 
-	var missingVars []string
+	var missingVars []errors.MissingVar
 	for _, requiredVar := range t.Requires.Vars {
 		_, ok := t.Vars.Get(requiredVar.Name)
 		if !ok {
-			missingVars = append(missingVars, requiredVar.Name)
+			missingVars = append(missingVars, errors.MissingVar{
+				Name:          requiredVar.Name,
+				AllowedValues: requiredVar.Enum,
+			})
 		}
 	}
 
 	if len(missingVars) > 0 {
-		return &errors.TaskMissingRequiredVars{
+		return &errors.TaskMissingRequiredVarsError{
 			TaskName:    t.Name(),
 			MissingVars: missingVars,
 		}
@@ -51,7 +54,7 @@ func (e *Executor) areTaskRequiredVarsAllowedValuesSet(t *ast.Task) error {
 	}
 
 	if len(notAllowedValuesVars) > 0 {
-		return &errors.TaskNotAllowedVars{
+		return &errors.TaskNotAllowedVarsError{
 			TaskName:       t.Name(),
 			NotAllowedVars: notAllowedValuesVars,
 		}

setup.go

@@ -13,7 +13,6 @@ import (
 	"github.com/sajari/fuzzy"
 
 	"github.com/go-task/task/v3/errors"
-	"github.com/go-task/task/v3/internal/compiler"
 	"github.com/go-task/task/v3/internal/env"
 	"github.com/go-task/task/v3/internal/execext"
 	"github.com/go-task/task/v3/internal/filepathext"
@@ -56,7 +55,7 @@ func (e *Executor) Setup() error {
 }
 
 func (e *Executor) getRootNode() (taskfile.Node, error) {
-	node, err := taskfile.NewRootNode(e.Logger, e.Entrypoint, e.Dir, e.Insecure, e.Timeout)
+	node, err := taskfile.NewRootNode(e.Entrypoint, e.Dir, e.Insecure, e.Timeout)
 	if err != nil {
 		return nil, err
 	}
@@ -65,14 +64,21 @@ func (e *Executor) getRootNode() (taskfile.Node, error) {
 }
 
 func (e *Executor) readTaskfile(node taskfile.Node) error {
+	debugFunc := func(s string) {
+		e.Logger.VerboseOutf(logger.Magenta, s)
+	}
+	promptFunc := func(s string) error {
+		return e.Logger.Prompt(logger.Yellow, s, "n", "y", "yes")
+	}
 	reader := taskfile.NewReader(
 		node,
-		e.Insecure,
-		e.Download,
-		e.Offline,
-		e.Timeout,
-		e.TempDir.Remote,
-		e.Logger,
+		taskfile.WithInsecure(e.Insecure),
+		taskfile.WithDownload(e.Download),
+		taskfile.WithOffline(e.Offline),
+		taskfile.WithTimeout(e.Timeout),
+		taskfile.WithTempDir(e.TempDir.Remote),
+		taskfile.WithDebugFunc(debugFunc),
+		taskfile.WithPromptFunc(promptFunc),
 	)
 	graph, err := reader.Read()
 	if err != nil {
@@ -93,12 +99,9 @@ func (e *Executor) setupFuzzyModel() {
 	model.SetThreshold(1) // because we want to build grammar based on every task name
 
 	var words []string
-	for _, taskName := range e.Taskfile.Tasks.Keys() {
-		words = append(words, taskName)
-
-		for _, task := range e.Taskfile.Tasks.Values() {
-			words = slices.Concat(words, task.Aliases)
-		}
+	for name, task := range e.Taskfile.Tasks.All(nil) {
+		words = append(words, name)
+		words = slices.Concat(words, task.Aliases)
 	}
 
 	model.Train(words)
@@ -194,7 +197,7 @@ func (e *Executor) setupCompiler() error {
 		}
 	}
 
-	e.Compiler = &compiler.Compiler{
+	e.Compiler = &Compiler{
 		Dir:            e.Dir,
 		Entrypoint:     e.Entrypoint,
 		UserWorkingDir: e.UserWorkingDir,
@@ -206,21 +209,29 @@ func (e *Executor) setupCompiler() error {
 }
 
 func (e *Executor) readDotEnvFiles() error {
+	if e.Taskfile == nil || len(e.Taskfile.Dotenv) == 0 {
+		return nil
+	}
+
 	if e.Taskfile.Version.LessThan(ast.V3) {
 		return nil
 	}
 
-	env, err := taskfile.Dotenv(e.Compiler, e.Taskfile, e.Dir)
+	vars, err := e.Compiler.GetTaskfileVariables()
 	if err != nil {
 		return err
 	}
 
-	err = env.Range(func(key string, value ast.Var) error {
-		if _, ok := e.Taskfile.Env.Get(key); !ok {
-			e.Taskfile.Env.Set(key, value)
+	env, err := taskfile.Dotenv(vars, e.Taskfile, e.Dir)
+	if err != nil {
+		return err
+	}
+
+	for k, v := range env.All() {
+		if _, ok := e.Taskfile.Env.Get(k); !ok {
+			e.Taskfile.Env.Set(k, v)
 		}
-		return nil
-	})
+	}
 	return err
 }
 
@@ -238,7 +249,7 @@ func (e *Executor) setupConcurrencyState() {
 
 	e.taskCallCount = make(map[string]*int32, e.Taskfile.Tasks.Len())
 	e.mkdirMutexMap = make(map[string]*sync.Mutex, e.Taskfile.Tasks.Len())
-	for _, k := range e.Taskfile.Tasks.Keys() {
+	for k := range e.Taskfile.Tasks.Keys(nil) {
 		e.taskCallCount[k] = new(int32)
 		e.mkdirMutexMap[k] = &sync.Mutex{}
 	}

status.go

@@ -9,7 +9,7 @@ import (
 )
 
 // Status returns an error if any the of given tasks is not up-to-date
-func (e *Executor) Status(ctx context.Context, calls ...*ast.Call) error {
+func (e *Executor) Status(ctx context.Context, calls ...*Call) error {
 	for _, call := range calls {
 
 		// Compile the task

task.go

@@ -11,10 +11,7 @@ import (
 	"sync/atomic"
 	"time"
 
-	"mvdan.cc/sh/v3/interp"
-
 	"github.com/go-task/task/v3/errors"
-	"github.com/go-task/task/v3/internal/compiler"
 	"github.com/go-task/task/v3/internal/env"
 	"github.com/go-task/task/v3/internal/execext"
 	"github.com/go-task/task/v3/internal/fingerprint"
@@ -28,6 +25,7 @@ import (
 
 	"github.com/sajari/fuzzy"
 	"golang.org/x/sync/errgroup"
+	"mvdan.cc/sh/v3/interp"
 )
 
 const (
@@ -71,10 +69,10 @@ type Executor struct {
 	Stderr io.Writer
 
 	Logger             *logger.Logger
-	Compiler           *compiler.Compiler
+	Compiler           *Compiler
 	Output             output.Output
 	OutputStyle        ast.Output
-	TaskSorter         sort.TaskSorter
+	TaskSorter         sort.Sorter
 	UserWorkingDir     string
 	EnableVersionCheck bool
 
@@ -87,8 +85,15 @@ type Executor struct {
 	executionHashesMutex sync.Mutex
 }
 
+// MatchingTask represents a task that matches a given call. It includes the
+// task itself and a list of wildcards that were matched.
+type MatchingTask struct {
+	Task      *ast.Task
+	Wildcards []string
+}
+
 // Run runs Task
-func (e *Executor) Run(ctx context.Context, calls ...*ast.Call) error {
+func (e *Executor) Run(ctx context.Context, calls ...*Call) error {
 	// check if given tasks exist
 	for _, call := range calls {
 		task, err := e.GetTask(call)
@@ -150,7 +155,7 @@ func (e *Executor) Run(ctx context.Context, calls ...*ast.Call) error {
 	return nil
 }
 
-func (e *Executor) splitRegularAndWatchCalls(calls ...*ast.Call) (regularCalls []*ast.Call, watchCalls []*ast.Call, err error) {
+func (e *Executor) splitRegularAndWatchCalls(calls ...*Call) (regularCalls []*Call, watchCalls []*Call, err error) {
 	for _, c := range calls {
 		t, err := e.GetTask(c)
 		if err != nil {
@@ -167,7 +172,7 @@ func (e *Executor) splitRegularAndWatchCalls(calls ...*ast.Call) (regularCalls [
 }
 
 // RunTask runs a task by its name
-func (e *Executor) RunTask(ctx context.Context, call *ast.Call) error {
+func (e *Executor) RunTask(ctx context.Context, call *Call) error {
 	t, err := e.FastCompiledTask(call)
 	if err != nil {
 		return err
@@ -317,7 +322,7 @@ func (e *Executor) runDeps(ctx context.Context, t *ast.Task) error {
 	for _, d := range t.Deps {
 		d := d
 		g.Go(func() error {
-			err := e.RunTask(ctx, &ast.Call{Task: d.Task, Vars: d.Vars, Silent: d.Silent, Indirect: true})
+			err := e.RunTask(ctx, &Call{Task: d.Task, Vars: d.Vars, Silent: d.Silent, Indirect: true})
 			if err != nil {
 				return err
 			}
@@ -328,7 +333,7 @@ func (e *Executor) runDeps(ctx context.Context, t *ast.Task) error {
 	return g.Wait()
 }
 
-func (e *Executor) runDeferred(t *ast.Task, call *ast.Call, i int, deferredExitCode *uint8) {
+func (e *Executor) runDeferred(t *ast.Task, call *Call, i int, deferredExitCode *uint8) {
 	ctx, cancel := context.WithCancel(context.Background())
 	defer cancel()
 
@@ -353,7 +358,7 @@ func (e *Executor) runDeferred(t *ast.Task, call *ast.Call, i int, deferredExitC
 	}
 }
 
-func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *ast.Call, i int) error {
+func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *Call, i int) error {
 	cmd := t.Cmds[i]
 
 	switch {
@@ -361,7 +366,7 @@ func (e *Executor) runCommand(ctx context.Context, t *ast.Task, call *ast.Call,
 		reacquire := e.releaseConcurrencyLimit()
 		defer reacquire()
 
-		err := e.RunTask(ctx, &ast.Call{Task: cmd.Task, Vars: cmd.Vars, Silent: cmd.Silent, Indirect: true})
+		err := e.RunTask(ctx, &Call{Task: cmd.Task, Vars: cmd.Vars, Silent: cmd.Silent, Indirect: true})
 		if err != nil {
 			return err
 		}
@@ -447,12 +452,39 @@ func (e *Executor) startExecution(ctx context.Context, t *ast.Task, execute func
 	return execute(ctx)
 }
 
+// FindMatchingTasks returns a list of tasks that match the given call. A task
+// matches a call if its name is equal to the call's task name or if it matches
+// a wildcard pattern. The function returns a list of MatchingTask structs, each
+// containing a task and a list of wildcards that were matched.
+func (e *Executor) FindMatchingTasks(call *Call) []*MatchingTask {
+	if call == nil {
+		return nil
+	}
+	var matchingTasks []*MatchingTask
+	// If there is a direct match, return it
+	if task, ok := e.Taskfile.Tasks.Get(call.Task); ok {
+		matchingTasks = append(matchingTasks, &MatchingTask{Task: task, Wildcards: nil})
+		return matchingTasks
+	}
+	// Attempt a wildcard match
+	// For now, we can just nil check the task before each loop
+	for _, value := range e.Taskfile.Tasks.All(nil) {
+		if match, wildcards := value.WildcardMatch(call.Task); match {
+			matchingTasks = append(matchingTasks, &MatchingTask{
+				Task:      value,
+				Wildcards: wildcards,
+			})
+		}
+	}
+	return matchingTasks
+}
+
 // GetTask will return the task with the name matching the given call from the taskfile.
 // If no task is found, it will search for tasks with a matching alias.
 // If multiple tasks contain the same alias or no matches are found an error is returned.
-func (e *Executor) GetTask(call *ast.Call) (*ast.Task, error) {
+func (e *Executor) GetTask(call *Call) (*ast.Task, error) {
 	// Search for a matching task
-	matchingTasks := e.Taskfile.Tasks.FindMatchingTasks(call)
+	matchingTasks := e.FindMatchingTasks(call)
 	switch len(matchingTasks) {
 	case 0: // Carry on
 	case 1:
@@ -475,7 +507,7 @@ func (e *Executor) GetTask(call *ast.Call) (*ast.Task, error) {
 	// If didn't find one, search for a task with a matching alias
 	var matchingTask *ast.Task
 	var aliasedTasks []string
-	for _, task := range e.Taskfile.Tasks.Values() {
+	for task := range e.Taskfile.Tasks.Values(nil) {
 		if slices.Contains(task.Aliases, call.Task) {
 			aliasedTasks = append(aliasedTasks, task.Task)
 			matchingTask = task
@@ -511,8 +543,13 @@ func (e *Executor) GetTaskList(filters ...FilterFunc) ([]*ast.Task, error) {
 	// Create an error group to wait for each task to be compiled
 	var g errgroup.Group
 
+	// Sort the tasks
+	if e.TaskSorter == nil {
+		e.TaskSorter = sort.AlphaNumericWithRootTasksFirst
+	}
+
 	// Filter tasks based on the given filter functions
-	for _, task := range e.Taskfile.Tasks.Values() {
+	for task := range e.Taskfile.Tasks.Values(e.TaskSorter) {
 		var shouldFilter bool
 		for _, filter := range filters {
 			if filter(task) {
@@ -527,7 +564,7 @@ func (e *Executor) GetTaskList(filters ...FilterFunc) ([]*ast.Task, error) {
 	// Compile the list of tasks
 	for i := range tasks {
 		g.Go(func() error {
-			compiledTask, err := e.CompiledTaskForTaskList(&ast.Call{Task: tasks[i].Task})
+			compiledTask, err := e.FastCompiledTask(&Call{Task: tasks[i].Task})
 			if err != nil {
 				return err
 			}
@@ -541,12 +578,6 @@ func (e *Executor) GetTaskList(filters ...FilterFunc) ([]*ast.Task, error) {
 		return nil, err
 	}
 
-	// Sort the tasks
-	if e.TaskSorter == nil {
-		e.TaskSorter = &sort.AlphaNumericWithRootTasksFirst{}
-	}
-	e.TaskSorter.Sort(tasks)
-
 	return tasks, nil
 }
 

taskfile/ast/cmd.go

@@ -51,18 +51,53 @@ func (c *Cmd) UnmarshalYAML(node *yaml.Node) error {
 		return nil
 
 	case yaml.MappingNode:
-
-		// A command with additional options
 		var cmdStruct struct {
 			Cmd         string
+			Task        string
 			For         *For
 			Silent      bool
 			Set         []string
 			Shopt       []string
+			Vars        *Vars
 			IgnoreError bool `yaml:"ignore_error"`
+			Defer       *Defer
 			Platforms   []*Platform
 		}
-		if err := node.Decode(&cmdStruct); err == nil && cmdStruct.Cmd != "" {
+		if err := node.Decode(&cmdStruct); err != nil {
+			return errors.NewTaskfileDecodeError(err, node)
+		}
+		if cmdStruct.Defer != nil {
+
+			// A deferred command
+			if cmdStruct.Defer.Cmd != "" {
+				c.Defer = true
+				c.Cmd = cmdStruct.Defer.Cmd
+				c.Silent = cmdStruct.Silent
+				return nil
+			}
+
+			// A deferred task call
+			if cmdStruct.Defer.Task != "" {
+				c.Defer = true
+				c.Task = cmdStruct.Defer.Task
+				c.Vars = cmdStruct.Defer.Vars
+				c.Silent = cmdStruct.Defer.Silent
+				return nil
+			}
+			return nil
+		}
+
+		// A task call
+		if cmdStruct.Task != "" {
+			c.Task = cmdStruct.Task
+			c.Vars = cmdStruct.Vars
+			c.For = cmdStruct.For
+			c.Silent = cmdStruct.Silent
+			return nil
+		}
+
+		// A command with additional options
+		if cmdStruct.Cmd != "" {
 			c.Cmd = cmdStruct.Cmd
 			c.For = cmdStruct.For
 			c.Silent = cmdStruct.Silent
@@ -73,45 +108,6 @@ func (c *Cmd) UnmarshalYAML(node *yaml.Node) error {
 			return nil
 		}
 
-		// A deferred command
-		var deferredCmd struct {
-			Defer  string
-			Silent bool
-		}
-		if err := node.Decode(&deferredCmd); err == nil && deferredCmd.Defer != "" {
-			c.Defer = true
-			c.Cmd = deferredCmd.Defer
-			c.Silent = deferredCmd.Silent
-			return nil
-		}
-
-		// A deferred task call
-		var deferredCall struct {
-			Defer Call
-		}
-		if err := node.Decode(&deferredCall); err == nil && deferredCall.Defer.Task != "" {
-			c.Defer = true
-			c.Task = deferredCall.Defer.Task
-			c.Vars = deferredCall.Defer.Vars
-			c.Silent = deferredCall.Defer.Silent
-			return nil
-		}
-
-		// A task call
-		var taskCall struct {
-			Task   string
-			Vars   *Vars
-			For    *For
-			Silent bool
-		}
-		if err := node.Decode(&taskCall); err == nil && taskCall.Task != "" {
-			c.Task = taskCall.Task
-			c.Vars = taskCall.Vars
-			c.For = taskCall.For
-			c.Silent = taskCall.Silent
-			return nil
-		}
-
 		return errors.NewTaskfileDecodeError(nil, node).WithMessage("invalid keys in command")
 	}
 

taskfile/ast/defer.go

@@ -0,0 +1,45 @@
+package ast
+
+import (
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/errors"
+)
+
+type Defer struct {
+	Cmd    string
+	Task   string
+	Vars   *Vars
+	Silent bool
+}
+
+func (d *Defer) UnmarshalYAML(node *yaml.Node) error {
+	switch node.Kind {
+
+	case yaml.ScalarNode:
+		var cmd string
+		if err := node.Decode(&cmd); err != nil {
+			return errors.NewTaskfileDecodeError(err, node)
+		}
+		d.Cmd = cmd
+		return nil
+
+	case yaml.MappingNode:
+		var deferStruct struct {
+			Defer  string
+			Task   string
+			Vars   *Vars
+			Silent bool
+		}
+		if err := node.Decode(&deferStruct); err != nil {
+			return errors.NewTaskfileDecodeError(err, node)
+		}
+		d.Cmd = deferStruct.Defer
+		d.Task = deferStruct.Task
+		d.Vars = deferStruct.Vars
+		d.Silent = deferStruct.Silent
+		return nil
+	}
+
+	return errors.NewTaskfileDecodeError(nil, node).WithTypeMessage("defer")
+}

taskfile/ast/graph.go

@@ -116,14 +116,5 @@ func (tfg *TaskfileGraph) Merge() (*Taskfile, error) {
 		return nil, err
 	}
 
-	_ = rootVertex.Taskfile.Tasks.Range(func(name string, task *Task) error {
-		if task == nil {
-			task = &Task{}
-			rootVertex.Taskfile.Tasks.Set(name, task)
-		}
-		task.Task = name
-		return nil
-	})
-
 	return rootVertex.Taskfile, nil
 }

taskfile/ast/include.go

@@ -1,9 +1,10 @@
 package ast
 
 import (
+	"iter"
 	"sync"
 
-	"github.com/elliotchance/orderedmap/v2"
+	"github.com/elliotchance/orderedmap/v3"
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
@@ -84,19 +85,31 @@ func (includes *Includes) Set(key string, value *Include) bool {
 	return includes.om.Set(key, value)
 }
 
+// All returns an iterator that loops over all task key-value pairs.
 // Range calls the provided function for each include in the map. The function
 // receives the include's key and value as arguments. If the function returns
 // an error, the iteration stops and the error is returned.
-func (includes *Includes) Range(f func(k string, v *Include) error) error {
+func (includes *Includes) All() iter.Seq2[string, *Include] {
 	if includes == nil || includes.om == nil {
-		return nil
+		return func(yield func(string, *Include) bool) {}
 	}
-	for pair := includes.om.Front(); pair != nil; pair = pair.Next() {
-		if err := f(pair.Key, pair.Value); err != nil {
-			return err
-		}
+	return includes.om.AllFromFront()
+}
+
+// Keys returns an iterator that loops over all task keys.
+func (includes *Includes) Keys() iter.Seq[string] {
+	if includes == nil || includes.om == nil {
+		return func(yield func(string) bool) {}
 	}
-	return nil
+	return includes.om.Keys()
+}
+
+// Values returns an iterator that loops over all task values.
+func (includes *Includes) Values() iter.Seq[*Include] {
+	if includes == nil || includes.om == nil {
+		return func(yield func(*Include) bool) {}
+	}
+	return includes.om.Values()
 }
 
 // UnmarshalYAML implements the yaml.Unmarshaler interface.

taskfile/ast/matrix.go

@@ -1,22 +1,34 @@
 package ast
 
 import (
-	"github.com/elliotchance/orderedmap/v2"
+	"iter"
+
+	"github.com/elliotchance/orderedmap/v3"
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/deepcopy"
 )
 
-type Matrix struct {
-	om *orderedmap.OrderedMap[string, []any]
-}
-
-type MatrixElement orderedmap.Element[string, []any]
+type (
+	// Matrix is an ordered map of variable names to arrays of values.
+	Matrix struct {
+		om *orderedmap.OrderedMap[string, *MatrixRow]
+	}
+	// A MatrixElement is a key-value pair that is used for initializing a
+	// Matrix structure.
+	MatrixElement orderedmap.Element[string, *MatrixRow]
+	// A MatrixRow list of values for a matrix key or a reference to another
+	// variable.
+	MatrixRow struct {
+		Ref   string
+		Value []any
+	}
+)
 
 func NewMatrix(els ...*MatrixElement) *Matrix {
 	matrix := &Matrix{
-		om: orderedmap.NewOrderedMap[string, []any](),
+		om: orderedmap.NewOrderedMap[string, *MatrixRow](),
 	}
 	for _, el := range els {
 		matrix.Set(el.Key, el.Value)
@@ -31,33 +43,45 @@ func (matrix *Matrix) Len() int {
 	return matrix.om.Len()
 }
 
-func (matrix *Matrix) Get(key string) ([]any, bool) {
+func (matrix *Matrix) Get(key string) (*MatrixRow, bool) {
 	if matrix == nil || matrix.om == nil {
 		return nil, false
 	}
 	return matrix.om.Get(key)
 }
 
-func (matrix *Matrix) Set(key string, value []any) bool {
+func (matrix *Matrix) Set(key string, value *MatrixRow) bool {
 	if matrix == nil {
 		matrix = NewMatrix()
 	}
 	if matrix.om == nil {
-		matrix.om = orderedmap.NewOrderedMap[string, []any]()
+		matrix.om = orderedmap.NewOrderedMap[string, *MatrixRow]()
 	}
 	return matrix.om.Set(key, value)
 }
 
-func (matrix *Matrix) Range(f func(k string, v []any) error) error {
+// All returns an iterator that loops over all task key-value pairs.
+func (matrix *Matrix) All() iter.Seq2[string, *MatrixRow] {
 	if matrix == nil || matrix.om == nil {
-		return nil
+		return func(yield func(string, *MatrixRow) bool) {}
 	}
-	for pair := matrix.om.Front(); pair != nil; pair = pair.Next() {
-		if err := f(pair.Key, pair.Value); err != nil {
-			return err
-		}
+	return matrix.om.AllFromFront()
+}
+
+// Keys returns an iterator that loops over all task keys.
+func (matrix *Matrix) Keys() iter.Seq[string] {
+	if matrix == nil || matrix.om == nil {
+		return func(yield func(string) bool) {}
 	}
-	return nil
+	return matrix.om.Keys()
+}
+
+// Values returns an iterator that loops over all task values.
+func (matrix *Matrix) Values() iter.Seq[*MatrixRow] {
+	if matrix == nil || matrix.om == nil {
+		return func(yield func(*MatrixRow) bool) {}
+	}
+	return matrix.om.Values()
 }
 
 func (matrix *Matrix) DeepCopy() *Matrix {
@@ -79,14 +103,36 @@ func (matrix *Matrix) UnmarshalYAML(node *yaml.Node) error {
 			keyNode := node.Content[i]
 			valueNode := node.Content[i+1]
 
-			// Decode the value node into a Matrix struct
-			var v []any
-			if err := valueNode.Decode(&v); err != nil {
-				return errors.NewTaskfileDecodeError(err, node)
-			}
+			switch valueNode.Kind {
+			case yaml.SequenceNode:
+				// Decode the value node into a Matrix struct
+				var v []any
+				if err := valueNode.Decode(&v); err != nil {
+					return errors.NewTaskfileDecodeError(err, node)
+				}
 
-			// Add the task to the ordered map
-			matrix.Set(keyNode.Value, v)
+				// Add the row to the ordered map
+				matrix.Set(keyNode.Value, &MatrixRow{
+					Value: v,
+				})
+
+			case yaml.MappingNode:
+				// Decode the value node into a Matrix struct
+				var refStruct struct {
+					Ref string
+				}
+				if err := valueNode.Decode(&refStruct); err != nil {
+					return errors.NewTaskfileDecodeError(err, node)
+				}
+
+				// Add the reference to the ordered map
+				matrix.Set(keyNode.Value, &MatrixRow{
+					Ref: refStruct.Ref,
+				})
+
+			default:
+				return errors.NewTaskfileDecodeError(nil, node).WithMessage("matrix values must be an array or a reference")
+			}
 		}
 		return nil
 	}

taskfile/ast/tasks.go

@@ -2,15 +2,17 @@ package ast
 
 import (
 	"fmt"
+	"iter"
 	"slices"
 	"strings"
 	"sync"
 
-	"github.com/elliotchance/orderedmap/v2"
+	"github.com/elliotchance/orderedmap/v3"
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/filepathext"
+	"github.com/go-task/task/v3/internal/sort"
 )
 
 type (
@@ -22,12 +24,6 @@ type (
 	// A TaskElement is a key-value pair that is used for initializing a Tasks
 	// structure.
 	TaskElement orderedmap.Element[string, *Task]
-	// MatchingTask represents a task that matches a given call. It includes the
-	// task itself and a list of wildcards that were matched.
-	MatchingTask struct {
-		Task      *Task
-		Wildcards []string
-	}
 )
 
 // NewTasks creates a new instance of Tasks and initializes it with the provided
@@ -79,81 +75,53 @@ func (tasks *Tasks) Set(key string, value *Task) bool {
 	return tasks.om.Set(key, value)
 }
 
-// Range calls the provided function for each task in the map. The function
-// receives the task's key and value as arguments. If the function returns an
-// error, the iteration stops and the error is returned.
-func (tasks *Tasks) Range(f func(k string, v *Task) error) error {
-	if tasks == nil || tasks.om == nil {
-		return nil
+// All returns an iterator that loops over all task key-value pairs in the order
+// specified by the sorter.
+func (t *Tasks) All(sorter sort.Sorter) iter.Seq2[string, *Task] {
+	if t == nil || t.om == nil {
+		return func(yield func(string, *Task) bool) {}
 	}
-	for pair := tasks.om.Front(); pair != nil; pair = pair.Next() {
-		if err := f(pair.Key, pair.Value); err != nil {
-			return err
+	if sorter == nil {
+		return t.om.AllFromFront()
+	}
+	return func(yield func(string, *Task) bool) {
+		for _, key := range sorter(slices.Collect(t.om.Keys()), nil) {
+			el := t.om.GetElement(key)
+			if !yield(el.Key, el.Value) {
+				return
+			}
 		}
 	}
-	return nil
 }
 
-// Keys returns a slice of all the keys in the Tasks map.
-func (tasks *Tasks) Keys() []string {
-	if tasks == nil {
-		return nil
-	}
-	defer tasks.mutex.RUnlock()
-	tasks.mutex.RLock()
-	var keys []string
-	for pair := tasks.om.Front(); pair != nil; pair = pair.Next() {
-		keys = append(keys, pair.Key)
-	}
-	return keys
-}
-
-// Values returns a slice of all the values in the Tasks map.
-func (tasks *Tasks) Values() []*Task {
-	if tasks == nil {
-		return nil
-	}
-	defer tasks.mutex.RUnlock()
-	tasks.mutex.RLock()
-	var values []*Task
-	for pair := tasks.om.Front(); pair != nil; pair = pair.Next() {
-		values = append(values, pair.Value)
-	}
-	return values
-}
-
-// FindMatchingTasks returns a list of tasks that match the given call. A task
-// matches a call if its name is equal to the call's task name or if it matches
-// a wildcard pattern. The function returns a list of MatchingTask structs, each
-// containing a task and a list of wildcards that were matched.
-func (t *Tasks) FindMatchingTasks(call *Call) []*MatchingTask {
-	if call == nil {
-		return nil
-	}
-	var matchingTasks []*MatchingTask
-	// If there is a direct match, return it
-	if task, ok := t.Get(call.Task); ok {
-		matchingTasks = append(matchingTasks, &MatchingTask{Task: task, Wildcards: nil})
-		return matchingTasks
-	}
-	// Attempt a wildcard match
-	// For now, we can just nil check the task before each loop
-	_ = t.Range(func(key string, value *Task) error {
-		if match, wildcards := value.WildcardMatch(call.Task); match {
-			matchingTasks = append(matchingTasks, &MatchingTask{
-				Task:      value,
-				Wildcards: wildcards,
-			})
+// Keys returns an iterator that loops over all task keys in the order specified
+// by the sorter.
+func (t *Tasks) Keys(sorter sort.Sorter) iter.Seq[string] {
+	return func(yield func(string) bool) {
+		for k := range t.All(sorter) {
+			if !yield(k) {
+				return
+			}
 		}
-		return nil
-	})
-	return matchingTasks
+	}
+}
+
+// Values returns an iterator that loops over all task values in the order
+// specified by the sorter.
+func (t *Tasks) Values(sorter sort.Sorter) iter.Seq[*Task] {
+	return func(yield func(*Task) bool) {
+		for _, v := range t.All(sorter) {
+			if !yield(v) {
+				return
+			}
+		}
+	}
 }
 
 func (t1 *Tasks) Merge(t2 *Tasks, include *Include, includedTaskfileVars *Vars) error {
 	defer t2.mutex.RUnlock()
 	t2.mutex.RLock()
-	err := t2.Range(func(name string, v *Task) error {
+	for name, v := range t2.All(nil) {
 		// We do a deep copy of the task struct here to ensure that no data can
 		// be changed elsewhere once the taskfile is merged.
 		task := v.DeepCopy()
@@ -162,9 +130,9 @@ func (t1 *Tasks) Merge(t2 *Tasks, include *Include, includedTaskfileVars *Vars)
 		task.Internal = task.Internal || (include != nil && include.Internal)
 		taskName := name
 
-		// if the task is in the exclude list, don't add it to the merged taskfile and early return
+		// if the task is in the exclude list, don't add it to the merged taskfile
 		if slices.Contains(include.Excludes, name) {
-			return nil
+			continue
 		}
 
 		if !include.Flatten {
@@ -219,9 +187,7 @@ func (t1 *Tasks) Merge(t2 *Tasks, include *Include, includedTaskfileVars *Vars)
 		}
 		// Add the task to the merged taskfile
 		t1.Set(taskName, task)
-
-		return nil
-	})
+	}
 
 	// If the included Taskfile has a default task, is not flattened and the
 	// parent namespace has no task with a matching name, we can add an alias so
@@ -239,7 +205,7 @@ func (t1 *Tasks) Merge(t2 *Tasks, include *Include, includedTaskfileVars *Vars)
 		}
 	}
 
-	return err
+	return nil
 }
 
 func (t *Tasks) UnmarshalYAML(node *yaml.Node) error {

taskfile/ast/var.go

@@ -2,169 +2,13 @@ package ast
 
 import (
 	"strings"
-	"sync"
 
-	"github.com/elliotchance/orderedmap/v2"
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
-	"github.com/go-task/task/v3/internal/deepcopy"
 	"github.com/go-task/task/v3/internal/experiments"
 )
 
-type (
-	// Vars is an ordered map of variable names to values.
-	Vars struct {
-		om    *orderedmap.OrderedMap[string, Var]
-		mutex sync.RWMutex
-	}
-	// A VarElement is a key-value pair that is used for initializing a Vars
-	// structure.
-	VarElement orderedmap.Element[string, Var]
-)
-
-// NewVars creates a new instance of Vars and initializes it with the provided
-// set of elements, if any. The elements are added in the order they are passed.
-func NewVars(els ...*VarElement) *Vars {
-	vars := &Vars{
-		om: orderedmap.NewOrderedMap[string, Var](),
-	}
-	for _, el := range els {
-		vars.Set(el.Key, el.Value)
-	}
-	return vars
-}
-
-// Len returns the number of variables in the Vars map.
-func (vars *Vars) Len() int {
-	if vars == nil || vars.om == nil {
-		return 0
-	}
-	defer vars.mutex.RUnlock()
-	vars.mutex.RLock()
-	return vars.om.Len()
-}
-
-// Get returns the value the the variable with the provided key and a boolean
-// that indicates if the value was found or not. If the value is not found, the
-// returned variable is a zero value and the bool is false.
-func (vars *Vars) Get(key string) (Var, bool) {
-	if vars == nil || vars.om == nil {
-		return Var{}, false
-	}
-	defer vars.mutex.RUnlock()
-	vars.mutex.RLock()
-	return vars.om.Get(key)
-}
-
-// Set sets the value of the variable with the provided key to the provided
-// value. If the variable already exists, its value is updated. If the variable
-// does not exist, it is created.
-func (vars *Vars) Set(key string, value Var) bool {
-	if vars == nil {
-		vars = NewVars()
-	}
-	if vars.om == nil {
-		vars.om = orderedmap.NewOrderedMap[string, Var]()
-	}
-	defer vars.mutex.Unlock()
-	vars.mutex.Lock()
-	return vars.om.Set(key, value)
-}
-
-// Range calls the provided function for each variable in the map. The function
-// receives the variable's key and value as arguments. If the function returns
-// an error, the iteration stops and the error is returned.
-func (vars *Vars) Range(f func(k string, v Var) error) error {
-	if vars == nil || vars.om == nil {
-		return nil
-	}
-	for pair := vars.om.Front(); pair != nil; pair = pair.Next() {
-		if err := f(pair.Key, pair.Value); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// ToCacheMap converts Vars to an unordered map containing only the static
-// variables
-func (vars *Vars) ToCacheMap() (m map[string]any) {
-	defer vars.mutex.RUnlock()
-	vars.mutex.RLock()
-	m = make(map[string]any, vars.Len())
-	for pair := vars.om.Front(); pair != nil; pair = pair.Next() {
-		if pair.Value.Sh != nil && *pair.Value.Sh != "" {
-			// Dynamic variable is not yet resolved; trigger
-			// <no value> to be used in templates.
-			return nil
-		}
-		if pair.Value.Live != nil {
-			m[pair.Key] = pair.Value.Live
-		} else {
-			m[pair.Key] = pair.Value.Value
-		}
-	}
-	return
-}
-
-// Merge loops over other and merges it values with the variables in vars. If
-// the include parameter is not nil and its it is an advanced import, the
-// directory is set set to the value of the include parameter.
-func (vars *Vars) Merge(other *Vars, include *Include) {
-	if vars == nil || vars.om == nil || other == nil {
-		return
-	}
-	defer other.mutex.RUnlock()
-	other.mutex.RLock()
-	for pair := other.om.Front(); pair != nil; pair = pair.Next() {
-		if include != nil && include.AdvancedImport {
-			pair.Value.Dir = include.Dir
-		}
-		vars.om.Set(pair.Key, pair.Value)
-	}
-}
-
-func (vs *Vars) DeepCopy() *Vars {
-	if vs == nil {
-		return nil
-	}
-	defer vs.mutex.RUnlock()
-	vs.mutex.RLock()
-	return &Vars{
-		om: deepcopy.OrderedMap(vs.om),
-	}
-}
-
-func (vs *Vars) UnmarshalYAML(node *yaml.Node) error {
-	if vs == nil || vs.om == nil {
-		*vs = *NewVars()
-	}
-	vs.om = orderedmap.NewOrderedMap[string, Var]()
-	switch node.Kind {
-	case yaml.MappingNode:
-		// NOTE: orderedmap does not have an unmarshaler, so we have to decode
-		// the map manually. We increment over 2 values at a time and assign
-		// them as a key-value pair.
-		for i := 0; i < len(node.Content); i += 2 {
-			keyNode := node.Content[i]
-			valueNode := node.Content[i+1]
-
-			// Decode the value node into a Task struct
-			var v Var
-			if err := valueNode.Decode(&v); err != nil {
-				return errors.NewTaskfileDecodeError(err, node)
-			}
-
-			// Add the task to the ordered map
-			vs.Set(keyNode.Value, v)
-		}
-		return nil
-	}
-
-	return errors.NewTaskfileDecodeError(nil, node).WithTypeMessage("vars")
-}
-
 // Var represents either a static or dynamic variable.
 type Var struct {
 	Value any
@@ -178,7 +22,7 @@ func (v *Var) UnmarshalYAML(node *yaml.Node) error {
 	if experiments.MapVariables.Enabled() {
 
 		// This implementation is not backwards-compatible and replaces the 'sh' key with map variables
-		if experiments.MapVariables.Value == "1" {
+		if experiments.MapVariables.Value == 1 {
 			var value any
 			if err := node.Decode(&value); err != nil {
 				return errors.NewTaskfileDecodeError(err, node)
@@ -199,7 +43,7 @@ func (v *Var) UnmarshalYAML(node *yaml.Node) error {
 		}
 
 		// This implementation IS backwards-compatible and keeps the 'sh' key and allows map variables to be added under the `map` key
-		if experiments.MapVariables.Value == "2" {
+		if experiments.MapVariables.Value == 2 {
 			switch node.Kind {
 			case yaml.MappingNode:
 				key := node.Content[0].Value

taskfile/ast/vars.go

@@ -0,0 +1,174 @@
+package ast
+
+import (
+	"iter"
+	"sync"
+
+	"github.com/elliotchance/orderedmap/v3"
+	"gopkg.in/yaml.v3"
+
+	"github.com/go-task/task/v3/errors"
+	"github.com/go-task/task/v3/internal/deepcopy"
+)
+
+type (
+	// Vars is an ordered map of variable names to values.
+	Vars struct {
+		om    *orderedmap.OrderedMap[string, Var]
+		mutex sync.RWMutex
+	}
+	// A VarElement is a key-value pair that is used for initializing a Vars
+	// structure.
+	VarElement orderedmap.Element[string, Var]
+)
+
+// NewVars creates a new instance of Vars and initializes it with the provided
+// set of elements, if any. The elements are added in the order they are passed.
+func NewVars(els ...*VarElement) *Vars {
+	vars := &Vars{
+		om: orderedmap.NewOrderedMap[string, Var](),
+	}
+	for _, el := range els {
+		vars.Set(el.Key, el.Value)
+	}
+	return vars
+}
+
+// Len returns the number of variables in the Vars map.
+func (vars *Vars) Len() int {
+	if vars == nil || vars.om == nil {
+		return 0
+	}
+	defer vars.mutex.RUnlock()
+	vars.mutex.RLock()
+	return vars.om.Len()
+}
+
+// Get returns the value the the variable with the provided key and a boolean
+// that indicates if the value was found or not. If the value is not found, the
+// returned variable is a zero value and the bool is false.
+func (vars *Vars) Get(key string) (Var, bool) {
+	if vars == nil || vars.om == nil {
+		return Var{}, false
+	}
+	defer vars.mutex.RUnlock()
+	vars.mutex.RLock()
+	return vars.om.Get(key)
+}
+
+// Set sets the value of the variable with the provided key to the provided
+// value. If the variable already exists, its value is updated. If the variable
+// does not exist, it is created.
+func (vars *Vars) Set(key string, value Var) bool {
+	if vars == nil {
+		vars = NewVars()
+	}
+	if vars.om == nil {
+		vars.om = orderedmap.NewOrderedMap[string, Var]()
+	}
+	defer vars.mutex.Unlock()
+	vars.mutex.Lock()
+	return vars.om.Set(key, value)
+}
+
+// All returns an iterator that loops over all task key-value pairs.
+func (vars *Vars) All() iter.Seq2[string, Var] {
+	if vars == nil || vars.om == nil {
+		return func(yield func(string, Var) bool) {}
+	}
+	return vars.om.AllFromFront()
+}
+
+// Keys returns an iterator that loops over all task keys.
+func (vars *Vars) Keys() iter.Seq[string] {
+	if vars == nil || vars.om == nil {
+		return func(yield func(string) bool) {}
+	}
+	return vars.om.Keys()
+}
+
+// Values returns an iterator that loops over all task values.
+func (vars *Vars) Values() iter.Seq[Var] {
+	if vars == nil || vars.om == nil {
+		return func(yield func(Var) bool) {}
+	}
+	return vars.om.Values()
+}
+
+// ToCacheMap converts Vars to an unordered map containing only the static
+// variables
+func (vars *Vars) ToCacheMap() (m map[string]any) {
+	defer vars.mutex.RUnlock()
+	vars.mutex.RLock()
+	m = make(map[string]any, vars.Len())
+	for k, v := range vars.All() {
+		if v.Sh != nil && *v.Sh != "" {
+			// Dynamic variable is not yet resolved; trigger
+			// <no value> to be used in templates.
+			continue
+		}
+		if v.Live != nil {
+			m[k] = v.Live
+		} else {
+			m[k] = v.Value
+		}
+	}
+	return
+}
+
+// Merge loops over other and merges it values with the variables in vars. If
+// the include parameter is not nil and its it is an advanced import, the
+// directory is set set to the value of the include parameter.
+func (vars *Vars) Merge(other *Vars, include *Include) {
+	if vars == nil || vars.om == nil || other == nil {
+		return
+	}
+	defer other.mutex.RUnlock()
+	other.mutex.RLock()
+	for pair := other.om.Front(); pair != nil; pair = pair.Next() {
+		if include != nil && include.AdvancedImport {
+			pair.Value.Dir = include.Dir
+		}
+		vars.om.Set(pair.Key, pair.Value)
+	}
+}
+
+func (vs *Vars) DeepCopy() *Vars {
+	if vs == nil {
+		return nil
+	}
+	defer vs.mutex.RUnlock()
+	vs.mutex.RLock()
+	return &Vars{
+		om: deepcopy.OrderedMap(vs.om),
+	}
+}
+
+func (vs *Vars) UnmarshalYAML(node *yaml.Node) error {
+	if vs == nil || vs.om == nil {
+		*vs = *NewVars()
+	}
+	vs.om = orderedmap.NewOrderedMap[string, Var]()
+	switch node.Kind {
+	case yaml.MappingNode:
+		// NOTE: orderedmap does not have an unmarshaler, so we have to decode
+		// the map manually. We increment over 2 values at a time and assign
+		// them as a key-value pair.
+		for i := 0; i < len(node.Content); i += 2 {
+			keyNode := node.Content[i]
+			valueNode := node.Content[i+1]
+
+			// Decode the value node into a Task struct
+			var v Var
+			if err := valueNode.Decode(&v); err != nil {
+				return errors.NewTaskfileDecodeError(err, node)
+			}
+
+			// Add the task to the ordered map
+			vs.Set(keyNode.Value, v)
+		}
+		return nil
+	}
+
+	return errors.NewTaskfileDecodeError(nil, node).WithTypeMessage("vars")
+}

taskfile/dotenv.go

@@ -6,22 +6,12 @@ import (
 
 	"github.com/joho/godotenv"
 
-	"github.com/go-task/task/v3/internal/compiler"
 	"github.com/go-task/task/v3/internal/filepathext"
 	"github.com/go-task/task/v3/internal/templater"
 	"github.com/go-task/task/v3/taskfile/ast"
 )
 
-func Dotenv(c *compiler.Compiler, tf *ast.Taskfile, dir string) (*ast.Vars, error) {
-	if len(tf.Dotenv) == 0 {
-		return nil, nil
-	}
-
-	vars, err := c.GetTaskfileVariables()
-	if err != nil {
-		return nil, err
-	}
-
+func Dotenv(vars *ast.Vars, tf *ast.Taskfile, dir string) (*ast.Vars, error) {
 	env := ast.NewVars()
 	cache := &templater.Cache{Vars: vars}
 

taskfile/node.go

@@ -11,7 +11,6 @@ import (
 
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/experiments"
-	"github.com/go-task/task/v3/internal/logger"
 )
 
 type Node interface {
@@ -26,7 +25,6 @@ type Node interface {
 }
 
 func NewRootNode(
-	l *logger.Logger,
 	entrypoint string,
 	dir string,
 	insecure bool,
@@ -37,11 +35,10 @@ func NewRootNode(
 	if entrypoint == "-" {
 		return NewStdinNode(dir)
 	}
-	return NewNode(l, entrypoint, dir, insecure, timeout)
+	return NewNode(entrypoint, dir, insecure, timeout)
 }
 
 func NewNode(
-	l *logger.Logger,
 	entrypoint string,
 	dir string,
 	insecure bool,
@@ -58,9 +55,9 @@ func NewNode(
 	case "git":
 		node, err = NewGitNode(entrypoint, dir, insecure, opts...)
 	case "http", "https":
-		node, err = NewHTTPNode(l, entrypoint, dir, insecure, timeout, opts...)
+		node, err = NewHTTPNode(entrypoint, dir, insecure, timeout, opts...)
 	default:
-		node, err = NewFileNode(l, entrypoint, dir, opts...)
+		node, err = NewFileNode(entrypoint, dir, opts...)
 
 	}
 

taskfile/node_file.go

@@ -9,7 +9,6 @@ import (
 
 	"github.com/go-task/task/v3/internal/execext"
 	"github.com/go-task/task/v3/internal/filepathext"
-	"github.com/go-task/task/v3/internal/logger"
 )
 
 // A FileNode is a node that reads a taskfile from the local filesystem.
@@ -18,10 +17,10 @@ type FileNode struct {
 	Entrypoint string
 }
 
-func NewFileNode(l *logger.Logger, entrypoint, dir string, opts ...NodeOption) (*FileNode, error) {
+func NewFileNode(entrypoint, dir string, opts ...NodeOption) (*FileNode, error) {
 	var err error
 	base := NewBaseNode(dir, opts...)
-	entrypoint, base.dir, err = resolveFileNodeEntrypointAndDir(l, entrypoint, base.dir)
+	entrypoint, base.dir, err = resolveFileNodeEntrypointAndDir(entrypoint, base.dir)
 	if err != nil {
 		return nil, err
 	}
@@ -50,10 +49,10 @@ func (node *FileNode) Read(ctx context.Context) ([]byte, error) {
 
 // resolveFileNodeEntrypointAndDir resolves checks the values of entrypoint and dir and
 // populates them with default values if necessary.
-func resolveFileNodeEntrypointAndDir(l *logger.Logger, entrypoint, dir string) (string, string, error) {
+func resolveFileNodeEntrypointAndDir(entrypoint, dir string) (string, string, error) {
 	var err error
 	if entrypoint != "" {
-		entrypoint, err = Exists(l, entrypoint)
+		entrypoint, err = Exists(entrypoint)
 		if err != nil {
 			return "", "", err
 		}
@@ -68,7 +67,7 @@ func resolveFileNodeEntrypointAndDir(l *logger.Logger, entrypoint, dir string) (
 			return "", "", err
 		}
 	}
-	entrypoint, err = ExistsWalk(l, dir)
+	entrypoint, err = ExistsWalk(dir)
 	if err != nil {
 		return "", "", err
 	}

taskfile/node_http.go

@@ -11,7 +11,6 @@ import (
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/execext"
 	"github.com/go-task/task/v3/internal/filepathext"
-	"github.com/go-task/task/v3/internal/logger"
 )
 
 // An HTTPNode is a node that reads a Taskfile from a remote location via HTTP.
@@ -19,12 +18,10 @@ type HTTPNode struct {
 	*BaseNode
 	URL        *url.URL // stores url pointing actual remote file. (e.g. with Taskfile.yml)
 	entrypoint string   // stores entrypoint url. used for building graph vertices.
-	logger     *logger.Logger
 	timeout    time.Duration
 }
 
 func NewHTTPNode(
-	l *logger.Logger,
 	entrypoint string,
 	dir string,
 	insecure bool,
@@ -45,7 +42,6 @@ func NewHTTPNode(
 		URL:        url,
 		entrypoint: entrypoint,
 		timeout:    timeout,
-		logger:     l,
 	}, nil
 }
 
@@ -58,7 +54,7 @@ func (node *HTTPNode) Remote() bool {
 }
 
 func (node *HTTPNode) Read(ctx context.Context) ([]byte, error) {
-	url, err := RemoteExists(ctx, node.logger, node.URL, node.timeout)
+	url, err := RemoteExists(ctx, node.URL, node.timeout)
 	if err != nil {
 		return nil, err
 	}

taskfile/reader.go

@@ -12,9 +12,8 @@ import (
 	"gopkg.in/yaml.v3"
 
 	"github.com/go-task/task/v3/errors"
-	"github.com/go-task/task/v3/internal/compiler"
+	"github.com/go-task/task/v3/internal/env"
 	"github.com/go-task/task/v3/internal/filepathext"
-	"github.com/go-task/task/v3/internal/logger"
 	"github.com/go-task/task/v3/internal/templater"
 	"github.com/go-task/task/v3/taskfile/ast"
 )
@@ -28,40 +27,115 @@ Continue?`
 Continue?`
 )
 
-// A Reader will recursively read Taskfiles from a given source using a directed
-// acyclic graph (DAG).
-type Reader struct {
-	graph       *ast.TaskfileGraph
-	node        Node
-	insecure    bool
-	download    bool
-	offline     bool
-	timeout     time.Duration
-	tempDir     string
-	logger      *logger.Logger
-	promptMutex sync.Mutex
-}
+type (
+	// ReaderDebugFunc is a function that is called when the reader wants to
+	// log debug messages
+	ReaderDebugFunc func(string)
+	// ReaderPromptFunc is a function that is called when the reader wants to
+	// prompt the user in some way
+	ReaderPromptFunc func(string) error
+	// ReaderOption is a function that configures a Reader.
+	ReaderOption func(*Reader)
+	// A Reader will recursively read Taskfiles from a given source using a directed
+	// acyclic graph (DAG).
+	Reader struct {
+		graph       *ast.TaskfileGraph
+		node        Node
+		insecure    bool
+		download    bool
+		offline     bool
+		timeout     time.Duration
+		tempDir     string
+		debugFunc   ReaderDebugFunc
+		promptFunc  ReaderPromptFunc
+		promptMutex sync.Mutex
+	}
+)
 
+// NewReader constructs a new Taskfile Reader using the given Node and options.
 func NewReader(
 	node Node,
-	insecure bool,
-	download bool,
-	offline bool,
-	timeout time.Duration,
-	tempDir string,
-	logger *logger.Logger,
+	opts ...ReaderOption,
 ) *Reader {
-	return &Reader{
+	reader := &Reader{
 		graph:       ast.NewTaskfileGraph(),
 		node:        node,
-		insecure:    insecure,
-		download:    download,
-		offline:     offline,
-		timeout:     timeout,
-		tempDir:     tempDir,
-		logger:      logger,
+		insecure:    false,
+		download:    false,
+		offline:     false,
+		timeout:     time.Second * 10,
+		tempDir:     os.TempDir(),
+		debugFunc:   nil,
+		promptFunc:  nil,
 		promptMutex: sync.Mutex{},
 	}
+	for _, opt := range opts {
+		opt(reader)
+	}
+	return reader
+}
+
+// WithInsecure enables insecure connections when reading remote taskfiles. By
+// default, insecure connections are rejected.
+func WithInsecure(insecure bool) ReaderOption {
+	return func(r *Reader) {
+		r.insecure = insecure
+	}
+}
+
+// WithDownload forces the reader to download a fresh copy of the taskfile from
+// the remote source.
+func WithDownload(download bool) ReaderOption {
+	return func(r *Reader) {
+		r.download = download
+	}
+}
+
+// WithOffline stops the reader from being able to make network connections.
+// It will still be able to read local files and cached copies of remote files.
+func WithOffline(offline bool) ReaderOption {
+	return func(r *Reader) {
+		r.offline = offline
+	}
+}
+
+// WithTimeout sets the timeout for reading remote taskfiles. By default, the
+// timeout is set to 10 seconds.
+func WithTimeout(timeout time.Duration) ReaderOption {
+	return func(r *Reader) {
+		r.timeout = timeout
+	}
+}
+
+// WithTempDir sets the temporary directory to be used by the reader. By
+// default, the reader uses `os.TempDir()`.
+func WithTempDir(tempDir string) ReaderOption {
+	return func(r *Reader) {
+		r.tempDir = tempDir
+	}
+}
+
+// WithDebugFunc sets the debug function to be used by the reader. If set, this
+// function will be called with debug messages. This can be useful if the caller
+// wants to log debug messages from the reader. By default, no debug function is
+// set and the logs are not written.
+func WithDebugFunc(debugFunc ReaderDebugFunc) ReaderOption {
+	return func(r *Reader) {
+		r.debugFunc = debugFunc
+	}
+}
+
+// WithPromptFunc sets the prompt function to be used by the reader. If set,
+// this function will be called with prompt messages. The function should
+// optionally log the message to the user and return nil if the prompt is
+// accepted and the execution should continue. Otherwise, it should return an
+// error which describes why the the prompt was rejected. This can then be
+// caught and used later when calling the Read method. By default, no prompt
+// function is set and all prompts are automatically accepted.
+func WithPromptFunc(promptFunc ReaderPromptFunc) ReaderOption {
+	return func(r *Reader) {
+		r.promptFunc = promptFunc
+	}
 }
 
 func (r *Reader) Read() (*ast.TaskfileGraph, error) {
@@ -73,6 +147,19 @@ func (r *Reader) Read() (*ast.TaskfileGraph, error) {
 	return r.graph, nil
 }
 
+func (r *Reader) debugf(format string, a ...any) {
+	if r.debugFunc != nil {
+		r.debugFunc(fmt.Sprintf(format, a...))
+	}
+}
+
+func (r *Reader) promptf(format string, a ...any) error {
+	if r.promptFunc != nil {
+		return r.promptFunc(fmt.Sprintf(format, a...))
+	}
+	return nil
+}
+
 func (r *Reader) include(node Node) error {
 	// Create a new vertex for the Taskfile
 	vertex := &ast.TaskfileVertex{
@@ -100,8 +187,8 @@ func (r *Reader) include(node Node) error {
 	var g errgroup.Group
 
 	// Loop over each included taskfile
-	_ = vertex.Taskfile.Includes.Range(func(namespace string, include *ast.Include) error {
-		vars := compiler.GetEnviron()
+	for _, include := range vertex.Taskfile.Includes.All() {
+		vars := env.GetEnviron()
 		vars.Merge(vertex.Taskfile.Vars, nil)
 		// Start a goroutine to process each included Taskfile
 		g.Go(func() error {
@@ -132,7 +219,7 @@ func (r *Reader) include(node Node) error {
 				return err
 			}
 
-			includeNode, err := NewNode(r.logger, entrypoint, include.Dir, r.insecure, r.timeout,
+			includeNode, err := NewNode(entrypoint, include.Dir, r.insecure, r.timeout,
 				WithParent(node),
 			)
 			if err != nil {
@@ -177,8 +264,7 @@ func (r *Reader) include(node Node) error {
 			}
 			return err
 		})
-		return nil
-	})
+	}
 
 	// Wait for all the go routines to finish
 	return g.Wait()
@@ -193,9 +279,14 @@ func (r *Reader) readNode(node Node) (*ast.Taskfile, error) {
 	var tf ast.Taskfile
 	if err := yaml.Unmarshal(b, &tf); err != nil {
 		// Decode the taskfile and add the file info the any errors
-		taskfileInvalidErr := &errors.TaskfileDecodeError{}
-		if errors.As(err, &taskfileInvalidErr) {
-			return nil, taskfileInvalidErr.WithFileInfo(node.Location(), b, 2)
+		taskfileDecodeErr := &errors.TaskfileDecodeError{}
+		if errors.As(err, &taskfileDecodeErr) {
+			snippet := NewSnippet(b,
+				SnippetWithLine(taskfileDecodeErr.Line),
+				SnippetWithColumn(taskfileDecodeErr.Column),
+				SnippetWithPadding(2),
+			)
+			return nil, taskfileDecodeErr.WithFileInfo(node.Location(), snippet.String())
 		}
 		return nil, &errors.TaskfileInvalidError{URI: filepathext.TryAbsToRel(node.Location()), Err: err}
 	}
@@ -207,7 +298,7 @@ func (r *Reader) readNode(node Node) (*ast.Taskfile, error) {
 
 	// Set the taskfile/task's locations
 	tf.Location = node.Location()
-	for _, task := range tf.Tasks.Values() {
+	for task := range tf.Tasks.Values(nil) {
 		// If the task is not defined, create a new one
 		if task == nil {
 			task = &ast.Task{}
@@ -241,7 +332,7 @@ func (r *Reader) loadNodeContent(node Node) ([]byte, error) {
 		} else if err != nil {
 			return nil, err
 		}
-		r.logger.VerboseOutf(logger.Magenta, "task: [%s] Fetched cached copy\n", node.Location())
+		r.debugf("task: [%s] Fetched cached copy\n", node.Location())
 
 		return cached, nil
 	}
@@ -265,14 +356,14 @@ func (r *Reader) loadNodeContent(node Node) ([]byte, error) {
 		} else if err != nil {
 			return nil, err
 		}
-		r.logger.VerboseOutf(logger.Magenta, "task: [%s] Network timeout. Fetched cached copy\n", node.Location())
+		r.debugf("task: [%s] Network timeout. Fetched cached copy\n", node.Location())
 
 		return cached, nil
 
 	} else if err != nil {
 		return nil, err
 	}
-	r.logger.VerboseOutf(logger.Magenta, "task: [%s] Fetched remote copy\n", node.Location())
+	r.debugf("task: [%s] Fetched remote copy\n", node.Location())
 
 	// Get the checksums
 	checksum := checksum(b)
@@ -281,17 +372,17 @@ func (r *Reader) loadNodeContent(node Node) ([]byte, error) {
 	var prompt string
 	if cachedChecksum == "" {
 		// If the checksum doesn't exist, prompt the user to continue
-		prompt = fmt.Sprintf(taskfileUntrustedPrompt, node.Location())
+		prompt = taskfileUntrustedPrompt
 	} else if checksum != cachedChecksum {
 		// If there is a cached hash, but it doesn't match the expected hash, prompt the user to continue
-		prompt = fmt.Sprintf(taskfileChangedPrompt, node.Location())
+		prompt = taskfileChangedPrompt
 	}
 
 	if prompt != "" {
 		if err := func() error {
 			r.promptMutex.Lock()
 			defer r.promptMutex.Unlock()
-			return r.logger.Prompt(logger.Yellow, prompt, "n", "y", "yes")
+			return r.promptf(prompt, node.Location())
 		}(); err != nil {
 			return nil, &errors.TaskfileNotTrustedError{URI: node.Location()}
 		}
@@ -302,7 +393,7 @@ func (r *Reader) loadNodeContent(node Node) ([]byte, error) {
 		}
 
 		// Cache the file
-		r.logger.VerboseOutf(logger.Magenta, "task: [%s] Caching downloaded file\n", node.Location())
+		r.debugf("task: [%s] Caching downloaded file\n", node.Location())
 		if err = cache.write(node, b); err != nil {
 			return nil, err
 		}

taskfile/snippet.go

@@ -0,0 +1,148 @@
+package taskfile
+
+import (
+	"bytes"
+	"embed"
+	"fmt"
+	"strings"
+
+	"github.com/alecthomas/chroma/v2"
+	"github.com/alecthomas/chroma/v2/quick"
+	"github.com/alecthomas/chroma/v2/styles"
+	"github.com/fatih/color"
+)
+
+//go:embed themes/*.xml
+var embedded embed.FS
+
+const (
+	lineIndicator   = ">"
+	columnIndicator = "^"
+)
+
+func init() {
+	r, err := embedded.Open("themes/task.xml")
+	if err != nil {
+		panic(err)
+	}
+	style, err := chroma.NewXMLStyle(r)
+	if err != nil {
+		panic(err)
+	}
+	styles.Register(style)
+}
+
+type (
+	SnippetOption func(*Snippet)
+	Snippet       struct {
+		linesRaw         []string
+		linesHighlighted []string
+		start            int
+		end              int
+		line             int
+		column           int
+		padding          int
+		noIndicators     bool
+	}
+)
+
+// NewSnippet creates a new snippet from a byte slice and a line and column
+// number. The line and column numbers should be 1-indexed. For example, the
+// first character in the file would be 1:1 (line 1, column 1). The padding
+// determines the number of lines to include before and after the chosen line.
+func NewSnippet(b []byte, opts ...SnippetOption) *Snippet {
+	snippet := &Snippet{}
+	for _, opt := range opts {
+		opt(snippet)
+	}
+
+	// Syntax highlight the input and split it into lines
+	buf := &bytes.Buffer{}
+	if err := quick.Highlight(buf, string(b), "yaml", "terminal", "task"); err != nil {
+		buf.Write(b)
+	}
+	linesRaw := strings.Split(string(b), "\n")
+	linesHighlighted := strings.Split(buf.String(), "\n")
+
+	// Work out the start and end lines of the snippet
+	snippet.start = max(snippet.line-snippet.padding, 1)
+	snippet.end = min(snippet.line+snippet.padding, len(linesRaw)-1)
+	snippet.linesRaw = linesRaw[snippet.start-1 : snippet.end]
+	snippet.linesHighlighted = linesHighlighted[snippet.start-1 : snippet.end]
+
+	return snippet
+}
+
+func SnippetWithLine(line int) SnippetOption {
+	return func(snippet *Snippet) {
+		snippet.line = line
+	}
+}
+
+func SnippetWithColumn(column int) SnippetOption {
+	return func(snippet *Snippet) {
+		snippet.column = column
+	}
+}
+
+func SnippetWithPadding(padding int) SnippetOption {
+	return func(snippet *Snippet) {
+		snippet.padding = padding
+	}
+}
+
+func SnippetWithNoIndicators() SnippetOption {
+	return func(snippet *Snippet) {
+		snippet.noIndicators = true
+	}
+}
+
+func (snippet *Snippet) String() string {
+	buf := &bytes.Buffer{}
+
+	maxLineNumberDigits := digits(snippet.end)
+	lineNumberFormat := fmt.Sprintf("%%%dd", maxLineNumberDigits)
+	lineNumberSpacer := strings.Repeat(" ", maxLineNumberDigits)
+	lineIndicatorSpacer := strings.Repeat(" ", len(lineIndicator))
+	columnSpacer := strings.Repeat(" ", max(snippet.column-1, 0))
+
+	// Loop over each line in the snippet
+	for i, lineHighlighted := range snippet.linesHighlighted {
+		if i > 0 {
+			fmt.Fprintln(buf)
+		}
+
+		currentLine := snippet.start + i
+		lineNumber := fmt.Sprintf(lineNumberFormat, currentLine)
+
+		// If this is a padding line or indicators are disabled, print it as normal
+		if currentLine != snippet.line || snippet.noIndicators {
+			fmt.Fprintf(buf, "%s %s | %s", lineIndicatorSpacer, lineNumber, lineHighlighted)
+			continue
+		}
+
+		// Otherwise, print the line with indicators
+		fmt.Fprintf(buf, "%s %s | %s", color.RedString(lineIndicator), lineNumber, lineHighlighted)
+
+		// Only print the column indicator if the column is in bounds
+		if snippet.column > 0 && snippet.column <= len(snippet.linesRaw[i]) {
+			fmt.Fprintf(buf, "\n%s %s | %s%s", lineIndicatorSpacer, lineNumberSpacer, columnSpacer, color.RedString(columnIndicator))
+		}
+	}
+
+	// If there are lines, but no line is selected, print the column indicator under all the lines
+	if len(snippet.linesHighlighted) > 0 && snippet.line == 0 && snippet.column > 0 {
+		fmt.Fprintf(buf, "\n%s %s | %s%s", lineIndicatorSpacer, lineNumberSpacer, columnSpacer, color.RedString(columnIndicator))
+	}
+
+	return buf.String()
+}
+
+func digits(number int) int {
+	count := 0
+	for number != 0 {
+		number /= 10
+		count += 1
+	}
+	return count
+}

taskfile/snippet_test.go

@@ -0,0 +1,289 @@
+package taskfile
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+const sample = `version: 3
+
+tasks:
+  default:
+    vars:
+      FOO: foo
+      BAR: bar
+    cmds:
+      - echo "{{.FOO}}"
+      - echo "{{.BAR}}"
+`
+
+func TestNewSnippet(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name string
+		b    []byte
+		opts []SnippetOption
+		want *Snippet
+	}{
+		{
+			name: "first line, first column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(1),
+			},
+			want: &Snippet{
+				linesRaw: []string{
+					"version: 3",
+				},
+				linesHighlighted: []string{
+					"\x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+				},
+				start:   1,
+				end:     1,
+				line:    1,
+				column:  1,
+				padding: 0,
+			},
+		},
+		{
+			name: "first line, first column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(1),
+				SnippetWithPadding(2),
+			},
+			want: &Snippet{
+				linesRaw: []string{
+					"version: 3",
+					"",
+					"tasks:",
+				},
+				linesHighlighted: []string{
+					"\x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+					"\x1b[1m\x1b[30m\x1b[0m",
+					"\x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+				},
+				start:   1,
+				end:     3,
+				line:    1,
+				column:  1,
+				padding: 2,
+			},
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			got := NewSnippet(tt.b, tt.opts...)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}
+
+func TestSnippetString(t *testing.T) {
+	t.Parallel()
+	tests := []struct {
+		name string
+		b    []byte
+		opts []SnippetOption
+		want string
+	}{
+		{
+			name: "empty",
+			b:    []byte{},
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(1),
+			},
+			want: "",
+		},
+		{
+			name: "0th line, 0th column (no indicators)",
+			b:    []byte(sample),
+			want: "",
+		},
+		{
+			name: "1st line, 0th column (line indicator only)",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+			},
+			want: "> 1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "0th line, 1st column (column indicator only)",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithColumn(1),
+			},
+			want: "",
+		},
+		{
+			name: "0th line, 1st column, padding=2 (column indicator only)",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithColumn(1),
+				SnippetWithPadding(2),
+			},
+			want: "  1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  2 | \x1b[1m\x1b[30m\x1b[0m\n    | ^",
+		},
+		{
+			name: "1st line, 1st column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(1),
+			},
+			want: "> 1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    | ^",
+		},
+		{
+			name: "1st line, 10th column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(10),
+			},
+			want: "> 1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    |          ^",
+		},
+		{
+			name: "1st line, 1st column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(1),
+				SnippetWithPadding(2),
+			},
+			want: "> 1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    | ^\n  2 | \x1b[1m\x1b[30m\x1b[0m\n  3 | \x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "1st line, 10th column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(1),
+				SnippetWithColumn(10),
+				SnippetWithPadding(2),
+			},
+			want: "> 1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    |          ^\n  2 | \x1b[1m\x1b[30m\x1b[0m\n  3 | \x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "5th line, 1st column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(5),
+				SnippetWithColumn(1),
+			},
+			want: "> 5 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mvars\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    | ^",
+		},
+		{
+			name: "5th line, 5th column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(5),
+				SnippetWithColumn(5),
+			},
+			want: "> 5 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mvars\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    |     ^",
+		},
+		{
+			name: "5th line, 5th column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(5),
+				SnippetWithColumn(5),
+				SnippetWithPadding(2),
+			},
+			want: "  3 | \x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  4 | \x1b[1m\x1b[30m  \x1b[0m\x1b[33mdefault\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n> 5 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mvars\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n    |     ^\n  6 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mFOO\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mfoo\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  7 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mBAR\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mbar\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "5th line, 5th column, padding=2, no indicators",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(5),
+				SnippetWithColumn(5),
+				SnippetWithPadding(2),
+				SnippetWithNoIndicators(),
+			},
+			want: "  3 | \x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  4 | \x1b[1m\x1b[30m  \x1b[0m\x1b[33mdefault\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  5 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mvars\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  6 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mFOO\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mfoo\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  7 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mBAR\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mbar\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "10th line, 1st column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(10),
+				SnippetWithColumn(1),
+			},
+			want: "> 10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n     | ^",
+		},
+		{
+			name: "10th line, 23rd column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(10),
+				SnippetWithColumn(23),
+			},
+			want: "> 10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n     |                       ^",
+		},
+		{
+			name: "10th line, 24th column (out of bounds)",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(10),
+				SnippetWithColumn(24),
+			},
+			want: "> 10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "10th line, 23rd column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(10),
+				SnippetWithColumn(23),
+				SnippetWithPadding(2),
+			},
+			want: "   8 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mcmds\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   9 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.FOO}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n> 10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n     |                       ^",
+		},
+		{
+			name: "5th line, 5th column, padding=100",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(5),
+				SnippetWithColumn(5),
+				SnippetWithPadding(100),
+			},
+			want: "   1 | \x1b[33mversion\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36m3\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   2 | \x1b[1m\x1b[30m\x1b[0m\n   3 | \x1b[33mtasks\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   4 | \x1b[1m\x1b[30m  \x1b[0m\x1b[33mdefault\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n>  5 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mvars\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n     |     ^\n   6 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mFOO\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mfoo\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   7 | \x1b[1m\x1b[30m      \x1b[0m\x1b[33mBAR\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m \x1b[0m\x1b[36mbar\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   8 | \x1b[1m\x1b[30m    \x1b[0m\x1b[33mcmds\x1b[0m\x1b[1m\x1b[30m:\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n   9 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.FOO}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+		{
+			name: "11th line (out of bounds), 1st column",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(11),
+				SnippetWithColumn(1),
+			},
+			want: "",
+		},
+		{
+			name: "11th line (out of bounds), 1st column, padding=2",
+			b:    []byte(sample),
+			opts: []SnippetOption{
+				SnippetWithLine(11),
+				SnippetWithColumn(1),
+				SnippetWithPadding(2),
+			},
+			want: "   9 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.FOO}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m\n  10 | \x1b[1m\x1b[30m      \x1b[0m\x1b[1m\x1b[30m- \x1b[0m\x1b[36mecho \"{{.BAR}}\"\x1b[0m\x1b[1m\x1b[30m\x1b[0m",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			snippet := NewSnippet(tt.b, tt.opts...)
+			got := snippet.String()
+			if strings.Contains(got, "\t") {
+				t.Fatalf("tab character found in snippet - check the sample string")
+			}
+			require.Equal(t, tt.want, got)
+		})
+	}
+}

taskfile/taskfile.go

@@ -12,7 +12,6 @@ import (
 
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/filepathext"
-	"github.com/go-task/task/v3/internal/logger"
 	"github.com/go-task/task/v3/internal/sysinfo"
 )
 
@@ -41,7 +40,7 @@ var (
 // at the given URL with any of the default Taskfile files names. If any of
 // these match a file, the first matching path will be returned. If no files are
 // found, an error will be returned.
-func RemoteExists(ctx context.Context, l *logger.Logger, u *url.URL, timeout time.Duration) (*url.URL, error) {
+func RemoteExists(ctx context.Context, u *url.URL, timeout time.Duration) (*url.URL, error) {
 	// Create a new HEAD request for the given URL to check if the resource exists
 	req, err := http.NewRequestWithContext(ctx, "HEAD", u.String(), nil)
 	if err != nil {
@@ -89,7 +88,6 @@ func RemoteExists(ctx context.Context, l *logger.Logger, u *url.URL, timeout tim
 
 		// If the request was successful, return the URL
 		if resp.StatusCode == http.StatusOK {
-			l.VerboseOutf(logger.Magenta, "task: [%s] Not found - Using alternative (%s)\n", alt.String(), taskfile)
 			return alt, nil
 		}
 	}
@@ -102,7 +100,7 @@ func RemoteExists(ctx context.Context, l *logger.Logger, u *url.URL, timeout tim
 // given path with any of the default Taskfile files names. If any of these
 // match a file, the first matching path will be returned. If no files are
 // found, an error will be returned.
-func Exists(l *logger.Logger, path string) (string, error) {
+func Exists(path string) (string, error) {
 	fi, err := os.Stat(path)
 	if err != nil {
 		return "", err
@@ -117,7 +115,6 @@ func Exists(l *logger.Logger, path string) (string, error) {
 	for _, taskfile := range defaultTaskfiles {
 		alt := filepathext.SmartJoin(path, taskfile)
 		if _, err := os.Stat(alt); err == nil {
-			l.VerboseOutf(logger.Magenta, "task: [%s] Not found - Using alternative (%s)\n", path, taskfile)
 			return filepath.Abs(alt)
 		}
 	}
@@ -130,14 +127,14 @@ func Exists(l *logger.Logger, path string) (string, error) {
 // calling the exists function until it finds a file or reaches the root
 // directory. On supported operating systems, it will also check if the user ID
 // of the directory changes and abort if it does.
-func ExistsWalk(l *logger.Logger, path string) (string, error) {
+func ExistsWalk(path string) (string, error) {
 	origPath := path
 	owner, err := sysinfo.Owner(path)
 	if err != nil {
 		return "", err
 	}
 	for {
-		fpath, err := Exists(l, path)
+		fpath, err := Exists(path)
 		if err == nil {
 			return fpath, nil
 		}

testdata/for/cmds/Taskfile.yml

@@ -1,5 +1,10 @@
 version: "3"
 
+vars:
+  OS_VAR: ["windows", "linux", "darwin"]
+  ARCH_VAR: ["amd64", "arm64"]
+  NOT_A_LIST: "not a list"
+
 tasks:
   # Loop over a list of values
   loop-explicit:
@@ -15,6 +20,26 @@ tasks:
             ARCH: ["amd64", "arm64"]
         cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
 
+  loop-matrix-ref:
+    cmds:
+      - for:
+          matrix:
+            OS:
+              ref: .OS_VAR
+            ARCH:
+              ref: .ARCH_VAR
+        cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+
+  loop-matrix-ref-error:
+    cmds:
+      - for:
+          matrix:
+            OS:
+              ref: .OS_VAR
+            ARCH:
+              ref: .NOT_A_LIST
+        cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+
   # Loop over the task's sources
   loop-sources:
     sources:

testdata/for/deps/Taskfile.yml

@@ -1,5 +1,10 @@
 version: "3"
 
+vars:
+  OS_VAR: ["windows", "linux", "darwin"]
+  ARCH_VAR: ["amd64", "arm64"]
+  NOT_A_LIST: "not a list"
+
 tasks:
   # Loop over a list of values
   loop-explicit:
@@ -19,6 +24,30 @@ tasks:
         vars:
           TEXT: "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
 
+  loop-matrix-ref:
+    deps:
+      - for:
+          matrix:
+            OS:
+              ref: .OS_VAR
+            ARCH:
+              ref: .ARCH_VAR
+        task: echo
+        vars:
+          TEXT: "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+
+  loop-matrix-ref-error:
+    deps:
+      - for:
+          matrix:
+            OS:
+              ref: .OS_VAR
+            ARCH:
+              ref: .NOT_A_LIST
+        task: echo
+        vars:
+          TEXT: "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
+
   # Loop over the task's sources
   loop-sources:
     sources:

testdata/include_with_vars_inside_include/Taskfile.yml

@@ -0,0 +1,10 @@
+version: "3"
+
+vars:
+  INCLUDE: include
+  FOO:
+    sh : echo bar
+
+includes:
+  included1:
+    taskfile: '{{.INCLUDE}}/Taskfile.include.yml'

testdata/include_with_vars_inside_include/include/Taskfile.include.yml

@@ -0,0 +1 @@
+version: "3"

testdata/requires/Taskfile.yml

@@ -33,10 +33,10 @@ tasks:
   validation-var:
     requires:
       vars:
+        - ENV
         - name: FOO
           enum: ['one', 'two']
 
-
   require-before-compile:
     requires:
       vars: [ MY_VAR ]

variables.go

@@ -1,6 +1,8 @@
 package task
 
 import (
+	"fmt"
+	"maps"
 	"os"
 	"path/filepath"
 	"strings"
@@ -18,61 +20,16 @@ import (
 
 // CompiledTask returns a copy of a task, but replacing variables in almost all
 // properties using the Go template package.
-func (e *Executor) CompiledTask(call *ast.Call) (*ast.Task, error) {
+func (e *Executor) CompiledTask(call *Call) (*ast.Task, error) {
 	return e.compiledTask(call, true)
 }
 
 // FastCompiledTask is like CompiledTask, but it skippes dynamic variables.
-func (e *Executor) FastCompiledTask(call *ast.Call) (*ast.Task, error) {
+func (e *Executor) FastCompiledTask(call *Call) (*ast.Task, error) {
 	return e.compiledTask(call, false)
 }
 
-func (e *Executor) CompiledTaskForTaskList(call *ast.Call) (*ast.Task, error) {
-	origTask, err := e.GetTask(call)
-	if err != nil {
-		return nil, err
-	}
-
-	vars, err := e.Compiler.FastGetVariables(origTask, call)
-	if err != nil {
-		return nil, err
-	}
-
-	cache := &templater.Cache{Vars: vars}
-
-	return &ast.Task{
-		Task:                 origTask.Task,
-		Label:                templater.Replace(origTask.Label, cache),
-		Desc:                 templater.Replace(origTask.Desc, cache),
-		Prompt:               templater.Replace(origTask.Prompt, cache),
-		Summary:              templater.Replace(origTask.Summary, cache),
-		Aliases:              origTask.Aliases,
-		Sources:              origTask.Sources,
-		Generates:            origTask.Generates,
-		Dir:                  origTask.Dir,
-		Set:                  origTask.Set,
-		Shopt:                origTask.Shopt,
-		Vars:                 vars,
-		Env:                  nil,
-		Dotenv:               origTask.Dotenv,
-		Silent:               origTask.Silent,
-		Interactive:          origTask.Interactive,
-		Internal:             origTask.Internal,
-		Method:               origTask.Method,
-		Prefix:               origTask.Prefix,
-		IgnoreError:          origTask.IgnoreError,
-		Run:                  origTask.Run,
-		IncludeVars:          origTask.IncludeVars,
-		IncludedTaskfileVars: origTask.IncludedTaskfileVars,
-		Platforms:            origTask.Platforms,
-		Location:             origTask.Location,
-		Requires:             origTask.Requires,
-		Watch:                origTask.Watch,
-		Namespace:            origTask.Namespace,
-	}, nil
-}
-
-func (e *Executor) compiledTask(call *ast.Call, evaluateShVars bool) (*ast.Task, error) {
+func (e *Executor) compiledTask(call *Call, evaluateShVars bool) (*ast.Task, error) {
 	origTask, err := e.GetTask(call)
 	if err != nil {
 		return nil, err
@@ -155,21 +112,17 @@ func (e *Executor) compiledTask(call *ast.Call, evaluateShVars bool) (*ast.Task,
 	new.Env.Merge(templater.ReplaceVars(dotenvEnvs, cache), nil)
 	new.Env.Merge(templater.ReplaceVars(origTask.Env, cache), nil)
 	if evaluateShVars {
-		err = new.Env.Range(func(k string, v ast.Var) error {
+		for k, v := range new.Env.All() {
 			// If the variable is not dynamic, we can set it and return
 			if v.Value != nil || v.Sh == nil {
 				new.Env.Set(k, ast.Var{Value: v.Value})
-				return nil
+				continue
 			}
 			static, err := e.Compiler.HandleDynamicVar(v, new.Dir, env.GetFromVars(new.Env))
 			if err != nil {
-				return err
+				return nil, err
 			}
 			new.Env.Set(k, ast.Var{Value: static})
-			return nil
-		})
-		if err != nil {
-			return nil, err
 		}
 	}
 
@@ -200,7 +153,7 @@ func (e *Executor) compiledTask(call *ast.Call, evaluateShVars bool) (*ast.Task,
 				continue
 			}
 			if cmd.For != nil {
-				list, keys, err := itemsFromFor(cmd.For, new.Dir, new.Sources, vars, origTask.Location)
+				list, keys, err := itemsFromFor(cmd.For, new.Dir, new.Sources, vars, origTask.Location, cache)
 				if err != nil {
 					return nil, err
 				}
@@ -247,7 +200,7 @@ func (e *Executor) compiledTask(call *ast.Call, evaluateShVars bool) (*ast.Task,
 				continue
 			}
 			if dep.For != nil {
-				list, keys, err := itemsFromFor(dep.For, new.Dir, new.Sources, vars, origTask.Location)
+				list, keys, err := itemsFromFor(dep.For, new.Dir, new.Sources, vars, origTask.Location, cache)
 				if err != nil {
 					return nil, err
 				}
@@ -319,11 +272,18 @@ func itemsFromFor(
 	sources []*ast.Glob,
 	vars *ast.Vars,
 	location *ast.Location,
+	cache *templater.Cache,
 ) ([]any, []string, error) {
 	var keys []string // The list of keys to loop over (only if looping over a map)
 	var values []any  // The list of values to loop over
 	// Get the list from a matrix
 	if f.Matrix.Len() != 0 {
+		if err := resolveMatrixRefs(f.Matrix, cache); err != nil {
+			return nil, nil, errors.TaskfileInvalidError{
+				URI: location.Taskfile,
+				Err: err,
+			}
+		}
 		return asAnySlice(product(f.Matrix)), nil, nil
 	}
 	// Get the list from the explicit for list
@@ -351,7 +311,7 @@ func itemsFromFor(
 			// If the variable is dynamic, then it hasn't been resolved yet
 			// and we can't use it as a list. This happens when fast compiling a task
 			// for use in --list or --list-all etc.
-			if ok && v.Sh == nil {
+			if ok && v.Value != nil && v.Sh == nil {
 				switch value := v.Value.(type) {
 				case string:
 					if f.Split != "" {
@@ -382,9 +342,27 @@ func itemsFromFor(
 	return values, keys, nil
 }
 
+func resolveMatrixRefs(matrix *ast.Matrix, cache *templater.Cache) error {
+	if matrix.Len() == 0 {
+		return nil
+	}
+	for _, row := range matrix.All() {
+		if row.Ref != "" {
+			v := templater.ResolveRef(row.Ref, cache)
+			switch value := v.(type) {
+			case []any:
+				row.Value = value
+			default:
+				return fmt.Errorf("matrix reference %q must resolve to a list", row.Ref)
+			}
+		}
+	}
+	return nil
+}
+
 // product generates the cartesian product of the input map of slices.
-func product(inputMap *ast.Matrix) []map[string]any {
-	if inputMap.Len() == 0 {
+func product(matrix *ast.Matrix) []map[string]any {
+	if matrix.Len() == 0 {
 		return nil
 	}
 
@@ -392,18 +370,16 @@ func product(inputMap *ast.Matrix) []map[string]any {
 	result := []map[string]any{{}}
 
 	// Iterate over each slice in the slices
-	_ = inputMap.Range(func(key string, slice []any) error {
+	for key, row := range matrix.All() {
 		var newResult []map[string]any
 
 		// For each combination in the current result
 		for _, combination := range result {
 			// Append each element from the current slice to the combinations
-			for _, item := range slice {
+			for _, item := range row.Value {
 				newComb := make(map[string]any, len(combination))
 				// Copy the existing combination
-				for k, v := range combination {
-					newComb[k] = v
-				}
+				maps.Copy(newComb, combination)
 				// Add the current item with the corresponding key
 				newComb[key] = item
 				newResult = append(newResult, newComb)
@@ -412,8 +388,7 @@ func product(inputMap *ast.Matrix) []map[string]any {
 
 		// Update result with the new combinations
 		result = newResult
-		return nil
-	})
+	}
 
 	return result
 }

watch.go

@@ -15,13 +15,12 @@ import (
 	"github.com/go-task/task/v3/errors"
 	"github.com/go-task/task/v3/internal/fingerprint"
 	"github.com/go-task/task/v3/internal/logger"
-	"github.com/go-task/task/v3/taskfile/ast"
 )
 
 const defaultWatchInterval = 5 * time.Second
 
 // watchTasks start watching the given tasks
-func (e *Executor) watchTasks(calls ...*ast.Call) error {
+func (e *Executor) watchTasks(calls ...*Call) error {
 	tasks := make([]string, len(calls))
 	for i, c := range calls {
 		tasks[i] = c.Task
@@ -119,24 +118,24 @@ func closeOnInterrupt(w *watcher.Watcher) {
 	}()
 }
 
-func (e *Executor) registerWatchedFiles(w *watcher.Watcher, calls ...*ast.Call) error {
+func (e *Executor) registerWatchedFiles(w *watcher.Watcher, calls ...*Call) error {
 	watchedFiles := w.WatchedFiles()
 
-	var registerTaskFiles func(*ast.Call) error
-	registerTaskFiles = func(c *ast.Call) error {
+	var registerTaskFiles func(*Call) error
+	registerTaskFiles = func(c *Call) error {
 		task, err := e.CompiledTask(c)
 		if err != nil {
 			return err
 		}
 
 		for _, d := range task.Deps {
-			if err := registerTaskFiles(&ast.Call{Task: d.Task, Vars: d.Vars}); err != nil {
+			if err := registerTaskFiles(&Call{Task: d.Task, Vars: d.Vars}); err != nil {
 				return err
 			}
 		}
 		for _, c := range task.Cmds {
 			if c.Task != "" {
-				if err := registerTaskFiles(&ast.Call{Task: c.Task, Vars: c.Vars}); err != nil {
+				if err := registerTaskFiles(&Call{Task: c.Task, Vars: c.Vars}); err != nil {
 					return err
 				}
 			}

website/docs/changelog.mdx

@@ -5,6 +5,94 @@ sidebar_position: 14
 
 # Changelog
 
+## v3.42.1 - 2025-03-10
+
+- Fixed a bug where some special variables caused a type error when used global
+  variables (#2106, #2107 by @pd93).
+
+## 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/docs/community.mdx

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

website/docs/contributing.mdx

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

website/docs/deprecations/deprecations.mdx

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

website/docs/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
-   contains the relevant environment variable(s). This allows you to enable an
-   experimental feature at a project level. If you commit the `.env` file to
-   source control then other users of your project will also have these
-   experiments enabled.
+3. Creating a `.env` or a `.task-experiments.yml` file in the same directory as
+   your root Taskfile.\
+   The `.env` file should contain the relevant environment
+   variable(s), while the `.task-experiments.yml` file should use a YAML format
+   where each experiment is defined as a key with a corresponding value.
 
-   ```shell title=".env"
-   TASK_X_FEATURE=1
-   ```
+   This allows you to enable an experimental feature at a project level. If you
+   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/docs/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/docs/integrations.mdx

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

website/docs/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/docs/reference/_category_.yml

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

website/docs/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/docs/releasing.mdx

@@ -58,7 +58,7 @@ If you think its Task version is outdated, open an issue to let us know.
 
 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).
+[this file](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/go/go-task/package.nix).
 If you think its Task version is outdated, open an issue to let us know.
 
 {/* prettier-ignore-start */}

website/docs/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/docs/taskfile_versions.mdx

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

website/docs/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`
-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.
+Specific Taskfiles can be called by specifying the `--taskfile` flag. If you
+don't specify a Taskfile, Task will automatically look for a file with one of
+the [supported file names](#supported-file-names) in the current directory. If
+you want to search in a different directory, you can use the `--dir` flag.
 
-```yaml
-version: '3'
+### Supported file names
 
-tasks:
-  build:
-    cmds:
-      - go build -v -i main.go
+Task looks for files with the following names, in order of priority:
 
-  assets:
-    cmds:
-      - esbuild --bundle --minify css/index.css > public/bundle.css
-```
+- `Taskfile.yml`
+- `taskfile.yml`
+- `Taskfile.yaml`
+- `taskfile.yaml`
+- `Taskfile.dist.yml`
+- `taskfile.dist.yml`
+- `Taskfile.dist.yaml`
+- `taskfile.dist.yaml`
 
-Running the tasks is as simple as running:
-
-```shell
-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`).
+The `.dist` variants allow projects to have one committed file (`.dist`) while
+still allowing individual users to override the Taskfile by adding an additional
+`Taskfile.yml` (which would be in your `.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
-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:
+You can include OS-specific Taskfiles by using a templating function:
 
 ```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:

website/static/schema-taskrc.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Taskrc YAML Schema",
+  "description": "Schema for .taskrc files.",
+  "type": "object",
+  "properties": {
+    "experiments": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "integer"
+      }
+    }
+  },
+  "additionalProperties": false
+}

website/static/schema.json

@@ -29,6 +29,12 @@
                   },
                   {
                     "$ref": "#/definitions/task_call"
+                  },
+                  {
+                    "$ref": "#/definitions/defer_task_call"
+                  },
+                  {
+                    "$ref": "#/definitions/defer_cmd_call"
                   }
                 ]
               }
@@ -216,7 +222,10 @@
           "$ref": "#/definitions/task_call"
         },
         {
-          "$ref": "#/definitions/defer_call"
+          "$ref": "#/definitions/defer_task_call"
+        },
+        {
+          "$ref": "#/definitions/defer_cmd_call"
         },
         {
           "$ref": "#/definitions/for_cmds_call"
@@ -350,15 +359,12 @@
       "additionalProperties": false,
       "required": ["cmd"]
     },
-    "defer_call": {
+    "defer_task_call": {
       "type": "object",
       "properties": {
         "defer": {
           "description": "Run a command when the task completes. This command will run even when the task fails",
           "anyOf": [
-            {
-              "type": "string"
-            },
             {
               "$ref": "#/definitions/task_call"
             }
@@ -368,6 +374,21 @@
       "additionalProperties": false,
       "required": ["defer"]
     },
+    "defer_cmd_call": {
+      "type": "object",
+      "properties": {
+        "defer": {
+          "description": "Name of the command to defer",
+          "type": "string"
+        },
+        "silent": {
+          "description": "Hides task name and command from output. The command's output will still be redirected to `STDOUT` and `STDERR`.",
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false,
+      "required": ["defer"]
+    },
     "for_cmds_call": {
       "type": "object",
       "properties": {

website/versioned_docs/version-latest/changelog.mdx

@@ -5,6 +5,94 @@ sidebar_position: 14
 
 # Changelog
 
+## v3.42.1 - 2025-03-10
+
+- Fixed a bug where some special variables caused a type error when used global
+  variables (#2106, #2107 by @pd93).
+
+## 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
-   contains the relevant environment variable(s). This allows you to enable an
-   experimental feature at a project level. If you commit the `.env` file to
-   source control then other users of your project will also have these
-   experiments enabled.
+3. Creating a `.env` or a `.task-experiments.yml` file in the same directory as
+   your root Taskfile.\
+   The `.env` file should contain the relevant environment
+   variable(s), while the `.task-experiments.yml` file should use a YAML format
+   where each experiment is defined as a key with a corresponding value.
 
-   ```shell title=".env"
-   TASK_X_FEATURE=1
-   ```
+   This allows you to enable an experimental feature at a project level. If you
+   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/releasing.mdx

@@ -58,7 +58,7 @@ If you think its Task version is outdated, open an issue to let us know.
 
 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).
+[this file](https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/go/go-task/package.nix).
 If you think its Task version is outdated, open an issue to let us know.
 
 {/* prettier-ignore-start */}

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`
-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.
+Specific Taskfiles can be called by specifying the `--taskfile` flag. If you
+don't specify a Taskfile, Task will automatically look for a file with one of
+the [supported file names](#supported-file-names) in the current directory. If
+you want to search in a different directory, you can use the `--dir` flag.
 
-```yaml
-version: '3'
+### Supported file names
 
-tasks:
-  build:
-    cmds:
-      - go build -v -i main.go
+Task looks for files with the following names, in order of priority:
 
-  assets:
-    cmds:
-      - esbuild --bundle --minify css/index.css > public/bundle.css
-```
+- `Taskfile.yml`
+- `taskfile.yml`
+- `Taskfile.yaml`
+- `taskfile.yaml`
+- `Taskfile.dist.yml`
+- `taskfile.dist.yml`
+- `Taskfile.dist.yaml`
+- `taskfile.dist.yaml`
 
-Running the tasks is as simple as running:
-
-```shell
-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`).
+The `.dist` variants allow projects to have one committed file (`.dist`) while
+still allowing individual users to override the Taskfile by adding an additional
+`Taskfile.yml` (which would be in your `.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
-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:
+You can include OS-specific Taskfiles by using a templating function:
 
 ```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:

website/yarn.lock

@@ -2437,9 +2437,9 @@
     "@types/react" "*"
 
 "@types/react@*", "@types/react@^19.0.0":
-  version "19.0.8"
-  resolved "https://registry.yarnpkg.com/@types/react/-/react-19.0.8.tgz#7098e6159f2a61e4f4cef2c1223c044a9bec590e"
-  integrity sha512-9P/o1IGdfmQxrujGbIMDyYaaCykhLKc0NGCtYcECNUr9UAaDe4gwvV9bR6tvd5Br1SG0j+PBpbKr2UYY8CwqSw==
+  version "19.0.10"
+  resolved "https://registry.yarnpkg.com/@types/react/-/react-19.0.10.tgz#d0c66dafd862474190fe95ce11a68de69ed2b0eb"
+  integrity sha512-JuRQ9KXLEjaUNjTWpzuR231Z2WpIwczOkBEIvbHNCzQefFIT0L8IqE6NV6ULLyC1SI/i234JnDoMkfg+RjQj2g==
   dependencies:
     csstype "^3.0.2"
 
@@ -5497,9 +5497,9 @@ markdown-table@^2.0.0:
     repeat-string "^1.0.0"
 
 markdown-table@^3.0.0:
-  version "3.0.3"
-  resolved "https://registry.npmjs.org/markdown-table/-/markdown-table-3.0.3.tgz"
-  integrity sha512-Z1NL3Tb1M9wH4XESsCDEksWoKTdlUafKc4pt0GRwjUyXaCFZ+dc3g2erqB6zm3szA2IUSi7VnPI+o/9jnxh9hw==
+  version "3.0.4"
+  resolved "https://registry.yarnpkg.com/markdown-table/-/markdown-table-3.0.4.tgz#fe44d6d410ff9d6f2ea1797a3f60aa4d2b631c2a"
+  integrity sha512-wiYz4+JrLyb/DqW2hkFJxP7Vd7JuTDm77fvbM8VfEQdmSMqcImWeeRbHwZjBjIFki/VaMK2BhFi7oUUZeM5bqw==
 
 math-intrinsics@^1.1.0:
   version "1.1.0"
@@ -5521,17 +5521,7 @@ mdast-util-directive@^3.0.0:
     stringify-entities "^4.0.0"
     unist-util-visit-parents "^6.0.0"
 
-mdast-util-find-and-replace@^3.0.0:
-  version "3.0.1"
-  resolved "https://registry.npmjs.org/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.1.tgz"
-  integrity sha512-SG21kZHGC3XRTSUhtofZkBzZTJNM5ecCi0SK2IMKmSXR8vO3peL+kb1O0z7Zl83jKtutG4k5Wv/W7V3/YHvzPA==
-  dependencies:
-    "@types/mdast" "^4.0.0"
-    escape-string-regexp "^5.0.0"
-    unist-util-is "^6.0.0"
-    unist-util-visit-parents "^6.0.0"
-
-mdast-util-find-and-replace@^3.0.1:
+mdast-util-find-and-replace@^3.0.0, mdast-util-find-and-replace@^3.0.1:
   version "3.0.2"
   resolved "https://registry.yarnpkg.com/mdast-util-find-and-replace/-/mdast-util-find-and-replace-3.0.2.tgz#70a3174c894e14df722abf43bc250cbae44b11df"
   integrity sha512-Tmd1Vg/m3Xz43afeNxDIhWRtFZgM2VLyaf4vSTYwudTyeuTneoL3qtWMA5jeLyz/O1vDJmmV4QuScFCA2tBPwg==
@@ -5572,9 +5562,9 @@ mdast-util-frontmatter@^2.0.0:
     micromark-extension-frontmatter "^2.0.0"
 
 mdast-util-gfm-autolink-literal@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.0.tgz"
-  integrity sha512-FyzMsduZZHSc3i0Px3PQcBT4WJY/X/RCtEJKuybiC6sjPqLv7h1yqAkmILZtuxMSsUyaLUWNp71+vQH2zqp5cg==
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm-autolink-literal/-/mdast-util-gfm-autolink-literal-2.0.1.tgz#abd557630337bd30a6d5a4bd8252e1c2dc0875d5"
+  integrity sha512-5HVP2MKaP6L+G6YaxPNjuL0BPrq9orG3TsrZ9YXbA3vDw/ACI4MEsnoDpn6ZNm7GnZgtAcONJyPhOP8tNJQavQ==
   dependencies:
     "@types/mdast" "^4.0.0"
     ccount "^2.0.0"
@@ -5583,9 +5573,9 @@ mdast-util-gfm-autolink-literal@^2.0.0:
     micromark-util-character "^2.0.0"
 
 mdast-util-gfm-footnote@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.0.0.tgz"
-  integrity sha512-5jOT2boTSVkMnQ7LTrd6n/18kqwjmuYqo7JUPe+tRCY6O7dAuTFMtTPauYYrMPpox9hlN0uOx/FL8XvEfG9/mQ==
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm-footnote/-/mdast-util-gfm-footnote-2.1.0.tgz#7778e9d9ca3df7238cc2bd3fa2b1bf6a65b19403"
+  integrity sha512-sqpDWlsHn7Ac9GNZQMeUzPQSMzR6Wv0WKRNvQRg0KqHh02fpTz69Qc1QSseNX29bhz1ROIyNyxExfawVKTm1GQ==
   dependencies:
     "@types/mdast" "^4.0.0"
     devlop "^1.1.0"
@@ -5595,7 +5585,7 @@ mdast-util-gfm-footnote@^2.0.0:
 
 mdast-util-gfm-strikethrough@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm-strikethrough/-/mdast-util-gfm-strikethrough-2.0.0.tgz#d44ef9e8ed283ac8c1165ab0d0dfd058c2764c16"
   integrity sha512-mKKb915TF+OC5ptj5bJ7WFRPdYtuHv0yTRxK2tJvi+BDqbkiG7h7u/9SI89nRAYcmap2xHQL9D+QG/6wSrTtXg==
   dependencies:
     "@types/mdast" "^4.0.0"
@@ -5604,7 +5594,7 @@ mdast-util-gfm-strikethrough@^2.0.0:
 
 mdast-util-gfm-table@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm-table/-/mdast-util-gfm-table-2.0.0.tgz#7a435fb6223a72b0862b33afbd712b6dae878d38"
   integrity sha512-78UEvebzz/rJIxLvE7ZtDd/vIQ0RHv+3Mh5DR96p7cS7HsBhYIICDBCu8csTNWNO6tBWfqXPWekRuj2FNOGOZg==
   dependencies:
     "@types/mdast" "^4.0.0"
@@ -5615,7 +5605,7 @@ mdast-util-gfm-table@^2.0.0:
 
 mdast-util-gfm-task-list-item@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm-task-list-item/-/mdast-util-gfm-task-list-item-2.0.0.tgz#e68095d2f8a4303ef24094ab642e1047b991a936"
   integrity sha512-IrtvNvjxC1o06taBAVJznEnkiHxLFTzgonUdy8hzFVeDun0uTjxxrRGVaNFqkU1wJR3RBPEfsxmU6jDWPofrTQ==
   dependencies:
     "@types/mdast" "^4.0.0"
@@ -5624,9 +5614,9 @@ mdast-util-gfm-task-list-item@^2.0.0:
     mdast-util-to-markdown "^2.0.0"
 
 mdast-util-gfm@^3.0.0:
-  version "3.0.0"
-  resolved "https://registry.npmjs.org/mdast-util-gfm/-/mdast-util-gfm-3.0.0.tgz"
-  integrity sha512-dgQEX5Amaq+DuUqf26jJqSK9qgixgd6rYDHAv4aTBuA92cTknZlKpPfa86Z/s8Dj8xsAQpFfBmPUHWJBWqS4Bw==
+  version "3.1.0"
+  resolved "https://registry.yarnpkg.com/mdast-util-gfm/-/mdast-util-gfm-3.1.0.tgz#2cdf63b92c2a331406b0fb0db4c077c1b0331751"
+  integrity sha512-0ulfdQOM3ysHhCJ1p06l0b0VKlhU0wuQs3thxZQagjcjPrlFRqY215uZGHHJan9GEAXd9MbfPjFJz+qMkVR6zQ==
   dependencies:
     mdast-util-from-markdown "^2.0.0"
     mdast-util-gfm-autolink-literal "^2.0.0"
@@ -5822,9 +5812,9 @@ micromark-extension-frontmatter@^2.0.0:
     micromark-util-types "^2.0.0"
 
 micromark-extension-gfm-autolink-literal@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.0.0.tgz"
-  integrity sha512-rTHfnpt/Q7dEAK1Y5ii0W8bhfJlVJFnJMHIPisfPK3gpVNuOP0VnRl96+YJ3RYWV/P4gFeQoGKNlT3RhuvpqAg==
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-autolink-literal/-/micromark-extension-gfm-autolink-literal-2.1.0.tgz#6286aee9686c4462c1e3552a9d505feddceeb935"
+  integrity sha512-oOg7knzhicgQ3t4QCjCWgTmfNhvQbDDnJeVu9v81r7NltNCVmhPy1fJRX27pISafdjL+SVc4d3l48Gb6pbRypw==
   dependencies:
     micromark-util-character "^2.0.0"
     micromark-util-sanitize-uri "^2.0.0"
@@ -5832,9 +5822,9 @@ micromark-extension-gfm-autolink-literal@^2.0.0:
     micromark-util-types "^2.0.0"
 
 micromark-extension-gfm-footnote@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.0.0.tgz"
-  integrity sha512-6Rzu0CYRKDv3BfLAUnZsSlzx3ak6HAoI85KTiijuKIz5UxZxbUI+pD6oHgw+6UtQuiRwnGRhzMmPRv4smcz0fg==
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-footnote/-/micromark-extension-gfm-footnote-2.1.0.tgz#4dab56d4e398b9853f6fe4efac4fc9361f3e0750"
+  integrity sha512-/yPhxI1ntnDNsiHtzLKYnE3vf9JZ6cAisqVDauhp4CEHxlb4uoOTxOCJ+9s51bIB8U1N1FJ1RXOKTIlD5B/gqw==
   dependencies:
     devlop "^1.0.0"
     micromark-core-commonmark "^2.0.0"
@@ -5846,9 +5836,9 @@ micromark-extension-gfm-footnote@^2.0.0:
     micromark-util-types "^2.0.0"
 
 micromark-extension-gfm-strikethrough@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.0.0.tgz"
-  integrity sha512-c3BR1ClMp5fxxmwP6AoOY2fXO9U8uFMKs4ADD66ahLTNcwzSCyRVU4k7LPV5Nxo/VJiR4TdzxRQY2v3qIUceCw==
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-strikethrough/-/micromark-extension-gfm-strikethrough-2.1.0.tgz#86106df8b3a692b5f6a92280d3879be6be46d923"
+  integrity sha512-ADVjpOOkjz1hhkZLlBiYA9cR2Anf8F4HqZUO6e5eDcPQd0Txw5fxLzzxnEkSkfnD0wziSGiv7sYhk/ktvbf1uw==
   dependencies:
     devlop "^1.0.0"
     micromark-util-chunked "^2.0.0"
@@ -5858,9 +5848,9 @@ micromark-extension-gfm-strikethrough@^2.0.0:
     micromark-util-types "^2.0.0"
 
 micromark-extension-gfm-table@^2.0.0:
-  version "2.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.0.0.tgz"
-  integrity sha512-PoHlhypg1ItIucOaHmKE8fbin3vTLpDOUg8KAr8gRCF1MOZI9Nquq2i/44wFvviM4WuxJzc3demT8Y3dkfvYrw==
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-table/-/micromark-extension-gfm-table-2.1.1.tgz#fac70bcbf51fe65f5f44033118d39be8a9b5940b"
+  integrity sha512-t2OU/dXXioARrC6yWfJ4hqB7rct14e8f7m0cbI5hUmDyyIlwv5vEtooptH8INkbLzOatzKuVbQmAYcbWoyz6Dg==
   dependencies:
     devlop "^1.0.0"
     micromark-factory-space "^2.0.0"
@@ -5870,15 +5860,15 @@ micromark-extension-gfm-table@^2.0.0:
 
 micromark-extension-gfm-tagfilter@^2.0.0:
   version "2.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-tagfilter/-/micromark-extension-gfm-tagfilter-2.0.0.tgz#f26d8a7807b5985fba13cf61465b58ca5ff7dc57"
   integrity sha512-xHlTOmuCSotIA8TW1mDIM6X2O1SiX5P9IuDtqGonFhEK0qgRI4yeC6vMxEV2dgyr2TiD+2PQ10o+cOhdVAcwfg==
   dependencies:
     micromark-util-types "^2.0.0"
 
 micromark-extension-gfm-task-list-item@^2.0.0:
-  version "2.0.1"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.0.1.tgz"
-  integrity sha512-cY5PzGcnULaN5O7T+cOzfMoHjBW7j+T9D2sucA5d/KbsBTPcYdebm9zUd9zzdgJGCwahV+/W78Z3nbulBYVbTw==
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm-task-list-item/-/micromark-extension-gfm-task-list-item-2.1.0.tgz#bcc34d805639829990ec175c3eea12bb5b781f2c"
+  integrity sha512-qIBZhqxqI6fjLDYFTBIa4eivDMnP+OZqsNwmQ3xNLE4Cxwc+zfQEfbs6tzAo2Hjq+bh6q5F+Z8/cksrLFYWQQw==
   dependencies:
     devlop "^1.0.0"
     micromark-factory-space "^2.0.0"
@@ -5888,7 +5878,7 @@ micromark-extension-gfm-task-list-item@^2.0.0:
 
 micromark-extension-gfm@^3.0.0:
   version "3.0.0"
-  resolved "https://registry.npmjs.org/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/micromark-extension-gfm/-/micromark-extension-gfm-3.0.0.tgz#3e13376ab95dd7a5cfd0e29560dfe999657b3c5b"
   integrity sha512-vsKArQsicm7t0z2GugkCKtZehqUm31oeGBV/KVSorWSy8ZlNAv7ytjFhvaryUiCUJYqs+NoE6AFhpQvBTM6Q4w==
   dependencies:
     micromark-extension-gfm-autolink-literal "^2.0.0"
@@ -7720,9 +7710,9 @@ remark-frontmatter@^5.0.0:
     unified "^11.0.0"
 
 remark-gfm@^4.0.0:
-  version "4.0.0"
-  resolved "https://registry.npmjs.org/remark-gfm/-/remark-gfm-4.0.0.tgz"
-  integrity sha512-U92vJgBPkbw4Zfu/IiW2oTZLSL3Zpv+uI7My2eq8JxKgqraFdU8YUGicEJCEgSbeaG+QDFqIcwwfMTOEelPxuA==
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/remark-gfm/-/remark-gfm-4.0.1.tgz#33227b2a74397670d357bf05c098eaf8513f0d6b"
+  integrity sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg==
   dependencies:
     "@types/mdast" "^4.0.0"
     mdast-util-gfm "^3.0.0"
@@ -7774,7 +7764,7 @@ remark-rehype@^11.0.0:
 
 remark-stringify@^11.0.0:
   version "11.0.0"
-  resolved "https://registry.npmjs.org/remark-stringify/-/remark-stringify-11.0.0.tgz"
+  resolved "https://registry.yarnpkg.com/remark-stringify/-/remark-stringify-11.0.0.tgz#4c5b01dd711c269df1aaae11743eb7e2e7636fd3"
   integrity sha512-1OSmLd3awB/t8qdoEOMazZkNsfVTeY4fTsgzcQFdXNq8ToTN4ZGwrMnlda4K6smTFKD+GRV6O48i6Z4iKgPPpw==
   dependencies:
     "@types/mdast" "^4.0.0"
@@ -8530,9 +8520,9 @@ typedarray-to-buffer@^3.1.5:
     is-typedarray "^1.0.0"
 
 typescript@^5.3.3:
-  version "5.7.3"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.7.3.tgz#919b44a7dbb8583a9b856d162be24a54bf80073e"
-  integrity sha512-84MVSjMEHP+FQRPy3pX9sTVV/INIex71s9TL2Gm5FG/WG1SqXeKyZ0k7/blY/4FdOzI12CBy1vGc4og/eus0fw==
+  version "5.8.2"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.8.2.tgz#8170b3702f74b79db2e5a96207c15e65807999e4"
+  integrity sha512-aJn6wq13/afZp/jT9QZmwEjDqqvSGp1VT5GVg+f/t6/oVyrgXM6BY1h9BRh/O5p3PlUPAe+WuiEZOmb/49RqoQ==
 
 undici-types@~6.20.0:
   version "6.20.0"