Merge branch 'main' into feat/add-allowed-values-when-vars-not-provided

.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

@@ -12,7 +12,7 @@ linters:
     - misspell
     - noctx
     - paralleltest
-    - tenv
+    - usetesting
     - thelper
     - tparallel
 
@@ -29,6 +29,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{}'

CHANGELOG.md

@@ -4,6 +4,8 @@
 
 - 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
@@ -14,6 +16,23 @@
   experiment with an invalid value (#1979, #2049 by @pd93).
 - Refactored the experiments package and added tests (#2049 by @pd93).
 
+#### 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.
+
 ## v3.41.0 - 2025-01-18
 
 - Fixed an issue where dynamic variables were not properly logged in verbose

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

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
 	}
 

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
@@ -21,11 +21,11 @@ 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.11.0
+	golang.org/x/term v0.29.0
 	gopkg.in/yaml.v3 v3.0.1
 	mvdan.cc/sh/v3 v3.10.0
 )
@@ -56,7 +56,7 @@ require (
 	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/sys v0.30.0 // indirect
 	golang.org/x/tools v0.22.0 // indirect
 	gopkg.in/warnings.v0 v0.1.2 // indirect
 )

go.sum

@@ -131,6 +131,8 @@ github.com/skeema/knownhosts v1.3.0 h1:AM+y0rI04VksttfwjkSTNQorvGqmwATnvnAHpSgc0
 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/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=
@@ -160,6 +162,8 @@ 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/sync v0.11.0 h1:GGz8+XQP4FvTTrjZPzNKTMFtSXH80RAzG+5ghFPgK9w=
+golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 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=
@@ -173,11 +177,15 @@ 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/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/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=

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"
-
-// InitTaskfile creates a new Taskfile
-func InitTaskfile(w io.Writer, dir string) error {
-	f := filepathext.SmartJoin(dir, DefaultTaskFilename)
+const defaultTaskFilename = "Taskfile.yml"
+
+// 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.Stat(f); err == nil {
-		return errors.TaskfileAlreadyExistsError{}
+	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{}
+		}
 	}
 
-	if err := os.WriteFile(f, []byte(DefaultTaskfile), 0o644); err != nil {
-		return err
+	if err := os.WriteFile(path, []byte(DefaultTaskfile), 0o644); err != nil {
+		return path, err
 	}
 
-	return nil
+	return path, nil
 }

init_test.go

@@ -1,15 +1,14 @@
 package task_test
 
 import (
-	"io"
 	"os"
 	"testing"
 
 	"github.com/go-task/task/v3"
 	"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/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/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 == "" {

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.