Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
Document copy-ignored's disk-space benefit (#4022)
Maximilian Roosfa57cb63a4fa
diff --git a/README.md b/README.mdindex 0654012e9..259e9701e 100644--- a/README.md+++ b/README.md@@ -90,7 +90,7 @@ git branch -d feat</code></pre></td>- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commit messages from diffs- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews-- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees+- **[Share build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — ten worktrees get `target/`, `node_modules/`, etc without building or copying them (on APFS, btrfs, and XFS)- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique portdiff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.mdindex 167017a3d..2a6756c94 100644--- a/docs/src/content/docs/faq.md+++ b/docs/src/content/docs/faq.md@@ -55,6 +55,12 @@ These tools can be used together—run git-machete or git-town inside individualGit TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.+## How much disk do worktrees use?++Worktrees share one `.git`. Each adds a checkout of the tracked files, plus whatever gitignored build output you copy in.++On APFS, btrfs, and XFS (not ext4 or NTFS), [`wt step copy-ignored`](/step/#copy-on-write) reflinks that output, so a new worktree shares the primary worktree's disk blocks. A later build rewrites only what changed, and the rest stays shared. On one machine, 56 worktrees of a Rust repository with a 40GB `target/` came to 2.6TB by `du` and 0.7TB on disk.+## Does Worktrunk support stacked branches?Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [custom subcommands](/extending/#custom-subcommands)).diff --git a/docs/src/content/docs/step.md b/docs/src/content/docs/step.mdindex f738f9778..692184b2d 100644--- a/docs/src/content/docs/step.md+++ b/docs/src/content/docs/step.md@@ -611,16 +611,18 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was| Generated assets | Images, ML models, binaries too large for git || Environment files | `.env` (if not generated per-worktree) |-### Performance+### Copy-on-write-Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:+Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XFS (Linux), ReFS (Windows). A reflinked copy shares the source's disk blocks until one side writes. For a 14GB `target/` directory:-| Command | Time |-|---------|------|-| `cp -R` (full copy) | 2m |-| `cp -Rc` / `wt step copy-ignored` | 20s |+| Command | Time | Disk |+|---------|------|------|+| `cp -R` (full copy) | 2m | 14GB |+| `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.+On ext4 and NTFS, which have no reflink, every file is copied in full.++Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.@@ -654,7 +656,6 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` iThe `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)-- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle### Command referencediff --git a/docs/src/content/docs/worktrunk.md b/docs/src/content/docs/worktrunk.mdindex 058e90c0b..d9b40ae79 100644--- a/docs/src/content/docs/worktrunk.md+++ b/docs/src/content/docs/worktrunk.md@@ -100,7 +100,7 @@ git branch -d feat</code></pre></td>- **[LLM commit messages](/llm-commits/)** — generate commit messages from diffs- **[Merge workflow](/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](/switch/#interactive-picker)** — browse worktrees with live diff and log previews-- **[Copy build caches](/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees+- **[Share build caches](/step/#wt-step-copy-ignored)** — ten worktrees get `target/`, `node_modules/`, etc without building or copying them (on APFS, btrfs, and XFS)- **[`wt list --full`](/list/#full-mode)** — [CI status](/list/#ci-status) and [AI-generated summaries](/list/#llm-summaries) per branch- **[PR checkout](/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique portdiff --git a/plugins/worktrunk/skills/worktrunk/reference/README.md b/plugins/worktrunk/skills/worktrunk/reference/README.mdindex 0654012e9..259e9701e 100644--- a/plugins/worktrunk/skills/worktrunk/reference/README.md+++ b/plugins/worktrunk/skills/worktrunk/reference/README.md@@ -90,7 +90,7 @@ git branch -d feat</code></pre></td>- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commit messages from diffs- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews-- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees+- **[Share build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — ten worktrees get `target/`, `node_modules/`, etc without building or copying them (on APFS, btrfs, and XFS)- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique portdiff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.mdindex 6d7e27263..8989ac18b 100644--- a/plugins/worktrunk/skills/worktrunk/reference/faq.md+++ b/plugins/worktrunk/skills/worktrunk/reference/faq.md@@ -51,6 +51,12 @@ These tools can be used together—run git-machete or git-town inside individualGit TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.+## How much disk do worktrees use?++Worktrees share one `.git`. Each adds a checkout of the tracked files, plus whatever gitignored build output you copy in.++On APFS, btrfs, and XFS (not ext4 or NTFS), [`wt step copy-ignored`](https://worktrunk.dev/step/#copy-on-write) reflinks that output, so a new worktree shares the primary worktree's disk blocks. A later build rewrites only what changed, and the rest stays shared. On one machine, 56 worktrees of a Rust repository with a 40GB `target/` came to 2.6TB by `du` and 0.7TB on disk.+## Does Worktrunk support stacked branches?Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [custom subcommands](https://worktrunk.dev/extending/#custom-subcommands)).diff --git a/plugins/worktrunk/skills/worktrunk/reference/step.md b/plugins/worktrunk/skills/worktrunk/reference/step.mdindex a88b23831..bd4eccc59 100644--- a/plugins/worktrunk/skills/worktrunk/reference/step.md+++ b/plugins/worktrunk/skills/worktrunk/reference/step.md@@ -599,16 +599,18 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was| Generated assets | Images, ML models, binaries too large for git || Environment files | `.env` (if not generated per-worktree) |-### Performance+### Copy-on-write-Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:+Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XFS (Linux), ReFS (Windows). A reflinked copy shares the source's disk blocks until one side writes. For a 14GB `target/` directory:-| Command | Time |-|---------|------|-| `cp -R` (full copy) | 2m |-| `cp -Rc` / `wt step copy-ignored` | 20s |+| Command | Time | Disk |+|---------|------|------|+| `cp -R` (full copy) | 2m | 14GB |+| `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.+On ext4 and NTFS, which have no reflink, every file is copied in full.++Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.@@ -642,7 +644,6 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` iThe `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)-- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle### Command referencediff --git a/plugins/worktrunk/skills/worktrunk/reference/worktrunk.md b/plugins/worktrunk/skills/worktrunk/reference/worktrunk.mdindex 6fc3c8db0..0f6cded40 100644--- a/plugins/worktrunk/skills/worktrunk/reference/worktrunk.md+++ b/plugins/worktrunk/skills/worktrunk/reference/worktrunk.md@@ -72,7 +72,7 @@ git branch -d feat</code></pre></td>- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commit messages from diffs- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews-- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees+- **[Share build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — ten worktrees get `target/`, `node_modules/`, etc without building or copying them (on APFS, btrfs, and XFS)- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique portdiff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.mdindex 6d7e27263..8989ac18b 100644--- a/skills/worktrunk/reference/faq.md+++ b/skills/worktrunk/reference/faq.md@@ -51,6 +51,12 @@ These tools can be used together—run git-machete or git-town inside individualGit TUIs operate on a single repository. Worktrunk manages multiple worktrees, runs automation hooks, and aggregates status across branches. TUIs work inside each worktree directory.+## How much disk do worktrees use?++Worktrees share one `.git`. Each adds a checkout of the tracked files, plus whatever gitignored build output you copy in.++On APFS, btrfs, and XFS (not ext4 or NTFS), [`wt step copy-ignored`](https://worktrunk.dev/step/#copy-on-write) reflinks that output, so a new worktree shares the primary worktree's disk blocks. A later build rewrites only what changed, and the rest stays shared. On one machine, 56 worktrees of a Rust repository with a 40GB `target/` came to 2.6TB by `du` and 0.7TB on disk.+## Does Worktrunk support stacked branches?Not natively — stacked-branch workflows are a large design space, so Worktrunk treats them as an extension rather than a built-in. [`worktrunk-sync`](https://github.com/pablospe/worktrunk-sync) is a community tool that auto-detects the branch dependency tree from git history and rebases each branch onto its parent in topological order. Install with `cargo install worktrunk-sync` and run as `wt sync` (via [custom subcommands](https://worktrunk.dev/extending/#custom-subcommands)).diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.mdindex a88b23831..bd4eccc59 100644--- a/skills/worktrunk/reference/step.md+++ b/skills/worktrunk/reference/step.md@@ -599,16 +599,18 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was| Generated assets | Images, ML models, binaries too large for git || Environment files | `.env` (if not generated per-worktree) |-### Performance+### Copy-on-write-Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:+Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XFS (Linux), ReFS (Windows). A reflinked copy shares the source's disk blocks until one side writes. For a 14GB `target/` directory:-| Command | Time |-|---------|------|-| `cp -R` (full copy) | 2m |-| `cp -Rc` / `wt step copy-ignored` | 20s |+| Command | Time | Disk |+|---------|------|------|+| `cp -R` (full copy) | 2m | 14GB |+| `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.+On ext4 and NTFS, which have no reflink, every file is copied in full.++Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.@@ -642,7 +644,6 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` iThe `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)-- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle### Command referencediff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.mdindex 6fc3c8db0..0f6cded40 100644--- a/skills/worktrunk/reference/worktrunk.md+++ b/skills/worktrunk/reference/worktrunk.md@@ -72,7 +72,7 @@ git branch -d feat</code></pre></td>- **[LLM commit messages](https://worktrunk.dev/llm-commits/)** — generate commit messages from diffs- **[Merge workflow](https://worktrunk.dev/merge/)** — squash, rebase, merge, clean up in one command- **[Interactive picker](https://worktrunk.dev/switch/#interactive-picker)** — browse worktrees with live diff and log previews-- **[Copy build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — skip cold starts by sharing `target/`, `node_modules/`, etc between worktrees+- **[Share build caches](https://worktrunk.dev/step/#wt-step-copy-ignored)** — ten worktrees get `target/`, `node_modules/`, etc without building or copying them (on APFS, btrfs, and XFS)- **[`wt list --full`](https://worktrunk.dev/list/#full-mode)** — [CI status](https://worktrunk.dev/list/#ci-status) and [AI-generated summaries](https://worktrunk.dev/list/#llm-summaries) per branch- **[PR checkout](https://worktrunk.dev/switch/#pull-requests-and-merge-requests)** — `wt switch pr:123` to jump straight to a PR's branch- **[Dev server per worktree](https://worktrunk.dev/tips-patterns/#dev-server-per-worktree)** — `hash_port` template filter gives each worktree a unique portdiff --git a/src/cli/step.rs b/src/cli/step.rsindex 3af5bc952..43c59f0ca 100644--- a/src/cli/step.rs+++ b/src/cli/step.rs@@ -379,16 +379,18 @@ Without `.worktreeinclude`, the command is a no-op (it reports that nothing was| Generated assets | Images, ML models, binaries too large for git || Environment files | `.env` (if not generated per-worktree) |-## Performance+## Copy-on-write-Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB `target/` directory:+Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XFS (Linux), ReFS (Windows). A reflinked copy shares the source's disk blocks until one side writes. For a 14GB `target/` directory:-| Command | Time |-|---------|------|-| `cp -R` (full copy) | 2m |-| `cp -Rc` / `wt step copy-ignored` | 20s |+| Command | Time | Disk |+|---------|------|------|+| `cp -R` (full copy) | 2m | 14GB |+| `cp -Rc` / `wt step copy-ignored` | 20s | ~0 |-Uses per-file reflink (like `cp -Rc`) — copy time scales with file count.+On ext4 and NTFS, which have no reflink, every file is copied in full.++Reflinks are per file (like `cp -Rc`), so copy time scales with file count.Use the `post-start` hook so the copy runs in the background. Use `pre-start` instead if subsequent hooks or `--execute` command need the copied files immediately.@@ -422,7 +424,6 @@ Virtual environments contain absolute paths and can't be copied. Use `uv sync` iThe `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://code.claude.com/docs/en/desktop), which copies matching files when creating worktrees. Differences:- worktrunk copies all gitignored files by default; Claude Code requires `.worktreeinclude`. Pass `--require-include` to match Claude Code (copy nothing without `.worktreeinclude`)-- worktrunk uses copy-on-write for large directories like `target/` (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle"#)]CopyIgnored {diff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snapindex 0ca154ca2..0ae9cbe87 100644--- a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap+++ b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap@@ -145,16 +145,18 @@ Without [2m.worktreeinclude[0m, the command is a no-op (it reports that nothinGenerated assets Images, ML models, binaries too large for gitEnvironment files [2m.env[0m (if not generated per-worktree)-[1m[32mPerformance[0m+[1m[32mCopy-on-write[0m-Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB [2mtarget/[0m directory:+Files are reflinked where the filesystem supports it: APFS (macOS), btrfs and XFS (Linux), ReFS (Windows). A reflinked copy shares the source's disk blocks until one side writes. For a 14GB [2mtarget/[0m directory:- Command Time- ───────────────────────────── ────- [2mcp -R[0m (full copy) 2m- [2mcp -Rc[0m / [2mwt step copy-ignored[0m 20s+ Command Time Disk+ ───────────────────────────── ──── ────+ [2mcp -R[0m (full copy) 2m 14GB+ [2mcp -Rc[0m / [2mwt step copy-ignored[0m 20s ~0-Uses per-file reflink (like [2mcp -Rc[0m) — copy time scales with file count.+On ext4 and NTFS, which have no reflink, every file is copied in full.++Reflinks are per file (like [2mcp -Rc[0m), so copy time scales with file count.Use the [2mpost-start[0m hook so the copy runs in the background. Use [2mpre-start[0m instead if subsequent hooks or [2m--execute[0m command need the copied files immediately.@@ -186,7 +188,6 @@ Virtual environments contain absolute paths and can't be copied. Use [2muv syncThe [2m.worktreeinclude[0m pattern is shared with Claude Code on desktop, which copies matching files when creating worktrees. Differences:- worktrunk copies all gitignored files by default; Claude Code requires [2m.worktreeinclude[0m. Pass [2m--require-include[0m to match Claude Code (copy nothing without [2m.worktreeinclude[0m)-- worktrunk uses copy-on-write for large directories like [2mtarget/[0m (see Performance above)- worktrunk runs as a configurable hook in the worktree lifecycle----- stderr -----