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.mdindex 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-startTasks 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-commitFormatters, 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 hooksdiff --git a/docs/content/switch.md b/docs/content/switch.mdindex 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. OthWhen 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 complete2. Creates worktree at configured path3. 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```bashwt switch feature # Existing branch → creates worktreediff --git a/skills/worktrunk/reference/hook.md b/skills/worktrunk/reference/hook.mdindex 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-startTasks 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-commitFormatters, 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 hooksdiff --git a/skills/worktrunk/reference/switch.md b/skills/worktrunk/reference/switch.mdindex 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. OthWhen 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 complete2. Creates worktree at configured path3. 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```bashwt switch feature # Existing branch → creates worktreediff --git a/src/cli/hook.rs b/src/cli/hook.rsindex 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.rsindex 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. OthWhen 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 complete2. Creates worktree at configured path3. 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```consolewt 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-startTasks 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-commitFormatters, linters, type checking — runs during `wt merge` before the squash commit.diff --git a/src/commands/process.rs b/src/commands/process.rsindex 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: [1minvalid[22m. Valid: user, project");// Unknown hook type- assert_snapshot!(HookLog::parse("user:invalid-hook:server").unwrap_err(), @"Unknown hook type: [1minvalid-hook[22m. 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: [1minvalid-hook[22m. Valid: pre-switch, post-switch, pre-start, post-start, pre-commit, post-commit, pre-merge, post-merge, pre-remove, post-remove");// Unknown internal operationassert_snapshot!(HookLog::parse("internal:unknown").unwrap_err(), @"Unknown internal operation: [1munknown[22m. Valid: remove");diff --git a/src/config/hooks.rs b/src/config/hooks.rsindex 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 abovepost_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.rsindex 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.rsindex 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.snapindex 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, [2mwt switch[0m changes directories to iWhen creating a worktree, worktrunk:-1. Runs pre-switch hooks (blocking, fail-fast)+1. Runs pre-switch hooks — blocks until complete2. Creates worktree at configured path3. 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[107m [0m [2m[0m[2m[34mwt[0m[2m switch feature # Existing branch → creates worktree[0m[2m[0m[107m [0m [2m[0m[2m[34mwt[0m[2m switch [0m[2m[36m--create[0m[2m feature # New branch and worktree[0m[2m[0m