From a066794e8d19af9f63bf46a7c9ac4c8738f422f9 Mon Sep 17 00:00:00 2001
From: Kirill Bulatov <kirill@zed.dev>
Date: Thu, 11 Sep 2025 17:41:02 +0300
Subject: [PATCH] Document two task rerun modes better (#37996)

Part of https://github.com/zed-industries/zed/issues/37720

Release Notes:

- N/A
---
 assets/keymaps/default-linux.json   |  4 +++-
 assets/keymaps/default-macos.json   |  4 +++-
 assets/keymaps/default-windows.json |  4 +++-
 docs/src/tasks.md                   | 15 +++++++++++++++
 4 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/assets/keymaps/default-linux.json b/assets/keymaps/default-linux.json
index 700c7e8d8c441aabc11f61ca4de62d2a3f83245e..ea5f64c822f52c0b985616d37a4b51dcaac8ee29 100644
--- a/assets/keymaps/default-linux.json
+++ b/assets/keymaps/default-linux.json
@@ -649,7 +649,9 @@
       "ctrl-k shift-up": "workspace::SwapPaneUp",
       "ctrl-k shift-down": "workspace::SwapPaneDown",
       "ctrl-shift-x": "zed::Extensions",
-      "ctrl-shift-r": "task::Rerun",
+      // All task parameters are captured and unchanged between reruns by default.
+      // Use the `"reevaluate_context"` parameter to control this.
+      "ctrl-shift-r": ["task::Rerun", { "reevaluate_context": false }],
       "ctrl-alt-r": "task::Rerun",
       "alt-t": "task::Rerun",
       "alt-shift-t": "task::Spawn",
diff --git a/assets/keymaps/default-macos.json b/assets/keymaps/default-macos.json
index 7c85e6e582a8c0b89586d7ae3ee573271a457b38..bc870400e9eff1b27b012d3a80c1e58dc1726492 100644
--- a/assets/keymaps/default-macos.json
+++ b/assets/keymaps/default-macos.json
@@ -724,7 +724,9 @@
     "bindings": {
       "cmd-n": "workspace::NewFile",
       "cmd-shift-r": "task::Spawn",
-      "cmd-alt-r": "task::Rerun",
+      // All task parameters are captured and unchanged between reruns by default.
+      // Use the `"reevaluate_context"` parameter to control this.
+      "cmd-alt-r": ["task::Rerun", { "reevaluate_context": false }],
       "ctrl-alt-shift-r": ["task::Spawn", { "reveal_target": "center" }]
       // also possible to spawn tasks by name:
       // "foo-bar": ["task::Spawn", { "task_name": "MyTask", "reveal_target": "dock" }]
diff --git a/assets/keymaps/default-windows.json b/assets/keymaps/default-windows.json
index 0e9f193bd1a11cd4804878648e4690545fd7ce27..3f465d883dc098a5f36950ca369fdc775031b5f2 100644
--- a/assets/keymaps/default-windows.json
+++ b/assets/keymaps/default-windows.json
@@ -642,7 +642,9 @@
       "ctrl-k shift-up": "workspace::SwapPaneUp",
       "ctrl-k shift-down": "workspace::SwapPaneDown",
       "ctrl-shift-x": "zed::Extensions",
-      "ctrl-shift-r": "task::Rerun",
+      // All task parameters are captured and unchanged between reruns by default.
+      // Use the `"reevaluate_context"` parameter to control this.
+      "ctrl-shift-r": ["task::Rerun", { "reevaluate_context": false }],
       "alt-t": "task::Rerun",
       "shift-alt-t": "task::Spawn",
       "shift-alt-r": ["task::Spawn", { "reveal_target": "center" }],
diff --git a/docs/src/tasks.md b/docs/src/tasks.md
index e530f568cdce0fb8e1da059b4b841fac7049e8fd..b30b722007116d32435936205971419b5652689d 100644
--- a/docs/src/tasks.md
+++ b/docs/src/tasks.md
@@ -145,6 +145,21 @@ You can also adjust the currently selected task in a modal (`tab` is the default
 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.
 
+### More task rerun control
+
+By default, tasks capture their variables into a context once, and this "resolved task" is being rerun always.
+
+This can be controlled with the `"reevaluate_context"` argument to the task: setting it to `true` will force the task to be reevaluated before each run.
+
+```json
+{
+  "context": "Workspace",
+  "bindings": {
+    "alt-t": ["task::Rerun", { "reevaluate_context": true }]
+  }
+}
+```
+
 ## Custom keybindings for tasks
 
 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: