1# Tasks
2
3Zed supports ways to spawn (and rerun) commands using its integrated terminal to output the results. These commands can read a limited subset of Zed state (such as a path to the file currently being edited or selected text).
4
5```json
6[
7 {
8 "label": "Example task",
9 "command": "for i in {1..5}; do echo \"Hello $i/5\"; sleep 1; done",
10 //"args": [],
11 // Env overrides for the command, will be appended to the terminal's environment from the settings.
12 "env": { "foo": "bar" },
13 // Current working directory to spawn the command into, defaults to current project root.
14 //"cwd": "/path/to/working/directory",
15 // Whether to use a new terminal tab or reuse the existing one to spawn the process, defaults to `false`.
16 "use_new_terminal": false,
17 // Whether to allow multiple instances of the same task to be run, or rather wait for the existing ones to finish, defaults to `false`.
18 "allow_concurrent_runs": false,
19 // What to do with the terminal pane and tab, after the command was started:
20 // * `always` — always show the terminal pane, add and focus the corresponding task's tab in it (default)
21 // * `never` — avoid changing current terminal pane focus, but still add/reuse the task's tab there
22 "reveal": "always"
23 }
24]
25```
26
27There are two actions that drive the workflow of using tasks: `task: spawn` and `task: rerun`
28`task: spawn` opens a modal with all available tasks in the current file.
29`task: rerun` reruns the most-recently spawned task. You can also rerun tasks from task modal.
30
31## Task templates
32
33Tasks, defined in a config file (`tasks.json` in the Zed config directory).
34Zed supports both global task templates (available in all projects) or workspace-local task templates (available only in the current workspace).
35
36To edit global task templates, use `zed: open tasks` actions from command palette; to edit workspace-local task templates, use `zed: open local tasks` action.
37
38## Variables
39
40Variables allow you to pull information from the current editor and use it in your tasks. The following variables are available:
41
42- `ZED_COLUMN`: current line column
43- `ZED_ROW`: current line row
44- `ZED_FILE`: absolute path to the file
45- `ZED_SYMBOL`: currently selected symbol; should match the last symbol shown in a symbol breadcrumb (e.g. `mod tests > fn test_task_contexts`)
46- `ZED_SELECTED_TEXT`: currently selected text
47- `ZED_WORKTREE_ROOT`: absolute path to the root of the current worktree.
48- `ZED_CUSTOM_RUST_PACKAGE`: (Rust-specific) name of the parent package of $ZED_FILE source file.
49
50To use a variable in a task, prefix it with a dollar sign (`$`):
51
52```json
53{
54 "label": "echo current file's path",
55 "command": "echo $ZED_FILE"
56}
57```
58
59You can also use verbose syntax that allows specifying a default if a given variable is not available: `${ZED_FILE:default_value}`
60
61These environmental variables can also be used in tasks `cwd`, `args` and `label` fields.
62
63## Oneshot tasks
64
65The same task modal opened via `task: spawn` supports arbitrary bash-like command execution: type a command inside the modal text field, and use `opt-enter` to spawn it.
66
67Task modal will persist list of those command for current Zed session, `task: rerun` will also rerun such tasks if they were the last ones spawned.
68
69### Ephemeral tasks
70
71You can use cmd modifier when spawning a task via a modal; tasks spawned this way will not have their usage count increased (thus, they will not be respawned with `task: rerun` and they won't be have a high rank in task modal).
72The intended use of ephemeral tasks is to stay in the flow with continuous `task: rerun` usage.
73
74## Custom keybindings for tasks
75
76You can define your own keybindings for your tasks via additional argument to `task::Spawn`. If you wanted to bind the aforementioned `echo current file's path` task to `alt-g`, you would add the following snippet in your [`keymap.json`](./key-bindings/) file:
77
78```json
79{
80 "context": "Workspace",
81 "bindings": {
82 "alt-g": ["task::Spawn", { "task_name": "echo current file's path" }]
83 }
84}
85```
86
87## Binding runnable tags to task templates
88
89Zed supports overriding default action for inline runnable tags via workspace-local and global `tasks.json` file with the following precedence hierarchy:
90
911. Workspace `tasks.json`
922. Global `tasks.json`
933. Language-provided tag bindings (default).
94
95To tag a task, add the runnable tag name to `tags` field on task template:
96
97```json
98{
99 "label": "echo current file's path",
100 "command": "echo $ZED_FILE",
101 "tags": ["rust-test"]
102}
103```