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.mdindex 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.mdindex 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> <FROM></span>+ Source worktree branch++ Defaults to main worktree.++ <b><span class=c>--to</span></b><span class=c> <TO></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 '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></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-eachExecutes 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.mdindex 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 worktreediff --git a/docs/content/hook.md b/docs/content/hook.mdindex 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.mdindex 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> <spanShow 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> <FROM></span>+ Source worktree branch++ Defaults to main worktree.++ <b><span class=c>--to</span></b><span class=c> <TO></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 '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></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-eachExecutes 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.mdindex 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 worktreediff --git a/src/cli/mod.rs b/src/cli/mod.rsindex 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.rsindex 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///