Skip to content

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

docs(extending): add recipe for carrying changes to a new worktree (#2083)

Worktrunk Bot61b0e5ae11ae
diff --git a/docs/content/extending.md b/docs/content/extending.md
index e42af7ef5..98c30b284 100644
--- a/docs/content/extending.md
+++ b/docs/content/extending.md
@@ -130,6 +130,36 @@ When both user and project config define the same alias name, both run — user
Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
+### Recipe: move or copy in-progress changes to a new worktree
+
+Aliases compose existing commands into richer workflows. These three aliases wrap `wt switch --create` with git's stash and diff plumbing so staged, unstaged, and untracked changes can follow you into a new worktree:
+
+```toml
+# .config/wt.toml
+[aliases]
+# Move all in-progress changes (staged + unstaged + untracked) to a new
+# worktree. Source becomes clean.
+# wt step move-changes --var to=feature-xyz
+move-changes = '''if git diff --quiet HEAD && test -z "$(git ls-files --others --exclude-standard)"; then wt switch --create {{ to }}; else git stash push --include-untracked --quiet && wt switch --create {{ to }} --execute='git stash pop --index'; fi'''
+
+# Copy all changes (staged + unstaged + untracked) to a new worktree.
+# Source is unchanged.
+# wt step copy-changes --var to=feature-xyz
+copy-changes = '''if git diff --quiet HEAD && test -z "$(git ls-files --others --exclude-standard)"; then wt switch --create {{ to }}; else git stash push --include-untracked --quiet && git stash apply --index --quiet && wt switch --create {{ to }} --execute='git stash pop --index'; fi'''
+
+# Copy only staged changes to a new worktree. Source is unchanged.
+# wt step copy-staged --var to=feature-xyz
+copy-staged = '''if git diff --cached --quiet; then wt switch --create {{ to }}; else p=$(mktemp) && git diff --cached > "$p" && wt switch --create {{ to }} --execute="git apply --index '$p' && rm '$p'"; fi'''
+```
+
+How they work:
+
+- **`move-changes`** stashes everything (`--include-untracked`), creates the new worktree, then runs `git stash pop --index` inside it via `--execute`. The `--index` flag preserves the staged/unstaged split; the clean-state guard avoids touching a pre-existing stash.
+- **`copy-changes`** adds one extra step — `git stash apply --index --quiet` right after the push — to restore the source worktree before the pop happens in the new one. Both worktrees end up with identical in-progress state, untracked files included.
+- **`copy-staged`** writes `git diff --cached` to a tempfile and applies it with `git apply --index` in the new worktree. A diff (rather than `git stash --staged`) handles files where staged and unstaged hunks overlap on the same lines.
+
+Because an inner `wt switch --create` inside an alias [propagates its `cd` to the parent shell](@/step.md#aliases), all three drop the shell in the new worktree directly.
+
See [`wt step` — Aliases](@/step.md#aliases) for the full reference.
## External subcommands
diff --git a/skills/worktrunk/reference/extending.md b/skills/worktrunk/reference/extending.md
index 6d6b7620e..3f886a533 100644
--- a/skills/worktrunk/reference/extending.md
+++ b/skills/worktrunk/reference/extending.md
@@ -127,6 +127,36 @@ When both user and project config define the same alias name, both run — user
Alias names that collide with built-in step commands (`commit`, `squash`, `rebase`, etc.) are shadowed by the built-in.
+### Recipe: move or copy in-progress changes to a new worktree
+
+Aliases compose existing commands into richer workflows. These three aliases wrap `wt switch --create` with git's stash and diff plumbing so staged, unstaged, and untracked changes can follow you into a new worktree:
+
+```toml
+# .config/wt.toml
+[aliases]
+# Move all in-progress changes (staged + unstaged + untracked) to a new
+# worktree. Source becomes clean.
+# wt step move-changes --var to=feature-xyz
+move-changes = '''if git diff --quiet HEAD && test -z "$(git ls-files --others --exclude-standard)"; then wt switch --create {{ to }}; else git stash push --include-untracked --quiet && wt switch --create {{ to }} --execute='git stash pop --index'; fi'''
+
+# Copy all changes (staged + unstaged + untracked) to a new worktree.
+# Source is unchanged.
+# wt step copy-changes --var to=feature-xyz
+copy-changes = '''if git diff --quiet HEAD && test -z "$(git ls-files --others --exclude-standard)"; then wt switch --create {{ to }}; else git stash push --include-untracked --quiet && git stash apply --index --quiet && wt switch --create {{ to }} --execute='git stash pop --index'; fi'''
+
+# Copy only staged changes to a new worktree. Source is unchanged.
+# wt step copy-staged --var to=feature-xyz
+copy-staged = '''if git diff --cached --quiet; then wt switch --create {{ to }}; else p=$(mktemp) && git diff --cached > "$p" && wt switch --create {{ to }} --execute="git apply --index '$p' && rm '$p'"; fi'''
+```
+
+How they work:
+
+- **`move-changes`** stashes everything (`--include-untracked`), creates the new worktree, then runs `git stash pop --index` inside it via `--execute`. The `--index` flag preserves the staged/unstaged split; the clean-state guard avoids touching a pre-existing stash.
+- **`copy-changes`** adds one extra step — `git stash apply --index --quiet` right after the push — to restore the source worktree before the pop happens in the new one. Both worktrees end up with identical in-progress state, untracked files included.
+- **`copy-staged`** writes `git diff --cached` to a tempfile and applies it with `git apply --index` in the new worktree. A diff (rather than `git stash --staged`) handles files where staged and unstaged hunks overlap on the same lines.
+
+Because an inner `wt switch --create` inside an alias [propagates its `cd` to the parent shell](https://worktrunk.dev/step/#aliases), all three drop the shell in the new worktree directly.
+
See [`wt step` — Aliases](https://worktrunk.dev/step/#aliases) for the full reference.
## External subcommands