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 can be defined:
 34
 35- in global `tasks.json` file; such tasks are available in all Zed projects you work on. This file is usually located in `~/.config/zed/tasks.json`. You can edit them by using `zed: open tasks` action.
 36- in worktree-specific (local) `.zed/tasks.json` file; such tasks are available only when working on a project with that worktree included. You can edit worktree-specific tasks by using `zed: open local tasks`.
 37- on the fly with [oneshot tasks](#oneshot-tasks). These tasks are project-specific and do not persist across sections.
 38- by language extension.
 39
 40## Variables
 41
 42Zed tasks act just like your shell; that also means that you can reference environmental variables via sh-esque `$VAR_NAME` syntax. A couple of additional environmental variables are set for your convenience.
 43These variables allow you to pull information from the current editor and use it in your tasks. The following variables are available:
 44
 45- `ZED_COLUMN`: current line column
 46- `ZED_ROW`: current line row
 47- `ZED_FILE`: absolute path of the currently opened file (e.g. `/Users/my-user/path/to/project/src/main.rs`)
 48- `ZED_FILENAME`: filename of the currently opened file (e.g. `main.rs`)
 49- `ZED_DIRNAME`: absolute path of the currently opened file with file name stripped (e.g. `/Users/my-user/path/to/project/src`)
 50- `ZED_RELATIVE_FILE`: path of the currently opened file, relative to `ZED_WORKTREE_ROOT` (e.g. `src/main.rs`)
 51- `ZED_STEM`: stem (filename without extension) of the currently opened file (e.g. `main`)
 52- `ZED_SYMBOL`: currently selected symbol; should match the last symbol shown in a symbol breadcrumb (e.g. `mod tests > fn test_task_contexts`)
 53- `ZED_SELECTED_TEXT`: currently selected text
 54- `ZED_WORKTREE_ROOT`: absolute path to the root of the current worktree. (e.g. `/Users/my-user/path/to/project`)
 55- `ZED_CUSTOM_RUST_PACKAGE`: (Rust-specific) name of the parent package of $ZED_FILE source file.
 56
 57To use a variable in a task, prefix it with a dollar sign (`$`):
 58
 59```json
 60{
 61  "label": "echo current file's path",
 62  "command": "echo $ZED_FILE"
 63}
 64```
 65
 66You can also use verbose syntax that allows specifying a default if a given variable is not available: `${ZED_FILE:default_value}`
 67
 68These environmental variables can also be used in tasks `cwd`, `args` and `label` fields.
 69
 70## Oneshot tasks
 71
 72The 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.
 73
 74Task 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.
 75
 76You can also adjust currently selected task in a modal (`opt-e` is a default key binding). Doing so will put it's command into a prompt that can then be edited & spawned as an oneshot task.
 77
 78### Ephemeral tasks
 79
 80You 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).
 81The intended use of ephemeral tasks is to stay in the flow with continuous `task: rerun` usage.
 82
 83## Custom keybindings for tasks
 84
 85You 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:
 86
 87```json
 88{
 89  "context": "Workspace",
 90  "bindings": {
 91    "alt-g": ["task::Spawn", { "task_name": "echo current file's path" }]
 92  }
 93}
 94```
 95
 96## Binding runnable tags to task templates
 97
 98Zed supports overriding default action for inline runnable indicators via workspace-local and global `tasks.json` file with the following precedence hierarchy:
 99
1001. Workspace `tasks.json`
1012. Global `tasks.json`
1023. Language-provided tag bindings (default).
103
104To tag a task, add the runnable tag name to `tags` field on task template:
105
106```json
107{
108  "label": "echo current file's path",
109  "command": "echo $ZED_FILE",
110  "tags": ["rust-test"]
111}
112```
113
114In doing so, you can change which task is shown in runnables indicator.