diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ce33392f6..fa98f1c737 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## v3.37.0 - 2024-05-08 - Released the [Any Variables experiment](https://taskfile.dev/blog/any-variables), but diff --git a/package-lock.json b/package-lock.json index 883a977a33..42531b41d3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.36.0", + "version": "3.37.0", "lockfileVersion": 2, "requires": true, "packages": { diff --git a/package.json b/package.json index 351a9ef512..04112ae1c2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.36.0", + "version": "3.37.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 71b4559b0c..5163005f78 100644 --- a/website/docs/changelog.mdx +++ b/website/docs/changelog.mdx @@ -5,6 +5,27 @@ sidebar_position: 14 # Changelog +## v3.37.0 - 2024-05-08 + +- Released the + [Any Variables experiment](https://taskfile.dev/blog/any-variables), but + [_without support for maps_](https://github.com/go-task/task/issues/1415#issuecomment-2044756925) + (#1415, #1547 by @pd93). +- Refactored how Task reads, parses and merges Taskfiles using a DAG (#1563, + #1607 by @pd93). +- Fix a bug which stopped tasks from using `stdin` as input (#1593, #1623 by + @pd03). +- Fix error when a file or directory in the project contained a special char + like `&`, `(` or `)` (#1551, #1584 by @andreynering). +- Added alias `q` for template function `shellQuote` (#1601, #1603 by @vergenzt) +- Added support for `~` on ZSH completions (#1613 by @jwater7). +- Added the ability to pass variables by reference using Go template syntax when + the + [Map Variables experiment](https://taskfile.dev/experiments/map-variables/) is + enabled (#1612 by @pd93). +- Added support for environment variables in the templating engine in `includes` + (#1610 by @vmaerten). + ## v3.36.0 - 2024-04-08 - Added support for diff --git a/website/versioned_docs/version-latest/changelog.mdx b/website/versioned_docs/version-latest/changelog.mdx index 71b4559b0c..5163005f78 100644 --- a/website/versioned_docs/version-latest/changelog.mdx +++ b/website/versioned_docs/version-latest/changelog.mdx @@ -5,6 +5,27 @@ sidebar_position: 14 # Changelog +## v3.37.0 - 2024-05-08 + +- Released the + [Any Variables experiment](https://taskfile.dev/blog/any-variables), but + [_without support for maps_](https://github.com/go-task/task/issues/1415#issuecomment-2044756925) + (#1415, #1547 by @pd93). +- Refactored how Task reads, parses and merges Taskfiles using a DAG (#1563, + #1607 by @pd93). +- Fix a bug which stopped tasks from using `stdin` as input (#1593, #1623 by + @pd03). +- Fix error when a file or directory in the project contained a special char + like `&`, `(` or `)` (#1551, #1584 by @andreynering). +- Added alias `q` for template function `shellQuote` (#1601, #1603 by @vergenzt) +- Added support for `~` on ZSH completions (#1613 by @jwater7). +- Added the ability to pass variables by reference using Go template syntax when + the + [Map Variables experiment](https://taskfile.dev/experiments/map-variables/) is + enabled (#1612 by @pd93). +- Added support for environment variables in the templating engine in `includes` + (#1610 by @vmaerten). + ## v3.36.0 - 2024-04-08 - Added support for diff --git a/website/versioned_docs/version-latest/experiments/gentle_force.mdx b/website/versioned_docs/version-latest/experiments/gentle_force.mdx index ab3d52d3b2..5521303b0b 100644 --- a/website/versioned_docs/version-latest/experiments/gentle_force.mdx +++ b/website/versioned_docs/version-latest/experiments/gentle_force.mdx @@ -45,5 +45,5 @@ if you want to adopt the new behavior, you can continue to use the `--force` flag as you do now! {/* prettier-ignore-start */} -[enabling-experiments]: /experiments/#enabling-experiments +[enabling-experiments]: ./experiments.mdx#enabling-experiments {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/experiments/any_variables.mdx b/website/versioned_docs/version-latest/experiments/map_variables.mdx similarity index 66% rename from website/versioned_docs/version-latest/experiments/any_variables.mdx rename to website/versioned_docs/version-latest/experiments/map_variables.mdx index be768d10df..5be75d523a 100644 --- a/website/versioned_docs/version-latest/experiments/any_variables.mdx +++ b/website/versioned_docs/version-latest/experiments/map_variables.mdx @@ -1,11 +1,11 @@ --- -slug: /experiments/any-variables/ +slug: /experiments/map-variables/ --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -# Any Variables (#1415) +# Map Variables (#1585) :::caution @@ -15,19 +15,9 @@ environment. They are intended for testing and feedback only. ::: -Currently, Task only supports string variables. This experiment allows you to -specify and use the following variable types: - -- `string` -- `bool` -- `int` -- `float` -- `array` -- `map` - -This allows you to have a lot more flexibility in how you use variables in -Task's templating engine. There are two active proposals for this experiment. -Click on the tabs below to switch between them. +Currently, Task supports all variable types except for maps. This experiment +adds two different proposals for map variables. Click on the tabs below to +switch between them. - :::info To enable this experiment, set the environment variable: -`TASK_X_ANY_VARIABLES=2`. Check out [our guide to enabling experiments +`TASK_X_MAP_VARIABLES=2`. Check out [our guide to enabling experiments ][enabling-experiments] for more information. ::: -## Maps - This proposal maintains backwards-compatibility and the `sh` subkey and adds another new `map` subkey for defining map variables: @@ -150,7 +135,13 @@ objects/arrays. This is similar to the `fromJSON` template function, but means that you only have to parse the JSON/YAML once when you declare the variable, instead of every time you want to access a value. -Before: + + + ```yaml version: 3 @@ -164,7 +155,8 @@ tasks: - 'echo {{(fromJSON .FOO).b}}' ``` -After: + + ```yaml version: 3 @@ -179,12 +171,26 @@ tasks: - 'echo {{.FOO.b}}' ``` + + ## Variables by reference Lastly, this proposal adds support for defining and passing variables by reference. This is really important now that variables can be types other than a -string. Previously, to send a variable from one task to another, you would have -to use the templating system to pass it: +string. + +Previously, to send a variable from one task to another, you would have to use +the templating system. Unfortunately, the templater _always_ outputs a string +and operations on the passed variable may not have behaved as expected. With +this proposal, you can now pass variables by reference using the `ref` subkey: + + + + ```yaml version: 3 @@ -202,10 +208,8 @@ tasks: - 'echo {{index .FOO 0}}' # <-- FOO is a string so the task outputs '91' which is the ASCII code for '[' instead of the expected 'A' ``` -Unfortunately, this results in the value always being passed as a string as this -is the output type of the templater and operations on the passed variable may -not behave as expected. With this proposal, you can now pass variables by -reference using the `ref` subkey: + + ```yaml version: 3 @@ -218,12 +222,14 @@ tasks: - task: bar vars: FOO: - ref: FOO # <-- FOO gets passed by reference to bar and maintains its type + ref: .FOO # <-- FOO gets passed by reference to bar and maintains its type bar: cmds: - 'echo {{index .FOO 0}}' # <-- FOO is still a map so the task outputs 'A' as expected ``` + + This means that the type of the variable is maintained when it is passed to another Task. This also works the same way when calling `deps` and when defining a variable and can be used in any combination: @@ -236,27 +242,20 @@ tasks: vars: FOO: [A, B, C] # <-- FOO is defined as an array BAR: - ref: FOO # <-- BAR is defined as a reference to FOO + ref: .FOO # <-- BAR is defined as a reference to FOO deps: - task: bar vars: BAR: - ref: BAR # <-- BAR gets passed by reference to bar and maintains its type + ref: .BAR # <-- BAR gets passed by reference to bar and maintains its type bar: cmds: - 'echo {{index .BAR 0}}' # <-- BAR still refers to FOO so the task outputs 'A' ``` - - ---- - -## Common to both proposals - -Both proposals add support for all other variable types by directly defining -them in the Taskfile. For example: - -### Evaluating booleans +All references use the same templating syntax as regular templates, so in +addition to simply calling `.FOO`, you can also pass subkeys (`.FOO.BAR`) or +indexes (`index .FOO 0`) and use functions (`len .FOO`): ```yaml version: 3 @@ -264,46 +263,33 @@ version: 3 tasks: foo: vars: - BOOL: false + FOO: [A, B, C] # <-- FOO is defined as an array cmds: - - '{{if .BOOL}}echo foo{{end}}' -``` - -### Arithmetic - -```yaml -version: 3 - -tasks: - foo: - vars: - INT: 10 - FLOAT: 3.14159 + - task: bar + vars: + FOO: + ref: index .FOO 0 # <-- The element at index 0 is passed by reference to bar + bar: cmds: - - 'echo {{add .INT .FLOAT}}' + - 'echo {{.MYVAR}}' # <-- FOO is just the letter 'A' ``` -### Ranging - -```yaml -version: 3 + -tasks: - foo: - vars: - ARRAY: [1, 2, 3] - cmds: - - 'echo {{range .ARRAY}}{{.}}{{end}}' -``` +## Looping over maps -There are many more templating functions which can be used with the new types of -variables. For a full list, see the [slim-sprig][slim-sprig] documentation. +This experiment also adds support for looping over maps using the `for` keyword, +just like arrays. In addition to the `{{.ITEM}}` variable being populated when +looping over a map, we also make an additional `{{.KEY}}` variable available +that holds the string value of the map key. -## Looping over variables + -Previously, you would have to use a delimiter separated string to loop over an -arbitrary list of items in a variable and split them by using the `split` subkey -to specify the delimiter: + ```yaml version: 3 @@ -311,17 +297,15 @@ version: 3 tasks: foo: vars: - LIST: 'foo,bar,baz' + MAP: {a: 1, b: 2, c: 3} cmds: - for: - var: LIST - split: ',' - cmd: echo {{.ITEM}} + var: MAP + cmd: 'echo "{{.KEY}}: {{.ITEM}}"' ``` -Both of these proposals add support for looping over "collection-type" variables -using the `for` keyword, so now you are able to loop over a map/array variable -directly: + + ```yaml version: 3 @@ -329,18 +313,23 @@ version: 3 tasks: foo: vars: - LIST: [foo, bar, baz] + map: + MAP: {a: 1, b: 2, c: 3} cmds: - for: - var: LIST - cmd: echo {{.ITEM}} + var: MAP + cmd: 'echo "{{.KEY}}: {{.ITEM}}"' ``` -When looping over a map we also make an additional `{{.KEY}}` variable availabe -that holds the string value of the map key. Remember that maps are unordered, so +:::note + +Remember that maps are unordered, so the order in which the items are looped over is random. +::: + + + {/* prettier-ignore-start */} -[enabling-experiments]: /experiments/#enabling-experiments -[slim-sprig]: https://go-task.github.io/slim-sprig/ +[enabling-experiments]: ./experiments.mdx#enabling-experiments {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx b/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx index 742b451c67..a1259b7621 100644 --- a/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx +++ b/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx @@ -48,6 +48,20 @@ tasks: and you run `task my-remote-namespace:hello`, it will print the text: "Hello from the remote Taskfile!" to your console. +The Taskfile location is processed by the templating system, so you can +reference environment variables in your URL if you need to add authentication. +For example: + +```yaml +version: '3' + +includes: + my-remote-namespace: https://{{.TOKEN}}@raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml +``` + +`TOKEN=my-token task my-remote-namespace:hello` will be resolved by Task to +`https://my-token@raw.githubusercontent.com/my-org/my-repo/main/Taskfile.yml` + ## Security Running commands from sources that you do not control is always a potential @@ -99,6 +113,6 @@ the `--timeout` flag and specifying a duration. For example, `--timeout 5s` will set the timeout to 5 seconds. {/* prettier-ignore-start */} -[enabling-experiments]: /experiments/#enabling-experiments +[enabling-experiments]: ./experiments.mdx#enabling-experiments [man-in-the-middle-attacks]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/experiments/template.mdx b/website/versioned_docs/version-latest/experiments/template.mdx index fca9a527c2..f1bb9887df 100644 --- a/website/versioned_docs/version-latest/experiments/template.mdx +++ b/website/versioned_docs/version-latest/experiments/template.mdx @@ -38,5 +38,5 @@ information. \{Short explanation of how users should migrate to the new behavior\} {/* prettier-ignore-start */} -[enabling-experiments]: /experiments/#enabling-experiments +[enabling-experiments]: ./experiments.mdx#enabling-experiments {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/installation.mdx b/website/versioned_docs/version-latest/installation.mdx index ac5e063df0..94dd42cacf 100644 --- a/website/versioned_docs/version-latest/installation.mdx +++ b/website/versioned_docs/version-latest/installation.mdx @@ -31,7 +31,7 @@ brew install go-task ### pkgx -If you're on macOS or Linux and have [pkgx](https://pkgx.sh/) installed, getting Task is as +If you're on macOS or Linux and have [pkgx][pkgx] installed, getting Task is as simple as running: ```shell @@ -299,5 +299,5 @@ Invoke-Expression -Command path/to/task.ps1 [godownloader]: https://github.com/goreleaser/godownloader [choco]: https://chocolatey.org/ [scoop]: https://scoop.sh/ -[tea]: https://tea.xyz/ +[pkgx]: https://pkgx.sh/ {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/taskfile_versions.mdx b/website/versioned_docs/version-latest/taskfile_versions.mdx index 0b08072645..b85a6f7a59 100644 --- a/website/versioned_docs/version-latest/taskfile_versions.mdx +++ b/website/versioned_docs/version-latest/taskfile_versions.mdx @@ -256,8 +256,8 @@ The variable priority order was also different: 4. `Taskvars.yml` variables {/* prettier-ignore-start */} -[deprecate-version-2-schema]: /deprecations/version-2-schema/ -[output]: /usage#output-syntax -[ignore_errors]: /usage#ignore-errors -[includes]: /usage#including-other-taskfiles +[deprecate-version-2-schema]: ./deprecations/version_2_schema.mdx +[output]: ./usage.mdx#output-syntax +[ignore_errors]: ./usage.mdx#ignore-errors +[includes]: ./usage.mdx#including-other-taskfiles {/* prettier-ignore-end */} diff --git a/website/versioned_docs/version-latest/usage.mdx b/website/versioned_docs/version-latest/usage.mdx index 718744f5b5..b5088ce87d 100644 --- a/website/versioned_docs/version-latest/usage.mdx +++ b/website/versioned_docs/version-latest/usage.mdx @@ -121,13 +121,14 @@ tasks: ### Reading a Taskfile from stdin Taskfile also supports reading from stdin. This is useful if you are generating -Taskfiles dynamically and don't want write them to disk. This works just like -any other program that supports stdin. For example: +Taskfiles dynamically and don't want write them to disk. To tell task to read +from stdin, you must specify the `-t/--taskfile` flag with the special `-` +value. You may then pipe into Task as you would any other program: ```shell -task < <(cat ./Taskfile.yml) +task -t - <(cat ./Taskfile.yml) # OR -cat ./Taskfile.yml | task +cat ./Taskfile.yml | task -t - ``` ## Environment variables @@ -947,8 +948,26 @@ tasks: ## Variables -When doing interpolation of variables, Task will look for the below. They are -listed below in order of importance (i.e. most important first): +Task allows you to set variables using the `vars` keyword. The following +variable types are supported: + +- `string` +- `bool` +- `int` +- `float` +- `array` + +:::note + +Maps are not supported by default, but there is an +[experiment][map-variables] that can be enabled to add support. If +you're interested in this functionality, we would appreciate your feedback. +:pray: + +::: + +Variables can be set in many places in a Taskfile. When executing templates, +Task will look for variables in the order listed below (most important first): - Variables declared in the task definition - Variables given while calling a task from another (See @@ -1093,8 +1112,8 @@ tasks: ### Looping over variables To loop over the contents of a variable, you simply need to specify the variable -you want to loop over. By default, variables will be split on any whitespace -characters. +you want to loop over. By default, string variables will be split on any +whitespace characters. ```yaml version: '3' @@ -1108,8 +1127,8 @@ tasks: cmd: cat {{.ITEM}} ``` -If you need to split on a different character, you can do this by specifying the -`split` property: +If you need to split a string on a different character, you can do this by +specifying the `split` property: ```yaml version: '3' @@ -1123,6 +1142,26 @@ tasks: cmd: cat {{.ITEM}} ``` +You can also loop over arrays directly (and maps if you have the +[maps experiment](/experiments/map-variables) enabled): + +```yaml +version: 3 + +tasks: + foo: + vars: + LIST: [foo, bar, baz] + cmds: + - for: + var: LIST + cmd: echo {{.ITEM}} +``` + +When looping over a map we also make an additional `{{.KEY}}` variable available +that holds the string value of the map key. Remember that maps are unordered, so +the order in which the items are looped over is random. + All of this also works with dynamic variables! ```yaml @@ -1956,4 +1995,5 @@ if called by another task, either directly or as a dependency. {/* prettier-ignore-start */} [gotemplate]: https://golang.org/pkg/text/template/ +[map-variables]: ./experiments/map_variables.mdx {/* prettier-ignore-end */}