Skip to content

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.md
index 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-create
Both 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 them
Git 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 servers
Run 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.md
index 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://c
wt step copy-ignored - Copy gitignored files to another worktree
Copies 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.md
index 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 worktree
diff --git a/docs/content/hook.md b/docs/content/hook.md
index 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-create
Both 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 them
Git 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 servers
Run a dev server per worktree on a deterministic port using `hash_port`:
diff --git a/docs/content/step.md b/docs/content/step.md
index 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://c
wt step copy-ignored - Copy gitignored files to another worktree
Copies 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.md
index 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 worktree
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 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-create
Both 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 them
Git 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 servers
Run a dev server per worktree on a deterministic port using `hash_port`:
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 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