Skip to content

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.md
index 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 port
diff --git a/docs/src/content/docs/faq.md b/docs/src/content/docs/faq.md
index 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 individual
Git 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.md
index 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` i
The `.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 reference
diff --git a/docs/src/content/docs/worktrunk.md b/docs/src/content/docs/worktrunk.md
index 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 port
diff --git a/plugins/worktrunk/skills/worktrunk/reference/README.md b/plugins/worktrunk/skills/worktrunk/reference/README.md
index 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 port
diff --git a/plugins/worktrunk/skills/worktrunk/reference/faq.md b/plugins/worktrunk/skills/worktrunk/reference/faq.md
index 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 individual
Git 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.md
index 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` i
The `.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 reference
diff --git a/plugins/worktrunk/skills/worktrunk/reference/worktrunk.md b/plugins/worktrunk/skills/worktrunk/reference/worktrunk.md
index 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 port
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index 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 individual
Git 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.md
index 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` i
The `.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 reference
diff --git a/skills/worktrunk/reference/worktrunk.md b/skills/worktrunk/reference/worktrunk.md
index 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 port
diff --git a/src/cli/step.rs b/src/cli/step.rs
index 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` i
The `.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.snap
index 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 .worktreeinclude, the command is a no-op (it reports that nothin
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.
@@ -186,7 +188,6 @@ Virtual environments contain absolute paths and can't be copied. Use uv sync
The .worktreeinclude 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 .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
----- stderr -----