go/task
go/task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2024-12-04 10:24:45 +02:00
Code Issues Releases Activity

v3.39.0

Browse Source
This commit is contained in:
Pete Davison 2024-09-07 20:05:46 +00:00
parent 0c05dcbe0f
commit 1275ab1b5b
No known key found for this signature in database
11 changed files with 392 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -1,6 +1,6 @@
# Changelog
## Unreleased
## v3.39.0 - 2024-09-07
- Added
[Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence)

2
package-lock.json generated
View File

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

2
package.json
View File

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

31
website/docs/changelog.mdx
View File

@ -5,6 +5,37 @@ sidebar_position: 14
# Changelog
## v3.39.0 - 2024-09-07
- Added
[Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence)
(#1038, #1633 by @vmaerten).
- Added a CI lint job to ensure that the docs are updated correctly (#1719 by
@vmaerten).
- Updated minimum required Go version to 1.22 (#1758 by @pd93).
- Expose a new `EXIT_CODE` special variable on `defer:` when a command finishes
with a non-zero exit code (#1484, #1762 by @dorimon-1 and @andreynering).
- Expose a new `ALIAS` special variable, which will contain the alias used to
call the current task. Falls back to the task name. (#1764 by @DanStory).
- Fixed `TASK_REMOTE_DIR` environment variable not working when the path was
absolute. (#1715 by @vmaerten).
- Added an option to declare an included Taskfile as flattened (#1704 by
@vmaerten).
- Added a new
[`--completion` flag](https://taskfile.dev/installation/#setup-completions) to
output completion scripts for various shells (#293, #1157 by @pd93).
- This is now the preferred way to install completions.
- The completion scripts in the `completion` directory
[are now deprecated](https://taskfile.dev/deprecations/completion-scripts/).
- Added the ability to
[loop over a matrix of values](https://taskfile.dev/usage/#looping-over-a-matrix)
(#1766, #1767, #1784 by @pd93).
- Fixed a bug in fish completion where aliases were not displayed (#1781, #1782
by @vmaerten).
- Fixed panic when having a flattened included Taskfile that contains a
`default` task (#1777, #1778 by @vmaerten).
- Optimized file existence checks for remote Taskfiles (#1713 by @vmaerten).
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).

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

@ -5,6 +5,37 @@ sidebar_position: 14
# Changelog
## v3.39.0 - 2024-09-07
- Added
[Env Precedence Experiment](https://taskfile.dev/experiments/env-precedence)
(#1038, #1633 by @vmaerten).
- Added a CI lint job to ensure that the docs are updated correctly (#1719 by
@vmaerten).
- Updated minimum required Go version to 1.22 (#1758 by @pd93).
- Expose a new `EXIT_CODE` special variable on `defer:` when a command finishes
with a non-zero exit code (#1484, #1762 by @dorimon-1 and @andreynering).
- Expose a new `ALIAS` special variable, which will contain the alias used to
call the current task. Falls back to the task name. (#1764 by @DanStory).
- Fixed `TASK_REMOTE_DIR` environment variable not working when the path was
absolute. (#1715 by @vmaerten).
- Added an option to declare an included Taskfile as flattened (#1704 by
@vmaerten).
- Added a new
[`--completion` flag](https://taskfile.dev/installation/#setup-completions) to
output completion scripts for various shells (#293, #1157 by @pd93).
- This is now the preferred way to install completions.
- The completion scripts in the `completion` directory
[are now deprecated](https://taskfile.dev/deprecations/completion-scripts/).
- Added the ability to
[loop over a matrix of values](https://taskfile.dev/usage/#looping-over-a-matrix)
(#1766, #1767, #1784 by @pd93).
- Fixed a bug in fish completion where aliases were not displayed (#1781, #1782
by @vmaerten).
- Fixed panic when having a flattened included Taskfile that contains a
`default` task (#1777, #1778 by @vmaerten).
- Optimized file existence checks for remote Taskfiles (#1713 by @vmaerten).
## v3.38.0 - 2024-06-30
- Added `TASK_EXE` special variable (#1616, #1624 by @pd93 and @andreynering).

25
website/versioned_docs/version-latest/deprecations/completion_scripts.mdx Normal file
View File

@ -0,0 +1,25 @@
---
slug: /deprecations/completion-scripts/
---
# Completion Scripts
:::warning
This deprecation breaks the following functionality:
- Any direct references to the completion scripts in the Task git repository
:::
Direct use of the completion scripts in the `completion/*` directory of the
[github.com/go-task/task][task] Git repository is deprecated. Any shell
configuration that directly refers to these scripts will potentially break in
the future as the scripts may be moved or deleted entirely. Any configuration
should be updated to use the [new method for generating shell
completions][completions] instead.
{/* prettier-ignore-start */}
[completions]: ../installation.mdx#setup-completions
[task]: https://github.com/go-task/task
{/* prettier-ignore-end */}

74
website/versioned_docs/version-latest/experiments/env_precedence.mdx Normal file
View File

@ -0,0 +1,74 @@
---
slug: '/experiments/env-precedence'
---
# Env Precedence (#1038)
:::caution
All experimental features are subject to breaking changes and/or removal _at any
time_. We strongly recommend that you do not use these features in a production
environment. They are intended for testing and feedback only.
:::
:::warning
This experiment breaks the following functionality:
- environment variable will take precedence over OS environment variables
:::
:::info
To enable this experiment, set the environment variable:
`TASK_X_ENV_PRECEDENCE=1`. Check out [our guide to enabling
experiments][enabling-experiments] for more information.
:::
Before this experiment, the OS variable took precedence over the task
environment variable. This experiment changes the precedence to make the task
environment variable take precedence over the OS variable.
Consider the following example:
```yml
version: '3'
tasks:
default:
env:
KEY: 'other'
cmds:
- echo "$KEY"
```
Running `KEY=some task` before this experiment, the output would be `some`, but
after this experiment, the output would be `other`.
If you still want to get the OS variable, you can use the template function env
like follow : `{{env "OS_VAR"}}`.
```yml
version: '3'
tasks:
default:
env:
KEY: 'other'
cmds:
- echo "$KEY"
- echo {{env "KEY"}}
```
Running `KEY=some task`, the output would be `other` and `some`.
Like other variables/envs, you can also fall back to a given value using the
default template function:
```yml
MY_ENV: '{{.MY_ENV | default "fallback"}}'
```
{/* prettier-ignore-start */}
[enabling-experiments]: ./experiments.mdx#enabling-experiments
{/* prettier-ignore-end */}

106
website/versioned_docs/version-latest/installation.mdx
View File

@ -3,6 +3,9 @@ slug: /installation/
sidebar_position: 2
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Installation
Task offers many installation methods. Check out the available methods below.
@ -247,65 +250,76 @@ released binary.
## Setup completions
Download the autocompletion file corresponding to your shell.
Some installation methods will automatically install completions too, but if
this isn't working for you or your chosen method doesn't include them, you can
run `task --completion <shell>` to output a completion script for any supported
shell. There are a couple of ways these completions can be added to your shell
config:
[All completions are available on the Task repository](https://github.com/go-task/task/tree/main/completion).
### Option 1. Load the completions in your shell's startup config (Recommended)
### Bash
This method loads the completion script from the currently installed version of
task every time you create a new shell. This ensures that your completions are
always up-to-date.
First, ensure that you installed bash-completion using your package manager.
<Tabs values={[ {label: 'bash', value: '1'}, {label: 'zsh', value: '2'},
{label: 'fish', value: '3'},
{label: 'powershell', value: '4'}
]}>
Make the completion file executable:
<TabItem value="1">
```shell title="~/.bashrc"
eval "$(task --completion bash)"
```
</TabItem>
<TabItem value="2">
```shell title="~/.zshrc"
eval "$(task --completion zsh)"
```
</TabItem>
<TabItem value="3">
```shell title="~/.config/fish/config.fish"
task --completion fish | source
```
</TabItem>
<TabItem value="4">
```powershell title="$PROFILE\Microsoft.PowerShell_profile.ps1"
Invoke-Expression (&task --completion powershell)
```
</TabItem></Tabs>
### Option 2. Copy the script to your shell's completions directory
This method requires you to manually update the completions whenever Task is
updated. However, it is useful if you want to modify the completions yourself.
<Tabs
values={[
{label: 'bash', value: '1'},
{label: 'zsh', value: '2'},
{label: 'fish', value: '3'}
]}>
<TabItem value="1">
```shell
chmod +x path/to/task.bash
task --completion bash > /etc/bash_completion.d/task
```
</TabItem>
After, add this to your `~/.bash_profile`:
<TabItem value="2">
```shell
source path/to/task.bash
task --completion zsh > /usr/local/share/zsh/site-functions/_task
```
</TabItem>
### ZSH
Put the `_task` file somewhere in your `$FPATH`:
<TabItem value="3">
```shell
mv path/to/_task /usr/local/share/zsh/site-functions/_task
```
Ensure that the following is present in your `~/.zshrc`:
```shell
autoload -U compinit
compinit -i
```
ZSH version 5.7 or later is recommended.
### Fish
Move the `task.fish` completion script:
```shell
mv path/to/task.fish ~/.config/fish/completions/task.fish
```
### PowerShell
Open your profile script with:
```powershell
mkdir -Path (Split-Path -Parent $profile) -ErrorAction SilentlyContinue
notepad $profile
```
Add the line and save the file:
```shell
Invoke-Expression -Command path/to/task.ps1
task --completion fish > ~/.config/fish/completions/task.fish
```
</TabItem></Tabs>
{/* prettier-ignore-start */}
[go]: https://golang.org/

5
website/versioned_docs/version-latest/reference/schema.mdx
View File

@ -8,7 +8,7 @@ toc_max_heading_level: 5
# Schema Reference
| Attribute | Type | Default | Description |
| ---------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|------------|------------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `version` | `string` | | Version of the Taskfile. The current version is `3`. |
| `output` | `string` | `interleaved` | Output mode. Available options: `interleaved`, `group` and `prefixed`. |
| `method` | `string` | `checksum` | Default method in this Taskfile. Can be overridden in a task by task basis. Available options: `checksum`, `timestamp` and `none`. |
@ -26,10 +26,11 @@ toc_max_heading_level: 5
## Include
| Attribute | Type | Default | Description |
| ---------- | --------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|------------|-----------------------|-------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `taskfile` | `string` | | The path for the Taskfile or directory to be included. If a directory, Task will look for files named `Taskfile.yml` or `Taskfile.yaml` inside that directory. If a relative path, resolved relative to the directory containing the including Taskfile. |
| `dir` | `string` | The parent Taskfile directory | The working directory of the included tasks when run. |
| `optional` | `bool` | `false` | If `true`, no errors will be thrown if the specified file does not exist. |
| `flatten` | `bool` | `false` | If `true`, the tasks from the included Taskfile will be available in the including Taskfile without a namespace. If a task with the same name already exists in the including Taskfile, an error will be thrown. |
| `internal` | `bool` | `false` | Stops any task in the included Taskfile from being callable on the command line. These commands will also be omitted from the output when used with `--list`. |
| `aliases` | `[]string` | | Alternative names for the namespace of the included Taskfile. |
| `vars` | `map[string]Variable` | | A set of variables to apply to the included Taskfile. |

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

@ -101,10 +101,13 @@ engine. If you define a variable with the same name as a special variable, the
special variable will be overridden.
| Var | Description |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| `CLI_ARGS` | Contain all extra arguments passed after `--` when calling Task through the CLI. |
| `CLI_FORCE` | A boolean containing whether the `--force` or `--force-all` flags were set. |
| `CLI_SILENT` | A boolean containing whether the `--silent` flag was set. |
| `CLI_VERBOSE` | A boolean containing whether the `--verbose` flag was set. |
| `TASK` | The name of the current task. |
| `ALIAS` | The alias used for the current task, otherwise matches `TASK`. |
| `TASK_EXE` | The Task executable name or path. |
| `ROOT_TASKFILE` | The absolute path of the root Taskfile. |
| `ROOT_DIR` | The absolute path of the root Taskfile directory. |
@ -115,6 +118,7 @@ special variable will be overridden.
| `TIMESTAMP` | The date object of the greatest timestamp of the files listed in `sources`. Only available within the `status` prop and if method is set to `timestamp`. |
| `TASK_VERSION` | The current version of task. |
| `ITEM` | The value of the current iteration when using the `for` property. Can be changed to a different variable name using `as:`. |
| `EXIT_CODE` | Available exclusively inside the `defer:` command. Contains the failed command exit code. Only set when non-zero. |
## Functions

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

@ -334,6 +334,117 @@ includes:
internal: true
```
### Flatten includes
You can flatten the included Taskfile tasks into the main Taskfile by using the `flatten` option.
It means that the included Taskfile tasks will be available without the namespace.
<Tabs defaultValue="1"
values={[
{label: 'Taskfile.yml', value: '1'},
{label: 'Included.yml', value: '2'}
]}>
<TabItem value="1">
```yaml
version: '3'
includes:
lib:
taskfile: ./Included.yml
flatten: true
tasks:
greet:
cmds:
- echo "Greet"
- task: foo
```
</TabItem>
<TabItem value="2">
```yaml
version: '3'
tasks:
foo:
cmds:
- echo "Foo"
```
</TabItem></Tabs>
If you run `task -a` it will print :
```sh
task: Available tasks for this project:
* greet:
* foo
```
You can run `task foo` directly without the namespace.
You can also reference the task in other tasks without the namespace. So if you run `task greet` it will run `greet` and `foo` tasks and the output will be :
```text
```
If multiple tasks have the same name, an error will be thrown:
<Tabs defaultValue="1"
values={[
{label: 'Taskfile.yml', value: '1'},
{label: 'Included.yml', value: '2'}
]}>
<TabItem value="1">
```yaml
version: '3'
includes:
lib:
taskfile: ./Included.yml
flatten: true
tasks:
greet:
cmds:
- echo "Greet"
- task: foo
```
</TabItem>
<TabItem value="2">
```yaml
version: '3'
tasks:
greet:
cmds:
- echo "Foo"
```
</TabItem></Tabs>
If you run `task -a` it will print:
```text
task: Found multiple tasks (greet) included by "lib"
```
### Vars of included Taskfiles
You can also specify variables when including a Taskfile. This may be useful for
@ -1181,14 +1292,14 @@ tasks:
ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar
bar:
cmds:
- 'echo {{.MYVAR}}' # <-- FOO is just the letter 'A'
- 'echo {{.FOO}}' # <-- FOO is just the letter 'A'
```
## Looping over values
As of v3.28.0, Task allows you to loop over certain values and execute a command
for each. There are a number of ways to do this depending on the type of value
you want to loop over.
Task allows you to loop over certain values and execute a command for each.
There are a number of ways to do this depending on the type of value you want to
loop over.
### Looping over a static list
@ -1205,6 +1316,37 @@ tasks:
cmd: cat {{ .ITEM }}
```
### Looping over a matrix
If you need to loop over all permutations of multiple lists, you can use the
`matrix` property. This should be familiar to anyone who has used a matrix in a
CI/CD pipeline.
```yaml
version: '3'
tasks:
default:
silent: true
cmds:
- for:
matrix:
OS: ["windows", "linux", "darwin"]
ARCH: ["amd64", "arm64"]
cmd: echo "{{.ITEM.OS}}/{{.ITEM.ARCH}}"
```
This will output:
```txt
windows/amd64
windows/arm64
linux/amd64
linux/arm64
darwin/amd64
darwin/arm64
```
### Looping over your task's sources
You are also able to loop over the sources of your task:
@ -1520,6 +1662,20 @@ commands are executed in the reverse order if you schedule multiple of them.
:::
A special variable `.EXIT_CODE` is exposed when a command exited with a non-zero
exit code. You can check its presence to know if the task completed successfully
or not:
```yaml
version: '3'
tasks:
default:
cmds:
- defer: echo '{{if .EXIT_CODE}}Failed with {{.EXIT_CODE}}!{{else}}Success!{{end}}'
- exit 1
```
## Help
Running `task --list` (or `task -l`) lists all tasks with a description. The