diff --git a/CHANGELOG.md b/CHANGELOG.md index 6eb18a73..5f27b45b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## v3.42.0 - 2025-03-08 - Made `--init` less verbose by default and respect `--silent` and `--verbose` flags (#2009, #2011 by @HeCorr). diff --git a/package-lock.json b/package-lock.json index 1624fdf2..75785efb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.41.0", + "version": "3.42.0", "lockfileVersion": 2, "requires": true, "packages": { diff --git a/package.json b/package.json index da587753..b80d2afe 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.41.0", + "version": "3.42.0", "description": "A task runner / simpler Make alternative written in Go", "scripts": { "postinstall": "go-npm install", diff --git a/website/docs/changelog.mdx b/website/docs/changelog.mdx index ff72992f..d326b9b8 100644 --- a/website/docs/changelog.mdx +++ b/website/docs/changelog.mdx @@ -5,6 +5,89 @@ sidebar_position: 14 # Changelog +## v3.42.0 - 2025-03-08 + +- Made `--init` less verbose by default and respect `--silent` and `--verbose` + flags (#2009, #2011 by @HeCorr). +- `--init` now accepts a file name or directory as an argument (#2008, #2018 by + @HeCorr). +- Fix a bug where an HTTP node's location was being mutated incorrectly (#2007 + by @jeongukjae). +- Fixed a bug where allowed values didn't work with dynamic var (#2032, #2033 by + @vmaerten). +- Use only the relevant checker (timestamp or checksum) to improve performance + (#2029, #2031 by @vmaerten). +- Print warnings when attempting to enable an inactive experiment or an active + experiment with an invalid value (#1979, #2049 by @pd93). +- Refactored the experiments package and added tests (#2049 by @pd93). +- Show allowed values when a variable with an enum is missing (#2027, #2052 by + @vmaerten). +- Refactored how snippets in error work and added tests (#2068 by @pd93). +- Fixed a bug where errors decoding commands were sometimes unhelpful (#2068 by + @pd93). +- Fixed a bug in the Taskfile schema where `defer` statements in the shorthand + `cmds` syntax were not considered valid (#2068 by @pd93). +- Refactored how task sorting functions work (#1798 by @pd93). +- Added a new `.taskrc.yml` (or `.taskrc.yaml`) file to let users enable + experiments (similar to `.env`) (#1982 by @vmaerten). +- Added new [Getting Started docs](https://taskfile.dev/getting-started) (#2086 + by @pd93). +- Allow `matrix` to use references to other variables (#2065, #2069 by @pd93). +- Fixed a bug where, when a dynamic variable is provided, even if it is not + used, all other variables become unavailable in the templating system within + the include (#2092 by @vmaerten). + +#### Package API + +Unlike our CLI tool, +[Task's package API is not currently stable](https://taskfile.dev/reference/package). +In an effort to ease the pain of breaking changes for our users, we will be +providing changelogs for our package API going forwards. The hope is that these +changes will provide a better long-term experience for our users and allow to +stabilize the API in the future. #121 now tracks this piece of work. + +- Bumped the minimum required Go version to 1.23 (#2059 by @pd93). +- [`task.InitTaskfile`](https://pkg.go.dev/github.com/go-task/task/v3#InitTaskfile) + (#2011, ff8c913 by @HeCorr and @pd93) + - No longer accepts an `io.Writer` (output is now the caller's + responsibility). + - The path argument can now be a filename OR a directory. + - The function now returns the full path of the generated file. +- [`TaskfileDecodeError.WithFileInfo`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskfileDecodeError.WithFileInfo) + now accepts a string instead of the arguments required to generate a snippet + (#2068 by @pd93). + - The caller is now expected to create the snippet themselves (see below). +- [`TaskfileSnippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet) + and related code moved from the `errors` package to the `taskfile` package + (#2068 by @pd93). +- Renamed `TaskMissingRequiredVars` to + [`TaskMissingRequiredVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskMissingRequiredVarsError) + (#2052 by @vmaerten). +- Renamed `TaskNotAllowedVars` to + [`TaskNotAllowedVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskNotAllowedVarsError) + (#2052 by @vmaerten). +- The + [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader) + is now constructed using the functional options pattern (#2082 by @pd93). +- Removed our internal `logger.Logger` from the entire `taskfile` package (#2082 + by @pd93). + - Users are now expected to pass a custom debug/prompt functions into + [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader) + if they want this functionality by using the new + [`WithDebugFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithDebugFunc) + and + [`WithPromptFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithPromptFunc) + functional options. +- Remove `Range` functions in the `taskfile/ast` package in favour of new + iterator functions (#1798 by @pd93). +- `ast.Call` was moved from the `taskfile/ast` package to the main `task` + package (#2084 by @pd93). +- `ast.Tasks.FindMatchingTasks` was moved from the `taskfile/ast` package to the + `task.Executor.FindMatchingTasks` in the main `task` package (#2084 by @pd93). +- The `Compiler` and its `GetVariables` and `FastGetVariables` methods were + moved from the `internal/compiler` package to the main `task` package (#2084 + by @pd93). + ## v3.41.0 - 2025-01-18 - Fixed an issue where dynamic variables were not properly logged in verbose diff --git a/website/versioned_docs/version-latest/changelog.mdx b/website/versioned_docs/version-latest/changelog.mdx index ff72992f..d326b9b8 100644 --- a/website/versioned_docs/version-latest/changelog.mdx +++ b/website/versioned_docs/version-latest/changelog.mdx @@ -5,6 +5,89 @@ sidebar_position: 14 # Changelog +## v3.42.0 - 2025-03-08 + +- Made `--init` less verbose by default and respect `--silent` and `--verbose` + flags (#2009, #2011 by @HeCorr). +- `--init` now accepts a file name or directory as an argument (#2008, #2018 by + @HeCorr). +- Fix a bug where an HTTP node's location was being mutated incorrectly (#2007 + by @jeongukjae). +- Fixed a bug where allowed values didn't work with dynamic var (#2032, #2033 by + @vmaerten). +- Use only the relevant checker (timestamp or checksum) to improve performance + (#2029, #2031 by @vmaerten). +- Print warnings when attempting to enable an inactive experiment or an active + experiment with an invalid value (#1979, #2049 by @pd93). +- Refactored the experiments package and added tests (#2049 by @pd93). +- Show allowed values when a variable with an enum is missing (#2027, #2052 by + @vmaerten). +- Refactored how snippets in error work and added tests (#2068 by @pd93). +- Fixed a bug where errors decoding commands were sometimes unhelpful (#2068 by + @pd93). +- Fixed a bug in the Taskfile schema where `defer` statements in the shorthand + `cmds` syntax were not considered valid (#2068 by @pd93). +- Refactored how task sorting functions work (#1798 by @pd93). +- Added a new `.taskrc.yml` (or `.taskrc.yaml`) file to let users enable + experiments (similar to `.env`) (#1982 by @vmaerten). +- Added new [Getting Started docs](https://taskfile.dev/getting-started) (#2086 + by @pd93). +- Allow `matrix` to use references to other variables (#2065, #2069 by @pd93). +- Fixed a bug where, when a dynamic variable is provided, even if it is not + used, all other variables become unavailable in the templating system within + the include (#2092 by @vmaerten). + +#### Package API + +Unlike our CLI tool, +[Task's package API is not currently stable](https://taskfile.dev/reference/package). +In an effort to ease the pain of breaking changes for our users, we will be +providing changelogs for our package API going forwards. The hope is that these +changes will provide a better long-term experience for our users and allow to +stabilize the API in the future. #121 now tracks this piece of work. + +- Bumped the minimum required Go version to 1.23 (#2059 by @pd93). +- [`task.InitTaskfile`](https://pkg.go.dev/github.com/go-task/task/v3#InitTaskfile) + (#2011, ff8c913 by @HeCorr and @pd93) + - No longer accepts an `io.Writer` (output is now the caller's + responsibility). + - The path argument can now be a filename OR a directory. + - The function now returns the full path of the generated file. +- [`TaskfileDecodeError.WithFileInfo`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskfileDecodeError.WithFileInfo) + now accepts a string instead of the arguments required to generate a snippet + (#2068 by @pd93). + - The caller is now expected to create the snippet themselves (see below). +- [`TaskfileSnippet`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Snippet) + and related code moved from the `errors` package to the `taskfile` package + (#2068 by @pd93). +- Renamed `TaskMissingRequiredVars` to + [`TaskMissingRequiredVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskMissingRequiredVarsError) + (#2052 by @vmaerten). +- Renamed `TaskNotAllowedVars` to + [`TaskNotAllowedVarsError`](https://pkg.go.dev/github.com/go-task/task/v3/errors#TaskNotAllowedVarsError) + (#2052 by @vmaerten). +- The + [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader) + is now constructed using the functional options pattern (#2082 by @pd93). +- Removed our internal `logger.Logger` from the entire `taskfile` package (#2082 + by @pd93). + - Users are now expected to pass a custom debug/prompt functions into + [`taskfile.Reader`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#Reader) + if they want this functionality by using the new + [`WithDebugFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithDebugFunc) + and + [`WithPromptFunc`](https://pkg.go.dev/github.com/go-task/task/v3/taskfile#WithPromptFunc) + functional options. +- Remove `Range` functions in the `taskfile/ast` package in favour of new + iterator functions (#1798 by @pd93). +- `ast.Call` was moved from the `taskfile/ast` package to the main `task` + package (#2084 by @pd93). +- `ast.Tasks.FindMatchingTasks` was moved from the `taskfile/ast` package to the + `task.Executor.FindMatchingTasks` in the main `task` package (#2084 by @pd93). +- The `Compiler` and its `GetVariables` and `FastGetVariables` methods were + moved from the `internal/compiler` package to the main `task` package (#2084 + by @pd93). + ## v3.41.0 - 2025-01-18 - Fixed an issue where dynamic variables were not properly logged in verbose diff --git a/website/versioned_docs/version-latest/community.mdx b/website/versioned_docs/version-latest/community.mdx index 316b4a17..a0d49b7c 100644 --- a/website/versioned_docs/version-latest/community.mdx +++ b/website/versioned_docs/version-latest/community.mdx @@ -1,6 +1,6 @@ --- slug: /community/ -sidebar_position: 9 +sidebar_position: 10 --- # Community diff --git a/website/versioned_docs/version-latest/contributing.mdx b/website/versioned_docs/version-latest/contributing.mdx index 2c820ffd..546129de 100644 --- a/website/versioned_docs/version-latest/contributing.mdx +++ b/website/versioned_docs/version-latest/contributing.mdx @@ -1,6 +1,6 @@ --- slug: /contributing/ -sidebar_position: 11 +sidebar_position: 12 --- # Contributing diff --git a/website/versioned_docs/version-latest/deprecations/deprecations.mdx b/website/versioned_docs/version-latest/deprecations/deprecations.mdx index aa5011a8..f09a95cb 100644 --- a/website/versioned_docs/version-latest/deprecations/deprecations.mdx +++ b/website/versioned_docs/version-latest/deprecations/deprecations.mdx @@ -1,6 +1,6 @@ --- slug: /deprecations/ -sidebar_position: 7 +sidebar_position: 8 --- # Deprecations diff --git a/website/versioned_docs/version-latest/experiments/experiments.mdx b/website/versioned_docs/version-latest/experiments/experiments.mdx index 8a665ce8..a3284ff8 100644 --- a/website/versioned_docs/version-latest/experiments/experiments.mdx +++ b/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. + + + + ```yaml title=".taskrc.yml" + experiments: + FEATURE: 1 + ``` + + + + ```shell title=".env" + TASK_X_FEATURE=1 + ``` + + ## Workflow diff --git a/website/versioned_docs/version-latest/getting_started.mdx b/website/versioned_docs/version-latest/getting_started.mdx new file mode 100644 index 00000000..bef3482e --- /dev/null +++ b/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 */} diff --git a/website/versioned_docs/version-latest/integrations.mdx b/website/versioned_docs/version-latest/integrations.mdx index 3f2364c8..bf1f8e69 100644 --- a/website/versioned_docs/version-latest/integrations.mdx +++ b/website/versioned_docs/version-latest/integrations.mdx @@ -1,6 +1,6 @@ --- slug: /integrations/ -sidebar_position: 8 +sidebar_position: 9 --- # Integrations diff --git a/website/versioned_docs/version-latest/intro.mdx b/website/versioned_docs/version-latest/intro.mdx index 5a97531c..1791f670 100644 --- a/website/versioned_docs/version-latest/intro.mdx +++ b/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 @@ -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 */} diff --git a/website/versioned_docs/version-latest/reference/_category_.yml b/website/versioned_docs/version-latest/reference/_category_.yml index 3c6ca5c5..20a3c06b 100644 --- a/website/versioned_docs/version-latest/reference/_category_.yml +++ b/website/versioned_docs/version-latest/reference/_category_.yml @@ -1,2 +1,2 @@ -position: 4 +position: 5 label: Reference diff --git a/website/versioned_docs/version-latest/reference/cli.mdx b/website/versioned_docs/version-latest/reference/cli.mdx index e1963418..4afe84b8 100644 --- a/website/versioned_docs/version-latest/reference/cli.mdx +++ b/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.
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. diff --git a/website/versioned_docs/version-latest/styleguide.mdx b/website/versioned_docs/version-latest/styleguide.mdx index eaab37cc..1213e4a0 100644 --- a/website/versioned_docs/version-latest/styleguide.mdx +++ b/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. diff --git a/website/versioned_docs/version-latest/taskfile_versions.mdx b/website/versioned_docs/version-latest/taskfile_versions.mdx index 507715e8..23c8ac02 100644 --- a/website/versioned_docs/version-latest/taskfile_versions.mdx +++ b/website/versioned_docs/version-latest/taskfile_versions.mdx @@ -1,6 +1,6 @@ --- slug: /taskfile-versions/ -sidebar_position: 5 +sidebar_position: 6 --- # Taskfile Versions diff --git a/website/versioned_docs/version-latest/usage.mdx b/website/versioned_docs/version-latest/usage.mdx index d57a0ffe..0bfa5086 100644 --- a/website/versioned_docs/version-latest/usage.mdx +++ b/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: