Skip to content

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

Refactor copy-ignored docs into dedicated step page

Maximilian Roos549dd99a5df0
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index d2d55da90..a75818d8e 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -202,37 +202,14 @@ Many tasks work well in `post-start` — they'll likely be ready by the time the
### Copying untracked files
-Git worktrees share the repository but not untracked files. Common files to copy:
-
-- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`
-- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`
-- **Generated assets**: Images, ML models, binaries too large for git
-- **Environment files**: `.env` (if not generated per-worktree)
-
-Use `wt step copy-ignored` to copy files listed in `.worktreeinclude` that are also gitignored:
+Git 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 files listed in `.worktreeinclude`:
```toml
[post-create]
copy = "wt step copy-ignored"
```
-Create a `.worktreeinclude` file in the repository root listing patterns to copy (uses gitignore syntax):
-
-```gitignore
-# .worktreeinclude
-.env
-node_modules/
-target/
-.cache/
-```
-
-Files are only copied if they match **both** `.worktreeinclude` **and** are gitignored — this prevents accidentally copying tracked files.
-
-**Features:**
-- Uses copy-on-write (reflink) when available for instant, space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files (safe to re-run)
-- Skips symlinks and `.git` entries
+See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for setup, common patterns, and language-specific notes.
### Dev servers
@@ -381,22 +358,11 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for
## Language-specific tips
-Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.
-
-### Rust
-
-The `target/` directory is huge (often 1-10GB). Use `wt step copy-ignored` with a `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-target/
-```
-
-This copies `target/` using copy-on-write (reflink), cutting first build from ~68s to ~3s by reusing compiled dependencies.
+Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](https://worktrunk.dev/step/#language-specific-notes). This section covers hooks.
### Python
-Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:
+Use `uv sync` to recreate virtual environments:
```toml
[post-create]
@@ -410,23 +376,6 @@ For pip-based projects without uv:
venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"
```
-### Node.js
-
-`node_modules/` is large but mostly static. Add to `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-node_modules/
-.env
-```
-
-If the project has no native dependencies, symlinks are even faster:
-
-```toml
-[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
-```
-
### Hook flow patterns
**Progressive validation** — Quick checks before commit, thorough validation before merge:
diff --git a/.claude-plugin/skills/worktrunk/reference/step.md b/.claude-plugin/skills/worktrunk/reference/step.md
index 24af42834..17d2392fb 100644
--- a/.claude-plugin/skills/worktrunk/reference/step.md
+++ b/.claude-plugin/skills/worktrunk/reference/step.md
@@ -93,6 +93,106 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
Show debug info (-v), or also write diagnostic report (-vv)
+## wt step copy-ignored
+
+Git worktrees share the repository but not untracked files. This command copies files listed in `.worktreeinclude` to another worktree, eliminating cold starts.
+
+### Setup
+
+Create a `.worktreeinclude` file in your repository root listing patterns to copy (uses gitignore syntax):
+
+```gitignore
+# .worktreeinclude
+.env
+node_modules/
+target/
+.cache/
+```
+
+Add to your project config:
+
+```toml
+# .config/wt.toml
+[post-create]
+copy = "wt step copy-ignored"
+```
+
+### What gets copied
+
+Files are copied only if they match **both** `.worktreeinclude` **and** are gitignored. This prevents accidentally copying tracked files.
+
+### Common patterns
+
+| Type | Patterns |
+|------|----------|
+| Dependencies | `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/` |
+| Build caches | `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/` |
+| Generated assets | Images, ML models, binaries too large for git |
+| Environment files | `.env` (if not generated per-worktree) |
+
+### Features
+
+- Uses copy-on-write (reflink) when available for instant, space-efficient copies
+- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
+- Skips existing files (safe to re-run)
+- Skips symlinks and `.git` entries
+
+### Language-specific notes
+
+#### Rust
+
+The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first build from ~68s to ~3s by reusing compiled dependencies.
+
+#### Node.js
+
+`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
+
+```toml
+[post-create]
+deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+```
+
+#### Python
+
+Virtual environments contain absolute paths and can't be copied. Use `uv sync` instead — it's fast enough that copying isn't worth it.
+
+### Command reference
+
+wt step copy-ignored - Copy <b>.worktreeinclude</b> files to another worktree
+
+Copies files listed in <b>.worktreeinclude</b> that are also gitignored. Useful in
+post-create hooks to sync local config files (<b>.env</b>, IDE settings) to new
+worktrees. Skips symlinks and existing files.
+
+Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--from</span></b><span class=c> &lt;FROM&gt;</span>
+ Source worktree branch
+
+ Defaults to main worktree.
+
+ <b><span class=c>--to</span></b><span class=c> &lt;TO&gt;</span>
+ Destination worktree branch
+
+ Defaults to current worktree.
+
+ <b><span class=c>--dry-run</span></b>
+ Show what would be copied
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+
## wt step for-each
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
diff --git a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
index 3b0af2416..cfd45ebb9 100644
--- a/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
+++ b/.claude-plugin/skills/worktrunk/reference/tips-patterns.md
@@ -14,7 +14,7 @@ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
## Eliminate cold starts
-Use `wt step copy-ignored` in a `post-create` or `post-start` hook to copy gitignored files (caches, dependencies) between worktrees:
+Use [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) in a `post-create` hook to copy gitignored files (caches, dependencies) between worktrees:
```toml
[post-create]
@@ -31,7 +31,7 @@ node_modules/
target/
```
-See [Copying untracked files](https://worktrunk.dev/hook/#copying-untracked-files) for more details.
+See [`wt step copy-ignored`](https://worktrunk.dev/step/#wt-step-copy-ignored) for common patterns and language-specific notes.
## Dev server per worktree
diff --git a/docs/content/hook.md b/docs/content/hook.md
index e82b06b8d..89d94648c 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -210,37 +210,14 @@ Many tasks work well in `post-start` — they'll likely be ready by the time the
### Copying untracked files
-Git worktrees share the repository but not untracked files. Common files to copy:
-
-- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`
-- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`
-- **Generated assets**: Images, ML models, binaries too large for git
-- **Environment files**: `.env` (if not generated per-worktree)
-
-Use `wt step copy-ignored` to copy files listed in `.worktreeinclude` that are also gitignored:
+Git worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy files listed in `.worktreeinclude`:
```toml
[post-create]
copy = "wt step copy-ignored"
```
-Create a `.worktreeinclude` file in the repository root listing patterns to copy (uses gitignore syntax):
-
-```gitignore
-# .worktreeinclude
-.env
-node_modules/
-target/
-.cache/
-```
-
-Files are only copied if they match **both** `.worktreeinclude` **and** are gitignored — this prevents accidentally copying tracked files.
-
-**Features:**
-- Uses copy-on-write (reflink) when available for instant, space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files (safe to re-run)
-- Skips symlinks and `.git` entries
+See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for setup, common patterns, and language-specific notes.
### Dev servers
@@ -389,22 +366,11 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for
## Language-specific tips
-Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.
-
-### Rust
-
-The `target/` directory is huge (often 1-10GB). Use `wt step copy-ignored` with a `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-target/
-```
-
-This copies `target/` using copy-on-write (reflink), cutting first build from ~68s to ~3s by reusing compiled dependencies.
+Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes). This section covers hooks.
### Python
-Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:
+Use `uv sync` to recreate virtual environments:
```toml
[post-create]
@@ -418,23 +384,6 @@ For pip-based projects without uv:
venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"
```
-### Node.js
-
-`node_modules/` is large but mostly static. Add to `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-node_modules/
-.env
-```
-
-If the project has no native dependencies, symlinks are even faster:
-
-```toml
-[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
-```
-
### Hook flow patterns
**Progressive validation** — Quick checks before commit, thorough validation before merge:
diff --git a/docs/content/step.md b/docs/content/step.md
index 53669f3ba..055985259 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -108,6 +108,109 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
Show debug info (-v), or also write diagnostic report (-vv)
{% end %}
+## wt step copy-ignored
+
+Git worktrees share the repository but not untracked files. This command copies files listed in `.worktreeinclude` to another worktree, eliminating cold starts.
+
+### Setup
+
+Create a `.worktreeinclude` file in your repository root listing patterns to copy (uses gitignore syntax):
+
+```gitignore
+# .worktreeinclude
+.env
+node_modules/
+target/
+.cache/
+```
+
+Add to your project config:
+
+```toml
+# .config/wt.toml
+[post-create]
+copy = "wt step copy-ignored"
+```
+
+### What gets copied
+
+Files are copied only if they match **both** `.worktreeinclude` **and** are gitignored. This prevents accidentally copying tracked files.
+
+### Common patterns
+
+| Type | Patterns |
+|------|----------|
+| Dependencies | `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/` |
+| Build caches | `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/` |
+| Generated assets | Images, ML models, binaries too large for git |
+| Environment files | `.env` (if not generated per-worktree) |
+
+### Features
+
+- Uses copy-on-write (reflink) when available for instant, space-efficient copies
+- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
+- Skips existing files (safe to re-run)
+- Skips symlinks and `.git` entries
+
+### Language-specific notes
+
+#### Rust
+
+The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first build from ~68s to ~3s by reusing compiled dependencies.
+
+#### Node.js
+
+`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
+
+```toml
+[post-create]
+deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+```
+
+#### Python
+
+Virtual environments contain absolute paths and can't be copied. Use `uv sync` instead — it's fast enough that copying isn't worth it.
+
+### Command reference
+
+{% terminal() %}
+wt step copy-ignored - Copy <b>.worktreeinclude</b> files to another worktree
+
+Copies files listed in <b>.worktreeinclude</b> that are also gitignored. Useful in
+post-create hooks to sync local config files (<b>.env</b>, IDE settings) to new
+worktrees. Skips symlinks and existing files.
+
+Usage: <b><span class=c>wt step copy-ignored</span></b> <span class=c>[OPTIONS]</span>
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>--from</span></b><span class=c> &lt;FROM&gt;</span>
+ Source worktree branch
+
+ Defaults to main worktree.
+
+ <b><span class=c>--to</span></b><span class=c> &lt;TO&gt;</span>
+ Destination worktree branch
+
+ Defaults to current worktree.
+
+ <b><span class=c>--dry-run</span></b>
+ Show what would be copied
+
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Show debug info (-v), or also write diagnostic report (-vv)
+{% end %}
+
+
## wt step for-each
Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
diff --git a/docs/content/tips-patterns.md b/docs/content/tips-patterns.md
index d6d061d5a..fa0c20d74 100644
--- a/docs/content/tips-patterns.md
+++ b/docs/content/tips-patterns.md
@@ -20,7 +20,7 @@ wsc feature -- 'Fix GH #322' # Runs `claude 'Fix GH #322'`
## Eliminate cold starts
-Use `wt step copy-ignored` in a `post-create` or `post-start` hook to copy gitignored files (caches, dependencies) between worktrees:
+Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) in a `post-create` hook to copy gitignored files (caches, dependencies) between worktrees:
```toml
[post-create]
@@ -37,7 +37,7 @@ node_modules/
target/
```
-See [Copying untracked files](@/hook.md#copying-untracked-files) for more details.
+See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for common patterns and language-specific notes.
## Dev server per worktree
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 7d1086c73..fe7d73e65 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -979,6 +979,8 @@ wt step commit --show-prompt | llm -m gpt-5-nano
- [`wt merge`](@/merge.md) — Runs commit → squash → rebase → hooks → push → cleanup automatically
- [`wt hook`](@/hook.md) — Run configured hooks
+<!-- subdoc: copy-ignored -->
+
<!-- subdoc: for-each -->
"#
)]
@@ -1192,37 +1194,14 @@ Many tasks work well in `post-start` — they'll likely be ready by the time the
### Copying untracked files
-Git worktrees share the repository but not untracked files. Common files to copy:
-
-- **Dependencies**: `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/`
-- **Build caches**: `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/`
-- **Generated assets**: Images, ML models, binaries too large for git
-- **Environment files**: `.env` (if not generated per-worktree)
-
-Use `wt step copy-ignored` to copy files listed in `.worktreeinclude` that are also gitignored:
+Git worktrees share the repository but not untracked files (dependencies, caches, `.env`). Use [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) to copy files listed in `.worktreeinclude`:
```toml
[post-create]
copy = "wt step copy-ignored"
```
-Create a `.worktreeinclude` file in the repository root listing patterns to copy (uses gitignore syntax):
-
-```gitignore
-# .worktreeinclude
-.env
-node_modules/
-target/
-.cache/
-```
-
-Files are only copied if they match **both** `.worktreeinclude` **and** are gitignored — this prevents accidentally copying tracked files.
-
-**Features:**
-- Uses copy-on-write (reflink) when available for instant, space-efficient copies
-- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
-- Skips existing files (safe to re-run)
-- Skips symlinks and `.git` entries
+See [`wt step copy-ignored`](@/step.md#wt-step-copy-ignored) for setup, common patterns, and language-specific notes.
### Dev servers
@@ -1371,22 +1350,11 @@ The `--var KEY=VALUE` flag overrides built-in template variables — useful for
## Language-specific tips
-Each ecosystem has quirks that affect hook design. Contributions welcome for languages not listed.
-
-### Rust
-
-The `target/` directory is huge (often 1-10GB). Use `wt step copy-ignored` with a `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-target/
-```
-
-This copies `target/` using copy-on-write (reflink), cutting first build from ~68s to ~3s by reusing compiled dependencies.
+Each ecosystem has quirks that affect hook design. For copying dependencies and caches between worktrees, see [`wt step copy-ignored`](@/step.md#language-specific-notes). This section covers hooks.
### Python
-Virtual environments contain absolute paths and can't be copied between directories. Use `uv sync` to recreate — it's fast enough that copying isn't worth it:
+Use `uv sync` to recreate virtual environments:
```toml
[post-create]
@@ -1400,23 +1368,6 @@ For pip-based projects without uv:
venv = "python -m venv .venv && .venv/bin/pip install -r requirements.txt"
```
-### Node.js
-
-`node_modules/` is large but mostly static. Add to `.worktreeinclude`:
-
-```gitignore
-# .worktreeinclude
-node_modules/
-.env
-```
-
-If the project has no native dependencies, symlinks are even faster:
-
-```toml
-[post-create]
-deps = "ln -sf {{ main_worktree_path }}/node_modules ."
-```
-
### Hook flow patterns
**Progressive validation** — Quick checks before commit, thorough validation before merge:
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 6bda01002..80d112729 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -82,6 +82,69 @@ pub enum StepCommand {
/// Useful in post-create hooks to sync local config files
/// (`.env`, IDE settings) 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 files listed in `.worktreeinclude` to another worktree, eliminating cold starts.
+
+## Setup
+
+Create a `.worktreeinclude` file in your repository root listing patterns to copy (uses gitignore syntax):
+
+```gitignore
+# .worktreeinclude
+.env
+node_modules/
+target/
+.cache/
+```
+
+Add to your project config:
+
+```toml
+# .config/wt.toml
+[post-create]
+copy = "wt step copy-ignored"
+```
+
+## What gets copied
+
+Files are copied only if they match **both** `.worktreeinclude` **and** are gitignored. This prevents accidentally copying tracked files.
+
+## Common patterns
+
+| Type | Patterns |
+|------|----------|
+| Dependencies | `node_modules/`, `.venv/`, `target/`, `vendor/`, `Pods/` |
+| Build caches | `.cache/`, `.next/`, `.parcel-cache/`, `.turbo/` |
+| Generated assets | Images, ML models, binaries too large for git |
+| Environment files | `.env` (if not generated per-worktree) |
+
+## Features
+
+- Uses copy-on-write (reflink) when available for instant, space-efficient copies
+- Handles nested `.gitignore` files, global excludes, and `.git/info/exclude`
+- Skips existing files (safe to re-run)
+- Skips symlinks and `.git` entries
+
+## Language-specific notes
+
+### Rust
+
+The `target/` directory is huge (often 1-10GB). Copying with reflink cuts first build from ~68s to ~3s by reusing compiled dependencies.
+
+### Node.js
+
+`node_modules/` is large but mostly static. If the project has no native dependencies, symlinks are even faster:
+
+```toml
+[post-create]
+deps = "ln -sf {{ main_worktree_path }}/node_modules ."
+```
+
+### Python
+
+Virtual environments contain absolute paths and can't be copied. Use `uv sync` instead — it's fast enough that copying isn't worth it.
+"#
+ )]
CopyIgnored {
/// Source worktree branch
///