Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: document post-start/pre-remove cleanup pattern (#646)
Maximilian Roos5819e3f9e166
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.mdindex 84eddea34..88edce442 100644--- a/.claude-plugin/skills/worktrunk/reference/hook.md+++ b/.claude-plugin/skills/worktrunk/reference/hook.md@@ -276,6 +276,8 @@ Both run when creating a worktree. The difference:Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.+### Copying untracked filesGit worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files:@@ -294,6 +296,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:```toml[post-start]server = "npm run dev -- --port {{ branch | hash_port }}"++[pre-remove]+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"```The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:diff --git a/docs/content/hook.md b/docs/content/hook.mdindex 0ab56a9f3..72c194f3e 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -284,6 +284,8 @@ Both run when creating a worktree. The difference:Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.+### Copying untracked filesGit worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files:@@ -302,6 +304,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:```toml[post-start]server = "npm run dev -- --port {{ branch | hash_port }}"++[pre-remove]+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"```The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`:diff --git a/src/cli/mod.rs b/src/cli/mod.rsindex dd8c04b5d..252c1e1bc 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1272,6 +1272,8 @@ Both run when creating a worktree. The difference:Many tasks work well in `post-start` — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer `post-start` for faster worktree creation.+Background processes spawned by `post-start` outlive the worktree — pair them with `pre-remove` hooks to clean up. See [Dev servers](#dev-servers) and [Databases](#databases) for examples.+### Copying untracked filesGit worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files:@@ -1290,6 +1292,9 @@ Run a dev server per worktree on a deterministic port using `hash_port`:```toml[post-start]server = "npm run dev -- --port {{ branch | hash_port }}"++[pre-remove]+server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"```The port is stable across machines and restarts — `feature-api` always gets the same port. Show it in `wt list`: