Skip to content

feat(prompts): add ability for tasks to prompt user pre execution #1163

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andreynering merged 4 commits into from
Jun 4, 2023
Merged

feat(prompts): add ability for tasks to prompt user pre execution #1163

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c6f17a1
feat(prompts): add ability for tasks to prompt user pre execution
MaxCheetham May 15, 2023
0cc29e2
fix: show prompts pre execution, and not during task collection
MaxCheetham May 23, 2023
4556448
feat(prompts): add '--yes' flag to allow for prompts to be used nonin…
MaxCheetham May 23, 2023
fed2d23
feat(prompts): add to usage docs.
MaxCheetham May 23, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions cmd/task/task.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ var flags struct {
watch bool
verbose bool
silent bool
assumeYes bool
dry bool
summary bool
exitCode bool
Expand Down Expand Up @@ -113,6 +114,7 @@ func run() error {
pflag.BoolVarP(&flags.watch, "watch", "w", false, "Enables watch of the given task.")
pflag.BoolVarP(&flags.verbose, "verbose", "v", false, "Enables verbose mode.")
pflag.BoolVarP(&flags.silent, "silent", "s", false, "Disables echoing.")
pflag.BoolVarP(&flags.assumeYes, "yes", "y", false, "Assume \"yes\" as answer to all prompts.")
pflag.BoolVarP(&flags.parallel, "parallel", "p", false, "Executes tasks provided on command line in parallel.")
pflag.BoolVarP(&flags.dry, "dry", "n", false, "Compiles and prints tasks in the order that they would be run, without executing them.")
pflag.BoolVar(&flags.summary, "summary", false, "Show summary about a task.")
Expand Down Expand Up @@ -195,6 +197,7 @@ func run() error {
Watch: flags.watch,
Verbose: flags.verbose,
Silent: flags.silent,
AssumeYes: flags.assumeYes,
Dir: flags.dir,
Dry: flags.dry,
Entrypoint: flags.entrypoint,
Expand Down
36 changes: 20 additions & 16 deletions docs/docs/api_reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@ If `--` is given, all remaning arguments will be assigned to a special
| | `--output-group-error-only` | `bool` | `false` | Swallow command output on zero exit code. |
| `-p` | `--parallel` | `bool` | `false` | Executes tasks provided on command line in parallel. |
| `-s` | `--silent` | `bool` | `false` | Disables echoing. |
| `-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` | |
Expand All @@ -53,7 +54,8 @@ If `--` is given, all remaning arguments will be assigned to a special

## Exit Codes

Task will sometimes exit with specific exit codes. These codes are split into three groups with the following ranges:
Task will sometimes exit with specific exit codes. These codes are split into
three groups with the following ranges:

- General errors (0-99)
- Taskfile errors (100-199)
Expand All @@ -73,12 +75,13 @@ A full list of the exit codes and their descriptions can be found below:
| 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 |

These codes can also be found in the repository in [`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).
These codes can also be found in the repository in
[`errors/errors.go`](https://github.com/go-task/task/blob/main/errors/errors.go).

:::info
When Task is run with the `-x`/`--exit-code` flag, the exit code of any failed commands will be passed through to the user instead.
:::
:::info When Task is run with the `-x`/`--exit-code` flag, the exit code of any
failed commands will be passed through to the user instead. :::

## JSON Output

Expand Down Expand Up @@ -206,6 +209,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. |
| `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. |
Expand All @@ -223,7 +227,7 @@ vars:
| `prefix` | `string` | | Defines a string to prefix the output of tasks running in parallel. Only used when the output mode is `prefixed`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing commands. |
| `run` | `string` | The one declared globally in the Taskfile or `always` | Specifies whether the task should run again or not if called more than once. Available options: `always`, `once` and `when_changed`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/main/src/go/build/syslist.go). Task will be skipped otherwise. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the task should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/main/src/go/build/syslist.go). Task will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |

Expand All @@ -248,17 +252,17 @@ tasks:

#### Command

| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmd` | `string` | | The shell command to be executed. |
| `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. |
| `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. |
| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| Attribute | Type | Default | Description |
| -------------- | ---------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cmd` | `string` | | The shell command to be executed. |
| `silent` | `bool` | `false` | Skips some output for this command. Note that STDOUT and STDERR of the commands will still be redirected. |
| `task` | `string` | | Set this to trigger execution of another task instead of running a command. This cannot be set together with `cmd`. |
| `vars` | [`map[string]Variable`](#variable) | | Optional additional variables to be passed to the referenced task. Only relevant when setting `task` instead of `cmd`. |
| `ignore_error` | `bool` | `false` | Continue execution if errors happen while executing the command. |
| `defer` | `string` | | Alternative to `cmd`, but schedules the command to be executed at the end of this task instead of immediately. This cannot be used together with `cmd`. |
| `platforms` | `[]string` | All platforms | Specifies which platforms the command should be run on. [Valid GOOS and GOARCH values allowed](https://github.com/golang/go/blob/main/src/go/build/syslist.go). Command will be skipped otherwise. |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |
| `set` | `[]string` | | Specify options for the [`set` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Set-Builtin.html). |
| `shopt` | `[]string` | | Specify option for the [`shopt` builtin](https://www.gnu.org/software/bash/manual/html_node/The-Shopt-Builtin.html). |

:::info

Expand Down
58 changes: 58 additions & 0 deletions docs/docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1212,6 +1212,64 @@ tasks:
- echo "{{.MESSAGE}}"
```

## Warning Prompts

Warning Prompts to prompt a user for confirmation before a task is executed.

Below is an example using `prompt` with a dangerous command, that is called between two safe commands
```yaml
version: '3'

tasks:
example:
cmds:
- task: not-dangerous
- task: dangerous
- task: another-not-dangerous

not-dangerous:
cmds:
- echo 'not dangerous command.'

another-not-dangerous:
cmds:
- echo 'another not dangerous command.'

dangerous:
prompt: This is a dangerous command.. Do you want to continue?
cmds:
- echo 'dangerous command.'

```
```bash
❯ task dangerous
task: "This is a dangerous command.. Do you want to continue?" [y/N]
```

### Prompt behaviour

Warning prompts are called before executing a task. If a prompt is denied Task will exit with [Exit code](api_reference.md#exit-codes) 205. If approved, Task will continue as normal.

```bash
❯ taskd --dir ./testdata/prompt example
task: [not-dangerous] echo 'not dangerous command.'
not dangerous command.
task: "This is a dangerous command.. Do you want to continue?" [y/N]
y
task: [dangerous] echo 'dangerous command.'
dangerous command.
task: [another-not-dangerous] echo 'another not dangerous command.'
another not dangerous command.
```

### Skipping Warning Prompts

To skip warning prompts automatically, you can use the [-y | --yes] option when calling the task. By including this option, all warnings, will be automatically confirmed, and no prompts will be shows.





## Silent mode

Silent mode disables the echoing of commands before Task runs it. For the
Expand Down
4 changes: 4 additions & 0 deletions docs/static/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,10 @@
"description": "A short description of the task. This is displayed when calling `task --list`.",
"type": "string"
},
"prompt": {
"description": "A prompt that will be presented before a task is run. Declining will cancel running the current and any subsequent tasks.",
"type": "string"
},
"summary": {
"description": "A longer description of the task. This is displayed when calling `task --summary [task]`.",
"type": "string"
Expand Down
1 change: 1 addition & 0 deletions errors/errors.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ const (
CodeTaskInternal
CodeTaskNameConflict
CodeTaskCalledTooManyTimes
CodeTaskCancelled
)

// TaskError extends the standard error interface with a Code method. This code will
Expand Down
18 changes: 17 additions & 1 deletion errors/errors_task.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ type TaskCalledTooManyTimesError struct {

func (err *TaskCalledTooManyTimesError) Error() string {
return fmt.Sprintf(
`task: maximum task call exceeded (%d) for task %q: probably an cyclic dep or infinite loop`,
`task: Maximum task call exceeded (%d) for task %q: probably an cyclic dep or infinite loop`,
err.MaximumTaskCall,
err.TaskName,
)
Expand All @@ -98,3 +98,19 @@ func (err *TaskCalledTooManyTimesError) Error() string {
func (err *TaskCalledTooManyTimesError) Code() int {
return CodeTaskCalledTooManyTimes
}

// TaskCancelledError is returned when the user does not accept an optional prompt to continue.
type TaskCancelledError struct {
TaskName string
}

func (err *TaskCancelledError) Error() string {
return fmt.Sprintf(
`task: %q Cancelled by user`,
err.TaskName,
)
}

func (err *TaskCancelledError) Code() int {
return CodeTaskCancelled
}
Loading