rayan/go-task
1
0
Fork 0
mirror of https://github.com/go-task/task.git synced 2026-06-23 04:35:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add ability to specify which vars are required (#1204)

Browse Source
This commit is contained in:
Ben Coleman
2023-06-30 02:13:41 +01:00
committed by GitHub
parent f346015d8c
commit 307f39cee3
10 changed files with 165 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/docs/api_reference.md
View File

@@ -76,6 +76,7 @@ A full list of the exit codes and their descriptions can be found below:
| 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 |
These codes can also be found in the repository in
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
@@ -219,7 +220,9 @@ vars:
| `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. |
| `generates` | `[]string` | | A list of files meant to be generated by this task. Relevant for `timestamp` method. Can be file paths or star globs. |
| `status` | `[]string` | | A list of commands to check if this task should run. The task is skipped otherwise. This overrides `method`, `sources` and `generates`. |
| `requires` | `[]string` | | A list of variables which should be set if this task is to run, if any of these variables are unset the task will error and not run. |
| `preconditions` | [`[]Precondition`](#precondition) | | A list of commands to check if this task should run. If a condition is not met, the task will error. |
| `requires` | [`Requires`](#requires) | | A list of required variables which should be set if this task is to run, if any variables listed are unset the task will error and not run. |
| `dir` | `string` | | The directory in which this task should run. Defaults to the current working directory. |
| `vars` | [`map[string]Variable`](#variable) | | A set of variables that can be used in the task. |
| `env` | [`map[string]Variable`](#variable) | | A set of environment variables that will be made available to shell commands. |
@@ -322,3 +325,9 @@ tasks:
```
:::
#### Requires
| Attribute | Type | Default | Description |
| --------- | ---------- | ------- | -------------------------------------------------------------------------------------------------- |
| `vars` | `[]string` | | List of variable or environment variable names that must be set if this task is to execute and run |

42
docs/docs/usage.md
View File

@@ -876,6 +876,48 @@ tasks:
- sleep 5 # long operation like installing packages
```
### Ensuring required variables are set
If you want to check that certain variables are set before running a task then
you can use `requires`. This is useful when might not be clear to users which
variables are needed, or if you want clear message about what is required. Also
some tasks could have dangerous side effects if run with un-set variables.
Using `requires` you specify an array of strings in the `vars` sub-section
under `requires`, these strings are variable names which are checked prior to
running the task. If any variables are un-set the the task will error and not
run.
Environmental variables are also checked.
Syntax:
```yaml
requires:
vars: [] # Array of strings
```
:::note
Variables set to empty zero length strings, will pass the `requires` check.
:::
Example of using `requires`:
```yaml
version: '3'
tasks:
docker-build:
cmds:
- 'docker build . -t {{.IMAGE_NAME}}:{{.IMAGE_TAG}}'
# Make sure these variables are set before running
requires:
vars: [IMAGE_NAME, IMAGE_TAG]
```
## Variables
When doing interpolation of variables, Task will look for the below. They are