Skip to content

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

Reorder hook types from lifecycle to paired-by-event (#1763)

Maximilian Roosd3b63690a124
diff --git a/docs/content/hook.md b/docs/content/hook.md
index fbdefacbc..146338d2a 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -17,8 +17,8 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
| Event | `pre-` (blocking) | `post-` (background) |
|-------|-------------------|---------------------|
-| **start** | `pre-start` | `post-start` |
| **switch** | `pre-switch` | `post-switch` |
+| **start** | `pre-start` | `post-start` |
| **commit** | `pre-commit` | `post-commit` |
| **merge** | `pre-merge` | `post-merge` |
| **remove** | `pre-remove` | `post-remove` |
@@ -42,6 +42,15 @@ fi
"""
```
+## post-switch
+
+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
+
+```toml
+[post-switch]
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
+```
+
## pre-start
Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.
@@ -62,15 +71,6 @@ copy = "wt step copy-ignored"
server = "npm run dev -- --port {{ branch | hash_port }}"
```
-## post-switch
-
-Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
-
-```toml
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-```
-
## pre-commit
Formatters, linters, type checking — runs during `wt merge` before the squash commit.
@@ -516,9 +516,9 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=g>Commands:</span></b>
<b><span class=c>show</span></b> Show configured hooks
<b><span class=c>pre-switch</span></b> Run pre-switch hooks
+ <b><span class=c>post-switch</span></b> Run post-switch hooks
<b><span class=c>pre-start</span></b> Run pre-start hooks
<b><span class=c>post-start</span></b> Run post-start hooks
- <b><span class=c>post-switch</span></b> Run post-switch hooks
<b><span class=c>pre-commit</span></b> Run pre-commit hooks
<b><span class=c>post-commit</span></b> Run post-commit hooks
<b><span class=c>pre-merge</span></b> Run pre-merge hooks
diff --git a/docs/content/switch.md b/docs/content/switch.md
index a3dfb379f..6f148b87f 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -40,12 +40,11 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Runs [pre-switch hooks](@/hook.md#pre-switch) (blocking, fail-fast)
+1. Runs [pre-switch hooks](@/hook.md#pre-switch) — blocks until complete
2. Creates worktree at configured path
3. Switches to new directory
-4. Runs [pre-start hooks](@/hook.md#pre-start) (blocking)
-5. Spawns [post-start hooks](@/hook.md#post-start) (background)
-6. Spawns [post-switch hooks](@/hook.md#post-switch) (background)
+4. Runs [pre-start hooks](@/hook.md#pre-start) — blocks until complete
+5. Spawns [post-start](@/hook.md#post-start) and [post-switch hooks](@/hook.md#post-switch) in the background
```bash
wt switch feature # Existing branch → creates worktree
diff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.md
index 27662272f..8f7084c32 100644
--- a/skills/worktrunk/reference/hook.md
+++ b/skills/worktrunk/reference/hook.md
@@ -8,8 +8,8 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au
| Event | `pre-` (blocking) | `post-` (background) |
|-------|-------------------|---------------------|
-| **start** | `pre-start` | `post-start` |
| **switch** | `pre-switch` | `post-switch` |
+| **start** | `pre-start` | `post-start` |
| **commit** | `pre-commit` | `post-commit` |
| **merge** | `pre-merge` | `post-merge` |
| **remove** | `pre-remove` | `post-remove` |
@@ -33,6 +33,15 @@ fi
"""
```
+## post-switch
+
+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
+
+```toml
+[post-switch]
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
+```
+
## pre-start
Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.
@@ -53,15 +62,6 @@ copy = "wt step copy-ignored"
server = "npm run dev -- --port {{ branch | hash_port }}"
```
-## post-switch
-
-Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
-
-```toml
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-```
-
## pre-commit
Formatters, linters, type checking — runs during `wt merge` before the squash commit.
@@ -499,9 +499,9 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=g>Commands:</span></b>
<b><span class=c>show</span></b> Show configured hooks
<b><span class=c>pre-switch</span></b> Run pre-switch hooks
+ <b><span class=c>post-switch</span></b> Run post-switch hooks
<b><span class=c>pre-start</span></b> Run pre-start hooks
<b><span class=c>post-start</span></b> Run post-start hooks
- <b><span class=c>post-switch</span></b> Run post-switch hooks
<b><span class=c>pre-commit</span></b> Run pre-commit hooks
<b><span class=c>post-commit</span></b> Run post-commit hooks
<b><span class=c>pre-merge</span></b> Run pre-merge hooks
diff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.md
index e4b32f505..81e559065 100644
--- a/skills/worktrunk/reference/switch.md
+++ b/skills/worktrunk/reference/switch.md
@@ -24,12 +24,11 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Runs [pre-switch hooks](https://worktrunk.dev/hook/#pre-switch) (blocking, fail-fast)
+1. Runs [pre-switch hooks](https://worktrunk.dev/hook/#pre-switch) — blocks until complete
2. Creates worktree at configured path
3. Switches to new directory
-4. Runs [pre-start hooks](https://worktrunk.dev/hook/#pre-start) (blocking)
-5. Spawns [post-start hooks](https://worktrunk.dev/hook/#post-start) (background)
-6. Spawns [post-switch hooks](https://worktrunk.dev/hook/#post-switch) (background)
+4. Runs [pre-start hooks](https://worktrunk.dev/hook/#pre-start) — blocks until complete
+5. Spawns [post-start](https://worktrunk.dev/hook/#post-start) and [post-switch hooks](https://worktrunk.dev/hook/#post-switch) in the background
```bash
wt switch feature # Existing branch → creates worktree
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 85513e89b..5f4da42f3 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -10,7 +10,7 @@ pub enum HookCommand {
/// Lists user and project hooks. Project hooks show approval status (❓ = needs approval).
Show {
/// Hook type to show (default: all)
- #[arg(value_parser = ["pre-switch", "pre-start", "post-create", "post-start", "post-switch", "pre-commit", "post-commit", "pre-merge", "post-merge", "pre-remove", "post-remove"])]
+ #[arg(value_parser = ["pre-switch", "post-switch", "pre-start", "post-create", "post-start", "pre-commit", "post-commit", "pre-merge", "post-merge", "pre-remove", "post-remove"])]
hook_type: Option<String>,
/// Show expanded commands with current variables
@@ -42,11 +42,10 @@ pub enum HookCommand {
vars: Vec<(String, String)>,
},
- /// Run pre-start hooks
+ /// Run post-switch hooks
///
- /// Blocking — waits for completion before continuing.
- #[command(alias = "post-create")]
- PreStart {
+ /// Background by default. Use `--foreground` to run in foreground for debugging.
+ PostSwitch {
/// Filter by command name
///
/// Supports `user:name` or `project:name` to filter by source.
@@ -62,15 +61,20 @@ pub enum HookCommand {
#[arg(long)]
dry_run: bool,
+ /// Run in foreground (block until complete)
+ #[arg(long)]
+ foreground: bool,
+
/// Override built-in template variable (KEY=VALUE)
#[arg(long = "var", value_name = "KEY=VALUE", value_parser = super::parse_key_val, action = clap::ArgAction::Append)]
vars: Vec<(String, String)>,
},
- /// Run post-start hooks
+ /// Run pre-start hooks
///
- /// Background by default. Use `--foreground` to run in foreground for debugging.
- PostStart {
+ /// Blocking — waits for completion before continuing.
+ #[command(alias = "post-create")]
+ PreStart {
/// Filter by command name
///
/// Supports `user:name` or `project:name` to filter by source.
@@ -86,19 +90,15 @@ pub enum HookCommand {
#[arg(long)]
dry_run: bool,
- /// Run in foreground (block until complete)
- #[arg(long)]
- foreground: bool,
-
/// Override built-in template variable (KEY=VALUE)
#[arg(long = "var", value_name = "KEY=VALUE", value_parser = super::parse_key_val, action = clap::ArgAction::Append)]
vars: Vec<(String, String)>,
},
- /// Run post-switch hooks
+ /// Run post-start hooks
///
/// Background by default. Use `--foreground` to run in foreground for debugging.
- PostSwitch {
+ PostStart {
/// Filter by command name
///
/// Supports `user:name` or `project:name` to filter by source.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index ce738eeff..dc528ef6e 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -272,12 +272,11 @@ If the branch already has a worktree, `wt switch` changes directories to it. Oth
When creating a worktree, worktrunk:
-1. Runs [pre-switch hooks](@/hook.md#pre-switch) (blocking, fail-fast)
+1. Runs [pre-switch hooks](@/hook.md#pre-switch) — blocks until complete
2. Creates worktree at configured path
3. Switches to new directory
-4. Runs [pre-start hooks](@/hook.md#pre-start) (blocking)
-5. Spawns [post-start hooks](@/hook.md#post-start) (background)
-6. Spawns [post-switch hooks](@/hook.md#post-switch) (background)
+4. Runs [pre-start hooks](@/hook.md#pre-start) — blocks until complete
+5. Spawns [post-start](@/hook.md#post-start) and [post-switch hooks](@/hook.md#post-switch) in the background
```console
wt switch feature # Existing branch → creates worktree
@@ -1108,8 +1107,8 @@ Alias names that match a built-in step command (`commit`, `squash`, etc.) are sh
| Event | `pre-` (blocking) | `post-` (background) |
|-------|-------------------|---------------------|
-| **start** | `pre-start` | `post-start` |
| **switch** | `pre-switch` | `post-switch` |
+| **start** | `pre-start` | `post-start` |
| **commit** | `pre-commit` | `post-commit` |
| **merge** | `pre-merge` | `post-merge` |
| **remove** | `pre-remove` | `post-remove` |
@@ -1133,6 +1132,15 @@ fi
"""
```
+## post-switch
+
+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
+
+```toml
+[post-switch]
+tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
+```
+
## pre-start
Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.
@@ -1153,15 +1161,6 @@ copy = "wt step copy-ignored"
server = "npm run dev -- --port {{ branch | hash_port }}"
```
-## post-switch
-
-Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current.
-
-```toml
-[post-switch]
-tmux = "[ -n \"$TMUX\" ] && tmux rename-window {{ branch | sanitize }}"
-```
-
## pre-commit
Formatters, linters, type checking — runs during `wt merge` before the squash commit.
diff --git a/src/commands/process.rs b/src/commands/process.rs
index 2a7110e5c..8d808d3ed 100644
--- a/src/commands/process.rs
+++ b/src/commands/process.rs
@@ -660,7 +660,7 @@ mod tests {
assert_snapshot!(HookLog::parse("invalid:post-start:server").unwrap_err(), @"Unknown source: invalid. Valid: user, project");
// Unknown hook type
- assert_snapshot!(HookLog::parse("user:invalid-hook:server").unwrap_err(), @"Unknown hook type: invalid-hook. Valid: pre-switch, pre-start, post-start, post-switch, pre-commit, post-commit, pre-merge, post-merge, pre-remove, post-remove");
+ assert_snapshot!(HookLog::parse("user:invalid-hook:server").unwrap_err(), @"Unknown hook type: invalid-hook. Valid: pre-switch, post-switch, pre-start, post-start, pre-commit, post-commit, pre-merge, post-merge, pre-remove, post-remove");
// Unknown internal operation
assert_snapshot!(HookLog::parse("internal:unknown").unwrap_err(), @"Unknown internal operation: unknown. Valid: remove");
diff --git a/src/config/hooks.rs b/src/config/hooks.rs
index e02add12a..7e2380edf 100644
--- a/src/config/hooks.rs
+++ b/src/config/hooks.rs
@@ -16,6 +16,14 @@ pub struct HooksConfig {
)]
pub pre_switch: Option<CommandConfig>,
+ /// Commands to execute after switching to a worktree (background)
+ #[serde(
+ default,
+ rename = "post-switch",
+ skip_serializing_if = "Option::is_none"
+ )]
+ pub post_switch: Option<CommandConfig>,
+
/// Commands to execute before worktree start (blocking)
#[serde(default, rename = "pre-start", skip_serializing_if = "Option::is_none")]
pub pre_start: Option<CommandConfig>,
@@ -36,14 +44,6 @@ pub struct HooksConfig {
)]
pub post_start: Option<CommandConfig>,
- /// Commands to execute after switching to a worktree (background)
- #[serde(
- default,
- rename = "post-switch",
- skip_serializing_if = "Option::is_none"
- )]
- pub post_switch: Option<CommandConfig>,
-
/// Commands to execute before committing during merge (blocking, fail-fast)
#[serde(
default,
@@ -93,10 +93,10 @@ impl HooksConfig {
pub fn get(&self, hook: HookType) -> Option<&CommandConfig> {
match hook {
HookType::PreSwitch => self.pre_switch.as_ref(),
+ HookType::PostSwitch => self.post_switch.as_ref(),
// pre-start merges with deprecated post-create (pre-start takes precedence)
HookType::PreStart => self.pre_start.as_ref().or(self.post_create.as_ref()),
HookType::PostStart => self.post_start.as_ref(),
- HookType::PostSwitch => self.post_switch.as_ref(),
HookType::PreCommit => self.pre_commit.as_ref(),
HookType::PostCommit => self.post_commit.as_ref(),
HookType::PreMerge => self.pre_merge.as_ref(),
@@ -137,10 +137,10 @@ impl Merge for HooksConfig {
Self {
pre_switch: merge_append_hooks(&self.pre_switch, &other.pre_switch),
+ post_switch: merge_append_hooks(&self.post_switch, &other.post_switch),
pre_start: merge_append_hooks(&self_pre_start, &other_pre_start),
post_create: None, // folded into pre_start above
post_start: merge_append_hooks(&self.post_start, &other.post_start),
- post_switch: merge_append_hooks(&self.post_switch, &other.post_switch),
pre_commit: merge_append_hooks(&self.pre_commit, &other.pre_commit),
post_commit: merge_append_hooks(&self.post_commit, &other.post_commit),
pre_merge: merge_append_hooks(&self.pre_merge, &other.pre_merge),
diff --git a/src/git/mod.rs b/src/git/mod.rs
index c5d5a8647..b388e4048 100644
--- a/src/git/mod.rs
+++ b/src/git/mod.rs
@@ -329,9 +329,9 @@ pub fn branch_tracks_ref(
#[strum(serialize_all = "kebab-case")]
pub enum HookType {
PreSwitch,
+ PostSwitch,
PreStart,
PostStart,
- PostSwitch,
PreCommit,
PostCommit,
PreMerge,
diff --git a/src/main.rs b/src/main.rs
index acd27d1e8..733780f1a 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -150,34 +150,34 @@ fn handle_hook_command(action: HookCommand) -> anyhow::Result<()> {
dry_run,
vars,
} => run_non_toggle_hook(HookType::PreSwitch, yes, dry_run, name.as_deref(), &vars),
- HookCommand::PreStart {
- name,
- yes,
- dry_run,
- vars,
- } => run_non_toggle_hook(HookType::PreStart, yes, dry_run, name.as_deref(), &vars),
- HookCommand::PostStart {
+ HookCommand::PostSwitch {
name,
yes,
dry_run,
foreground,
vars,
} => run_toggleable_hook(
- HookType::PostStart,
+ HookType::PostSwitch,
yes,
dry_run,
foreground,
name.as_deref(),
&vars,
),
- HookCommand::PostSwitch {
+ HookCommand::PreStart {
+ name,
+ yes,
+ dry_run,
+ vars,
+ } => run_non_toggle_hook(HookType::PreStart, yes, dry_run, name.as_deref(), &vars),
+ HookCommand::PostStart {
name,
yes,
dry_run,
foreground,
vars,
} => run_toggleable_hook(
- HookType::PostSwitch,
+ HookType::PostStart,
yes,
dry_run,
foreground,
@@ -190,12 +190,6 @@ fn handle_hook_command(action: HookCommand) -> anyhow::Result<()> {
dry_run,
vars,
} => run_non_toggle_hook(HookType::PreCommit, yes, dry_run, name.as_deref(), &vars),
- HookCommand::PreMerge {
- name,
- yes,
- dry_run,
- vars,
- } => run_non_toggle_hook(HookType::PreMerge, yes, dry_run, name.as_deref(), &vars),
HookCommand::PostCommit {
name,
yes,
@@ -210,6 +204,12 @@ fn handle_hook_command(action: HookCommand) -> anyhow::Result<()> {
name.as_deref(),
&vars,
),
+ HookCommand::PreMerge {
+ name,
+ yes,
+ dry_run,
+ vars,
+ } => run_non_toggle_hook(HookType::PreMerge, yes, dry_run, name.as_deref(), &vars),
HookCommand::PostMerge {
name,
yes,
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 71aeaa517..728fcc09b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -128,12 +128,11 @@ If the branch already has a worktree, wt switch changes directories to i
When creating a worktree, worktrunk:
-1. Runs pre-switch hooks (blocking, fail-fast)
+1. Runs pre-switch hooks — blocks until complete
2. Creates worktree at configured path
3. Switches to new directory
-4. Runs pre-start hooks (blocking)
-5. Spawns post-start hooks (background)
-6. Spawns post-switch hooks (background)
+4. Runs pre-start hooks — blocks until complete
+5. Spawns post-start and post-switch hooks in the background
  wt switch feature # Existing branch → creates worktree
  wt switch --create feature # New branch and worktree