From d8e176311d323f79fbf4de1557614c9d70f5b5f0 Mon Sep 17 00:00:00 2001 From: Andrey Nering Date: Tue, 5 Nov 2024 22:34:38 -0300 Subject: [PATCH] v3.40.0 --- CHANGELOG.md | 2 +- package-lock.json | 2 +- package.json | 2 +- website/docs/changelog.mdx | 28 +++++++ .../version-latest/changelog.mdx | 28 +++++++ .../experiments/remote_taskfiles.mdx | 10 +++ .../version-latest/reference/cli.mdx | 39 +++++----- .../version-latest/reference/environment.mdx | 13 ++-- .../version-latest/reference/schema.mdx | 2 +- .../version-latest/reference/templating.mdx | 4 +- .../versioned_docs/version-latest/usage.mdx | 74 +++++++++++++++++++ 11 files changed, 174 insertions(+), 30 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3b4d08fc..e79c1428 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Changelog -## Unreleased +## v3.40.0 - 2024-11-05 - Fixed output of some functions (e.g. `splitArgs`/`splitLines`) not working in for loops (#1822, #1823 by @stawii). diff --git a/package-lock.json b/package-lock.json index 9d7efe1a..d8d92249 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.39.2", + "version": "3.40.0", "lockfileVersion": 2, "requires": true, "packages": { diff --git a/package.json b/package.json index 00f849e7..ccbfe40a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@go-task/cli", - "version": "3.39.2", + "version": "3.40.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 368437c8..cb03c147 100644 --- a/website/docs/changelog.mdx +++ b/website/docs/changelog.mdx @@ -5,6 +5,34 @@ sidebar_position: 14 # Changelog +## v3.40.0 - 2024-11-05 + +- Fixed output of some functions (e.g. `splitArgs`/`splitLines`) not working in + for loops (#1822, #1823 by @stawii). +- Added a new `TASK_OFFLINE` environment variable to configure the `--offline` + flag and expose it as a special variable in the templating system (#1470, + #1716 by @vmaerten and @pd93). +- Fixed a bug where multiple remote includes caused all prompts to display + without waiting for user input (#1832, #1833 by @vmaerten and @pd93). +- When using the + "[Remote Taskfiles](https://taskfile.dev/experiments/remote-taskfiles/)". + experiment, you can now include Taskfiles from Git repositories (#1652 by + @vmaerten). +- Improved the error message when a dotenv file cannot be parsed (#1842 by + @pbitty). +- Fix issue with directory when using the remote experiment (#1757 by @pbitty). +- Fixed an issue where a special variable was used in combination with a dotenv + file (#1232, #1810 by @vmaerten). +- Refactor the way Task reads Taskfiles to improve readability (#1771 by + @pbitty). +- Added a new option to ensure variable is within the list of values (#1827 by + @vmaerten). +- Allow multiple prompts to be specified for a task (#1861, #1866 by @mfbmina). +- Added new template function: `numCPU`, which returns the number of logical + CPUs usable (#1890, #1887 by @Amoghrd). +- Fixed a bug where non-nil, empty dynamic variables are returned as an empty + interface (#1903, #1904 by @pd93). + ## v3.39.2 - 2024-09-19 - Fix dynamic variables not working properly for a defer: statement (#1803, diff --git a/website/versioned_docs/version-latest/changelog.mdx b/website/versioned_docs/version-latest/changelog.mdx index 368437c8..cb03c147 100644 --- a/website/versioned_docs/version-latest/changelog.mdx +++ b/website/versioned_docs/version-latest/changelog.mdx @@ -5,6 +5,34 @@ sidebar_position: 14 # Changelog +## v3.40.0 - 2024-11-05 + +- Fixed output of some functions (e.g. `splitArgs`/`splitLines`) not working in + for loops (#1822, #1823 by @stawii). +- Added a new `TASK_OFFLINE` environment variable to configure the `--offline` + flag and expose it as a special variable in the templating system (#1470, + #1716 by @vmaerten and @pd93). +- Fixed a bug where multiple remote includes caused all prompts to display + without waiting for user input (#1832, #1833 by @vmaerten and @pd93). +- When using the + "[Remote Taskfiles](https://taskfile.dev/experiments/remote-taskfiles/)". + experiment, you can now include Taskfiles from Git repositories (#1652 by + @vmaerten). +- Improved the error message when a dotenv file cannot be parsed (#1842 by + @pbitty). +- Fix issue with directory when using the remote experiment (#1757 by @pbitty). +- Fixed an issue where a special variable was used in combination with a dotenv + file (#1232, #1810 by @vmaerten). +- Refactor the way Task reads Taskfiles to improve readability (#1771 by + @pbitty). +- Added a new option to ensure variable is within the list of values (#1827 by + @vmaerten). +- Allow multiple prompts to be specified for a task (#1861, #1866 by @mfbmina). +- Added new template function: `numCPU`, which returns the number of logical + CPUs usable (#1890, #1887 by @Amoghrd). +- Fixed a bug where non-nil, empty dynamic variables are returned as an empty + interface (#1903, #1904 by @pd93). + ## v3.39.2 - 2024-09-19 - Fix dynamic variables not working properly for a defer: statement (#1803, diff --git a/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx b/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx index 8a85ccd0..45e6617e 100644 --- a/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx +++ b/website/versioned_docs/version-latest/experiments/remote_taskfiles.mdx @@ -62,6 +62,16 @@ includes: `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` +## Git nodes + +You can also include a Taskfile from a Git node. We currently support ssh-style and http / https addresses like `git@example.com/foo/bar.git//Taskfiles.yml?ref=v1` and `https://example.com/foo/bar.git//Taskfiles.yml?ref=v1`. + +You need to follow this pattern : `.git//?ref=`. +The `ref` parameter, optional, can be a branch name or a tag, if not provided it'll pick up the default branch. +The `path` is the path to the Taskfile in the repository. + +If you want to use the SSH protocol, you need to make sure that your ssh-agent has your private ssh keys added so that they can be used during authentication. + ## Security Running commands from sources that you do not control is always a potential diff --git a/website/versioned_docs/version-latest/reference/cli.mdx b/website/versioned_docs/version-latest/reference/cli.mdx index 9beb1a83..893236d1 100644 --- a/website/versioned_docs/version-latest/reference/cli.mdx +++ b/website/versioned_docs/version-latest/reference/cli.mdx @@ -62,25 +62,26 @@ four groups with the following ranges: A full list of the exit codes and their descriptions can be found below: -| Code | Description | -| ---- | ------------------------------------------------------------ | -| 0 | Success | -| 1 | An unknown error occurred | -| 100 | No Taskfile was found | -| 101 | A Taskfile already exists when trying to initialize one | -| 102 | The Taskfile is invalid or cannot be parsed | -| 103 | A remote Taskfile could not be downloaded | -| 104 | A remote Taskfile was not trusted by the user | -| 105 | A remote Taskfile was could not be fetched securely | -| 106 | No cache was found for a remote Taskfile in offline mode | -| 107 | No schema version was defined in the Taskfile | -| 200 | The specified task could not be found | -| 201 | An error occurred while executing a command inside of a task | -| 202 | The user tried to invoke a task that is internal | -| 203 | There a multiple tasks with the same name or alias | -| 204 | A task was called too many times | -| 205 | A task was cancelled by the user | -| 206 | A task was not executed due to missing required variables | +| Code | Description | +|------|---------------------------------------------------------------------| +| 0 | Success | +| 1 | An unknown error occurred | +| 100 | No Taskfile was found | +| 101 | A Taskfile already exists when trying to initialize one | +| 102 | The Taskfile is invalid or cannot be parsed | +| 103 | A remote Taskfile could not be downloaded | +| 104 | A remote Taskfile was not trusted by the user | +| 105 | A remote Taskfile was could not be fetched securely | +| 106 | No cache was found for a remote Taskfile in offline mode | +| 107 | No schema version was defined in the Taskfile | +| 200 | The specified task could not be found | +| 201 | An error occurred while executing a command inside of a task | +| 202 | The user tried to invoke a task that is internal | +| 203 | There a multiple tasks with the same name or alias | +| 204 | A task was called too many times | +| 205 | A task was cancelled by the user | +| 206 | A task was not executed due to missing required variables | +| 207 | A task was not executed due to a variable having an incorrect value | These codes can also be found in the repository in [`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go). diff --git a/website/versioned_docs/version-latest/reference/environment.mdx b/website/versioned_docs/version-latest/reference/environment.mdx index ce9b7334..40ccfb63 100644 --- a/website/versioned_docs/version-latest/reference/environment.mdx +++ b/website/versioned_docs/version-latest/reference/environment.mdx @@ -8,16 +8,17 @@ sidebar_position: 4 Task allows you to configure some behavior using environment variables. This page lists all the environment variables that Task supports. -| ENV | Default | Description | -| ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. | -| `TASK_REMOTE_DIR` | `TASK_TEMP_DIR` | Location of the remote temp dir (used for caching). Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. | -| `FORCE_COLOR` | | Force color output usage. | +| ENV | Default | Description | +|-------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| `TASK_TEMP_DIR` | `.task` | Location of the temp dir. Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. | +| `TASK_REMOTE_DIR` | `TASK_TEMP_DIR` | Location of the remote temp dir (used for caching). Can relative to the project like `tmp/task` or absolute like `/tmp/.task` or `~/.task`. | +| `TASK_OFFLINE` | `false` | Set the `--offline` flag through the environment variable. Only for remote experiment. CLI flag `--offline` takes precedence over the env variable | +| `FORCE_COLOR` | | Force color output usage. | ## Custom Colors | ENV | Default | Description | -| --------------------------- | ------- | ----------------------- | +|-----------------------------|---------|-------------------------| | `TASK_COLOR_RESET` | `0` | Color used for white. | | `TASK_COLOR_RED` | `31` | Color used for red. | | `TASK_COLOR_GREEN` | `32` | Color used for green. | diff --git a/website/versioned_docs/version-latest/reference/schema.mdx b/website/versioned_docs/version-latest/reference/schema.mdx index e67a033c..7066f545 100644 --- a/website/versioned_docs/version-latest/reference/schema.mdx +++ b/website/versioned_docs/version-latest/reference/schema.mdx @@ -88,7 +88,7 @@ vars: | `deps` | [`[]Dependency`](#dependency) | | A list of dependencies of this task. Tasks defined here will run in parallel before this task. | | `label` | `string` | | Overrides the name of the task in the output when a task is run. Supports variables. | | `desc` | `string` | | A short description of the task. This is displayed when calling `task --list`. | -| `prompt` | `string` | | A prompt that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks. | +| `prompt` | `[]string` | | One or more prompts that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks. | | `summary` | `string` | | A longer description of the task. This is displayed when calling `task --summary [task]`. | | `aliases` | `[]string` | | A list of alternative names by which the task can be called. | | `sources` | `[]string` | | A list of sources to check before running this task. Relevant for `checksum` and `timestamp` methods. Can be file paths or star globs. | diff --git a/website/versioned_docs/version-latest/reference/templating.mdx b/website/versioned_docs/version-latest/reference/templating.mdx index 33df58e8..468a4333 100644 --- a/website/versioned_docs/version-latest/reference/templating.mdx +++ b/website/versioned_docs/version-latest/reference/templating.mdx @@ -106,6 +106,7 @@ special variable will be overridden. | `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. | +| `CLI_OFFLINE` | A boolean containing whether the `--offline` 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. | @@ -373,7 +374,8 @@ Lastly, Task itself provides a few functions: | Function | Description | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OS` | Returns the operating system. Possible values are `windows`, `linux`, `darwin` (macOS) and `freebsd`. | -| `ARCH` | return the architecture Task was compiled to: `386`, `amd64`, `arm` or `s390x`. | +| `ARCH` | Returns the architecture Task was compiled to: `386`, `amd64`, `arm` or `s390x`. | +| `numCPU` | Returns the number of logical CPU's usable by the current process. | | `splitLines` | Splits Unix (`\n`) and Windows (`\r\n`) styled newlines. | | `catLines` | Replaces Unix (`\n`) and Windows (`\r\n`) styled newlines with a space. | | `toSlash` | Does nothing on Unix, but on Windows converts a string from `\` path format to `/`. | diff --git a/website/versioned_docs/version-latest/usage.mdx b/website/versioned_docs/version-latest/usage.mdx index e05f7268..7a7811d5 100644 --- a/website/versioned_docs/version-latest/usage.mdx +++ b/website/versioned_docs/version-latest/usage.mdx @@ -1060,6 +1060,40 @@ tasks: vars: [IMAGE_NAME, IMAGE_TAG] ``` +### Ensuring required variables have allowed values + +If you want to ensure that a variable is set to one of a predefined set of valid values before executing a task, you can use requires. +This is particularly useful when there are strict requirements for what values a variable can take, and you want to provide clear feedback to the user when an invalid value is detected. + +To use `requires`, you specify an array of allowed values in the vars sub-section under requires. Task will check if the variable is set to one of the allowed values. +If the variable does not match any of these values, the task will raise an error and stop execution. + +This check applies both to user-defined variables and environment variables. + +Example of using `requires`: + +```yaml +version: '3' + +tasks: + deploy: + cmds: + - echo "deploying to {{.ENV}}" + + requires: + vars: + - name: ENV + enum: [dev, beta, prod] +``` + +If `ENV` is not one of 'dev', 'beta' or 'prod' an error will be raised. + +:::note + +This is supported only for string variables. + +::: + ## Variables Task allows you to set variables using the `vars` keyword. The following @@ -1178,6 +1212,28 @@ tasks: - echo "{{.GREETING}}" ``` +Example of a `default` value to be overriden from CLI: + +```yaml +version: '3' + + greet_user: + desc: "Greet the user with a name." + vars: + USER_NAME: '{{.USER_NAME| default "DefaultUser"}}' + cmds: + - echo "Hello, {{.USER_NAME}}!" +``` + +```shell +$ task greet_user +task: [greet_user] echo "Hello, DefaultUser!" +Hello, DefaultUser! +$ task greet_user USER_NAME="Bob" +task: [greet_user] echo "Hello, Bob!" +Hello, Bob! +``` + ### Dynamic variables The below syntax (`sh:` prop in a variable) is considered a dynamic variable. @@ -1844,6 +1900,24 @@ tasks: task: "This is a dangerous command... Do you want to continue?" [y/N] ``` +Prompts can be a single value or a list of prompts, like below: + +```yaml +version: '3' + +tasks: + example: + cmds: + - task: dangerous + + dangerous: + prompt: + - This is a dangerous command... Do you want to continue? + - Are you sure? + cmds: + - echo 'dangerous command' +``` + Warning prompts are called before executing a task. If a prompt is denied Task will exit with [exit code](/api#exit-codes) 205. If approved, Task will continue as normal.