Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs: lead with post-start hooks instead of post-create (#733)
Maximilian Roos33971aaf22d0
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.mdindex 61ae997b3..eb66e55cf 100644--- a/.claude-plugin/skills/worktrunk/reference/hook.md+++ b/.claude-plugin/skills/worktrunk/reference/hook.md@@ -8,8 +8,8 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|-| `post-create` | After worktree created | Yes | No || `post-start` | After worktree created | No (background) | No |+| `post-create` | After worktree created | Yes | No || `post-switch` | After every switch | No (background) | No || `pre-commit` | Before commit during merge | Yes | Yes || `pre-merge` | Before merging to target | Yes | Yes |@@ -19,23 +19,24 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au**Blocking**: Command waits for hook to complete before continuing.**Fail-fast**: First failure aborts the operation.-### post-create+### post-start-Copying caches, installing dependencies, generating environment files.+Dev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml-[post-create]+[post-start]copy = "wt step copy-ignored"-install = "npm ci"+server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-start+### post-create-Dev servers, long builds, file watchers. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.+Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.```toml-[post-start]-server = "npm run dev -- --port {{ branch | hash_port }}"+[post-create]+install = "npm ci"+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```### post-switch@@ -276,14 +277,14 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for## Designing effective hooks-### post-create vs post-start+### post-start vs post-createBoth run when creating a worktree. The difference:| Hook | Execution | Best for ||------|-----------|----------|-| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) || `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |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.@@ -294,10 +295,12 @@ Background processes spawned by `post-start` outlive the worktree — pair themGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) copies gitignored files between worktrees:```toml-[post-create]+[post-start]copy = "wt step copy-ignored"```+Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.+### Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.mdindex 531e5e417..7aba69b74 100644--- a/.claude-plugin/skills/worktrunk/reference/step.md+++ b/.claude-plugin/skills/worktrunk/reference/step.md@@ -234,7 +234,7 @@ Add to the project config:```toml# .config/wt.toml-[post-create]+[post-start]copy = "wt step copy-ignored"```@@ -278,7 +278,7 @@ Reflink copies share disk blocks until modified — no data is actually copied.Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.-If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.+Use the `post-start` hook so the copy runs in the background. Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.### Language-specific notes@@ -312,9 +312,9 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://cwt step copy-ignored - Copy gitignored files to another worktreeCopies gitignored files to another worktree. By default copies all gitignored-files; use <b>.worktreeinclude</b> to limit what gets copied. Useful in post-create-hooks to sync local config files (<b>.env</b>, IDE settings) to new worktrees. Skips-symlinks and existing files.+files; use <b>.worktreeinclude</b> to limit what gets copied. Useful in hooks to copy+build caches and dependencies to new worktrees. Skips symlinks and existing+files.Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.mdindex 9210ab308..5c60344da 100644--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md@@ -14,14 +14,15 @@ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`## Eliminate cold starts-Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) in a `post-create` hook to copy gitignored files (caches, dependencies, `.env`) between worktrees:+Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:```toml-[post-create]+[post-start]copy = "wt step copy-ignored"-install = "npm ci"```+Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for details.## Dev server per worktreediff --git a/docs/content/hook.md b/docs/content/hook.mdindex 40f30dc7c..48a5bc73e 100644--- a/docs/content/hook.md+++ b/docs/content/hook.md@@ -16,8 +16,8 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|-| `post-create` | After worktree created | Yes | No || `post-start` | After worktree created | No (background) | No |+| `post-create` | After worktree created | Yes | No || `post-switch` | After every switch | No (background) | No || `pre-commit` | Before commit during merge | Yes | Yes || `pre-merge` | Before merging to target | Yes | Yes |@@ -27,23 +27,24 @@ Hooks are shell commands that run at key points in the worktree lifecycle — au**Blocking**: Command waits for hook to complete before continuing.**Fail-fast**: First failure aborts the operation.-### post-create+### post-start-Copying caches, installing dependencies, generating environment files.+Dev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml-[post-create]+[post-start]copy = "wt step copy-ignored"-install = "npm ci"+server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-start+### post-create-Dev servers, long builds, file watchers. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.+Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.```toml-[post-start]-server = "npm run dev -- --port {{ branch | hash_port }}"+[post-create]+install = "npm ci"+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```### post-switch@@ -284,14 +285,14 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for## Designing effective hooks-### post-create vs post-start+### post-start vs post-createBoth run when creating a worktree. The difference:| Hook | Execution | Best for ||------|-----------|----------|-| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) || `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |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.@@ -302,10 +303,12 @@ Background processes spawned by `post-start` outlive the worktree — pair themGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:```toml-[post-create]+[post-start]copy = "wt step copy-ignored"```+Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.+### Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:diff --git a/docs/content/step.md b/docs/content/step.mdindex 298728074..84d6a49ae 100644--- a/docs/content/step.md+++ b/docs/content/step.md@@ -253,7 +253,7 @@ Add to the project config:```toml# .config/wt.toml-[post-create]+[post-start]copy = "wt step copy-ignored"```@@ -297,7 +297,7 @@ Reflink copies share disk blocks until modified — no data is actually copied.Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.-If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.+Use the `post-start` hook so the copy runs in the background. Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.### Language-specific notes@@ -332,9 +332,9 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://cwt step copy-ignored - Copy gitignored files to another worktreeCopies gitignored files to another worktree. By default copies all gitignored-files; use <b>.worktreeinclude</b> to limit what gets copied. Useful in post-create-hooks to sync local config files (<b>.env</b>, IDE settings) to new worktrees. Skips-symlinks and existing files.+files; use <b>.worktreeinclude</b> to limit what gets copied. Useful in hooks to copy+build caches and dependencies to new worktrees. Skips symlinks and existing+files.Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.mdindex 6fd6e0e5b..5370d87fa 100644--- a/docs/content/tips-patterns.md+++ b/docs/content/tips-patterns.md@@ -20,14 +20,15 @@ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`## Eliminate cold starts-Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) in a `post-create` hook to copy gitignored files (caches, dependencies, `.env`) between worktrees:+Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy gitignored files (caches, dependencies, `.env`) between worktrees:```toml-[post-create]+[post-start]copy = "wt step copy-ignored"-install = "npm ci"```+Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.+All gitignored files are copied by default. To limit what gets copied, create `.worktreeinclude` with patterns — files must be both gitignored and listed. See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for details.## Dev server per worktreediff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 0ffe810d4..ac3a3e46e 100644--- a/src/cli/mod.rs+++ b/src/cli/mod.rs@@ -1026,8 +1026,8 @@ wt step push| Hook | When | Blocking | Fail-fast ||------|------|----------|-----------|-| `post-create` | After worktree created | Yes | No || `post-start` | After worktree created | No (background) | No |+| `post-create` | After worktree created | Yes | No || `post-switch` | After every switch | No (background) | No || `pre-commit` | Before commit during merge | Yes | Yes || `pre-merge` | Before merging to target | Yes | Yes |@@ -1037,23 +1037,24 @@ wt step push**Blocking**: Command waits for hook to complete before continuing.**Fail-fast**: First failure aborts the operation.-### post-create+### post-start-Copying caches, installing dependencies, generating environment files.+Dev servers, long builds, file watchers, copying caches. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.```toml-[post-create]+[post-start]copy = "wt step copy-ignored"-install = "npm ci"+server = "npm run dev -- --port {{ branch | hash_port }}"```-### post-start+### post-create-Dev servers, long builds, file watchers. Output logged to `.git/wt-logs/{branch}-{source}-post-start-{name}.log`.+Tasks that must complete before `post-start` hooks or `--execute` run: dependency installation, environment file generation.```toml-[post-start]-server = "npm run dev -- --port {{ branch | hash_port }}"+[post-create]+install = "npm ci"+env = "echo 'PORT={{ branch | hash_port }}' > .env.local"```### post-switch@@ -1294,14 +1295,14 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for## Designing effective hooks-### post-create vs post-start+### post-start vs post-createBoth run when creating a worktree. The difference:| Hook | Execution | Best for ||------|-----------|----------|-| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) || `post-start` | Background, parallel | Long-running tasks that don't block worktree creation |+| `post-create` | Blocks until complete | Tasks the developer needs before working (dependency install) |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.@@ -1312,10 +1313,12 @@ Background processes spawned by `post-start` outlive the worktree — pair themGit worktrees share the repository but not untracked files. [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) copies gitignored files between worktrees:```toml-[post-create]+[post-start]copy = "wt step copy-ignored"```+Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.+### Dev serversRun a dev server per worktree on a deterministic port using `hash_port`:diff --git a/src/cli/step.rs b/src/cli/step.rsindex ca72c1482..38e322dd7 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -155,8 +155,8 @@ wt step squash --show-prompt | less////// Copies gitignored files to another worktree. By default copies all/// gitignored files; use `.worktreeinclude` to limit what gets copied.- /// Useful in post-create hooks to sync local config files (`.env`, IDE- /// settings) to new worktrees. Skips symlinks and existing files.+ /// Useful in hooks to copy build caches and dependencies to new worktrees.+ /// Skips symlinks and existing files.#[command(after_long_help = r#"Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.@@ -166,7 +166,7 @@ Add to the project config:```toml# .config/wt.toml-[post-create]+[post-start]copy = "wt step copy-ignored"```@@ -210,7 +210,7 @@ Reflink copies share disk blocks until modified — no data is actually copied.Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.-If the files are needed before any commands run in the worktree, put `wt step copy-ignored` in the `post-create` hook. Otherwise use the `post-start` hook so the copy runs in the background.+Use the `post-start` hook so the copy runs in the background. Use `post-create` instead if subsequent hooks or `--execute` command need the copied files immediately.## Language-specific notes