Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs(switch): document why only switch needs pre-flight template validation (#1504)

Maximilian Roos5131917b7358
diff --git a/src/commands/handle_switch.rs b/src/commands/handle_switch.rs
index 49c2a4a66..f3b3bb6fc 100644
--- a/src/commands/handle_switch.rs
+++ b/src/commands/handle_switch.rs
@@ -335,6 +335,20 @@ pub fn handle_switch(
/// are absent at expansion time (e.g., `upstream` when no tracking is configured).
/// Such late failures propagate as normal errors — no panics.
///
+/// ## Why only switch needs pre-flight validation
+///
+/// Switch is the only command where template failure after mutation creates a
+/// **blocking half-state**: `wt switch -c <branch>` creates a worktree, then if
+/// hook/--execute expansion fails, the worktree exists and the same command
+/// can't be re-run (branch already exists). Other commands don't have this
+/// problem:
+///
+/// - **Pre-operation hooks** (pre-merge, pre-remove, pre-commit) run before the
+/// irreversible operation, so template errors abort cleanly.
+/// - **Post-operation hooks** (post-merge, post-remove) run after the operation
+/// completed successfully — template failure is a missed notification, not a
+/// blocking state. The user can fix the template and run `wt hook` manually.
+///
/// Validates:
/// - `--execute` command template (if present)
/// - `--execute` trailing arg templates (if present)