Skip to content

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

docs(hook): correct pre-switch {{ branch }} resolution note (#3516)

Worktrunk Botc6eb148e62d5
diff --git a/docs/content/hook.md b/docs/content/hook.md
index c8a44ff2d..0975dcee8 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -29,7 +29,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| Hook | Purpose |
|------|---------|
-| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
+| `pre-switch` | Runs in the source worktree before switching — creating, switching to existing, or staying on current |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
diff --git a/plugins/worktrunk/skills/worktrunk/reference/hook.md b/plugins/worktrunk/skills/worktrunk/reference/hook.md
index 049b7c850..9dc5e9ff0 100644
--- a/plugins/worktrunk/skills/worktrunk/reference/hook.md
+++ b/plugins/worktrunk/skills/worktrunk/reference/hook.md
@@ -20,7 +20,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| Hook | Purpose |
|------|---------|
-| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
+| `pre-switch` | Runs in the source worktree before switching — creating, switching to existing, or staying on current |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 049b7c850..9dc5e9ff0 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -20,7 +20,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| Hook | Purpose |
|------|---------|
-| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
+| `pre-switch` | Runs in the source worktree before switching — creating, switching to existing, or staying on current |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 6dcb1d89f..2d10d7073 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1529,7 +1529,7 @@ The most common creation hook is `post-start` — it runs background tasks (dev
| Hook | Purpose |
|------|---------|
-| `pre-switch` | Runs before branch resolution or worktree creation. `{{ branch }}` is the destination as typed (before resolution) |
+| `pre-switch` | Runs in the source worktree before switching — creating, switching to existing, or staying on current |
| `post-switch` | Triggers on all switch results: creating, switching to existing, or staying on current |
| `pre-start` | Runs once when a new worktree is created, blocking `post-start`/`--execute` until complete: dependency install, env file generation |
| `post-start` | Runs once when a new worktree is created, in the background: dev servers, long builds, file watchers, copying caches |
diff --git a/src/commands/worktree/switch.rs b/src/commands/worktree/switch.rs
index 50685b545..577011469 100644
--- a/src/commands/worktree/switch.rs
+++ b/src/commands/worktree/switch.rs
@@ -1583,8 +1583,9 @@ impl SwitchPipeline<'_> {
// (.git, .bare) before anything reads worktree-path config.
offer_bare_repo_worktree_path_fix(repo, config, identifier)?;
- // Run pre-switch hooks before branch resolution or worktree creation.
- // {{ branch }} receives the raw user input (before resolution). Skip
+ // Run pre-switch hooks before worktree creation. run_pre_switch_hooks
+ // resolves symbolic args (`-`, `@`, `^`) first, so {{ branch }} and
+ // {{ target }} carry the concrete destination, not the raw token. Skip
// when recovered — the source worktree is gone, nothing to run hooks
// against. `yes` is the single switch-wide flag, so the picker (no
// `--yes`) and the argument path gate `pre-switch` hooks identically.
diff --git a/tests/integration_tests/user_hooks.rs b/tests/integration_tests/user_hooks.rs
index 183a6ad98..694858e33 100644
--- a/tests/integration_tests/user_hooks.rs
+++ b/tests/integration_tests/user_hooks.rs
@@ -2967,6 +2967,34 @@ check = "echo '{{ branch }}' > pre_switch_branch.txt"
);
}
+/// A symbolic switch argument (`@`, `-`, `^`) is resolved to its concrete branch
+/// name before the pre-switch hook runs, so `{{ branch }}` carries the resolved
+/// destination — not the literal token. Here `@` resolves to the current branch.
+#[rstest]
+fn test_user_pre_switch_branch_var_resolves_symbolic(repo: TestRepo) {
+ repo.write_test_config(
+ r#"[pre-switch]
+check = "echo '{{ branch }}' > pre_switch_symbolic.txt"
+"#,
+ );
+
+ // `@` resolves to the current branch (main), not the literal "@".
+ snapshot_switch("user_pre_switch_branch_symbolic", &repo, &["@"]);
+
+ let marker_file = repo.root_path().join("pre_switch_symbolic.txt");
+ assert!(
+ marker_file.exists(),
+ "Pre-switch hook should have created marker"
+ );
+ let contents = fs::read_to_string(&marker_file).unwrap();
+ assert_eq!(
+ contents.trim(),
+ "main",
+ "symbolic '@' should resolve to the concrete branch 'main', got: '{}'",
+ contents.trim(),
+ );
+}
+
/// When removing the current worktree, post-switch hooks should fire
/// because the user is implicitly switched back to the primary worktree.
/// Regression test for https://github.com/max-sixty/worktrunk/issues/1450
diff --git a/tests/snapshots/integration__integration_tests__user_hooks__user_pre_switch_branch_symbolic.snap b/tests/snapshots/integration__integration_tests__user_hooks__user_pre_switch_branch_symbolic.snap
new file mode 100644
index 000000000..04dfdb20c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__user_hooks__user_pre_switch_branch_symbolic.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/user_hooks.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "@"
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLAUDE_CONFIG_DIR: "[TEST_CLAUDE_CONFIG]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_PARENT_SHELL: ""
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+◎ Running pre-switch user:check
+  echo 'main' > pre_switch_symbolic.txt
+○ Already on worktree for main @ _REPO_
+↳ To enable automatic cd, run wt config shell install