go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2025-08-08 22:36:57 +02:00
Code Issues Releases Activity

v3.42.0

Browse Source
This commit is contained in:
Andrey Nering
2025-03-08 22:34:07 -03:00
parent 1b8b399c7e
commit cd086228b2
17 changed files with 409 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

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

2
package-lock.json generated
View File

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

2
package.json
View File

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

83
website/docs/changelog.mdx
View File

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

83
website/versioned_docs/version-latest/changelog.mdx
View File

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

2
website/versioned_docs/version-latest/community.mdx
View File

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

2
website/versioned_docs/version-latest/contributing.mdx
View File

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

2
website/versioned_docs/version-latest/deprecations/deprecations.mdx
View File

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

35
website/versioned_docs/version-latest/experiments/experiments.mdx
View File

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

143
website/versioned_docs/version-latest/getting_started.mdx Normal file
View File

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

2
website/versioned_docs/version-latest/integrations.mdx
View File

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

31
website/versioned_docs/version-latest/intro.mdx
View File

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

2
website/versioned_docs/version-latest/reference/_category_.yml
View File

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

6
website/versioned_docs/version-latest/reference/cli.mdx
View File

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

4
website/versioned_docs/version-latest/styleguide.mdx
View File

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

2
website/versioned_docs/version-latest/taskfile_versions.mdx
View File

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

94
website/versioned_docs/version-latest/usage.mdx
View File

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