Yehowshua/ZIm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix up tasks documentation (#24991)

Browse source 
Release Notes:

- N/A
This commit is contained in:
Joseph T. Lyons 2025-02-16 20:03:29 -05:00 • committed by GitHub
parent ba2c1821af
commit 58491807a4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 16 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

32
docs/src/tasks.md
View file

@ -21,7 +21,7 @@ Zed supports ways to spawn (and rerun) commands using its integrated terminal to
// * `no_focus` — always show the task's pane, add the task's tab in it, but don't focus it
// * `never` — do not alter focus, but still add/reuse the task's tab in its pane
"reveal": "always",
// What to do with the terminal pane and tab, after the command had finished:
// What to do with the terminal pane and tab, after the command has finished:
// * `never` — Do nothing when the command finishes (default)
// * `always` — always hide the terminal tab, hide the pane also if it was the last tab in it
// * `on_success` — hide the terminal tab on task success only, otherwise behaves similar to `always`
@ -50,11 +50,11 @@ Zed supports ways to spawn (and rerun) commands using its integrated terminal to
]
```
There are two actions that drive the workflow of using tasks: `task: spawn` and `task: rerun`
There are two actions that drive the workflow of using tasks: `task: spawn` and `task: rerun`.
`task: spawn` opens a modal with all available tasks in the current file.
`task: rerun` reruns the most-recently spawned task. You can also rerun tasks from task modal.
`task: rerun` reruns the most recently spawned task. You can also rerun tasks from the task modal.
By default, rerunning tasks reuses the same terminal (due to the `"use_new_terminal": false` default) but waits for the previous task to finish before start (due to the `"allow_concurrent_runs": false` default).
By default, rerunning tasks reuses the same terminal (due to the `"use_new_terminal": false` default) but waits for the previous task to finish before starting (due to the `"allow_concurrent_runs": false` default).
Keep `"use_new_terminal": false` and set `"allow_concurrent_runs": true` to allow cancelling previous tasks on rerun.
@ -62,9 +62,9 @@ Keep `"use_new_terminal": false` and set `"allow_concurrent_runs": true` to allo
Tasks can be defined:
- 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.
- 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`.
- on the fly with [oneshot tasks](#oneshot-tasks). These tasks are project-specific and do not persist across sections.
- in the 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 the `zed: open tasks` action.
- in the 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 the `zed: open local tasks` action.
- on the fly with [oneshot tasks](#oneshot-tasks). These tasks are project-specific and do not persist across sessions.
- by language extension.
## Variables
@ -95,7 +95,7 @@ To use a variable in a task, prefix it with a dollar sign (`$`):
You can also use verbose syntax that allows specifying a default if a given variable is not available: `${ZED_FILE:default_value}`
These environmental variables can also be used in tasks `cwd`, `args` and `label` fields.
These environmental variables can also be used in tasks' `cwd`, `args`, and `label` fields.
### Variable Quoting
@ -110,7 +110,7 @@ For example, instead of this (which will fail if the path has a space):
}
```
Provide the
Provide the following:
```json
{
@ -133,18 +133,18 @@ Or explicitly include escaped quotes like so:
The 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.
Task 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.
The task modal persists these ad-hoc commands for the duration of the session, `task: rerun` will also rerun such tasks if they were the last ones spawned.
You can also adjust currently selected task in a modal (`tab` is a default key binding). Doing so will put its command into a prompt that can then be edited & spawned as an oneshot task.
You can also adjust the currently selected task in a modal (`tab` is the default key binding). Doing so will put its command into a prompt that can then be edited & spawned as a oneshot task.
### Ephemeral tasks
You 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).
You can use the `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 have a high rank in the task modal).
The intended use of ephemeral tasks is to stay in the flow with continuous `task: rerun` usage.
## Custom keybindings for tasks
You 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.md) file:
You can define your own keybindings for your tasks via an 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.md) file:
```json
{
@ -181,13 +181,13 @@ This could be useful for launching a terminal application that you want to use i
## Binding runnable tags to task templates
Zed supports overriding default action for inline runnable indicators via workspace-local and global `tasks.json` file with the following precedence hierarchy:
Zed supports overriding the default action for inline runnable indicators via workspace-local and global `tasks.json` file with the following precedence hierarchy:
1. Workspace `tasks.json`
2. Global `tasks.json`
3. Language-provided tag bindings (default).
To tag a task, add the runnable tag name to `tags` field on task template:
To tag a task, add the runnable tag name to the `tags` field on the task template:
```json
{
@ -197,4 +197,4 @@ To tag a task, add the runnable tag name to `tags` field on task template:
}
```
In doing so, you can change which task is shown in runnables indicator.
In doing so, you can change which task is shown in the runnables indicator.