merge-worktree
Use when only part of a worktree needs to come back into the current branch: selective merge (file, patch, cherry-pick, multi-worktree) and the post-merge cleanup. Complements finish.
SKILL.mdskills/merge-worktree/SKILL.md
GitHubmerge-worktree
Brings the work from one or several worktrees back into the current branch when a full merge
isn't the right fit (we only want part of the content, or we want to review before validating).
Sits at step 11 of WORKFLOW.md, just upstream of finish: here we choose what to
bring back, finish then tidies away the worktree that has become useless.
When
- A single feature, a single file to retrieve from a worktree.
- A worktree contains several changes and only some of them are ripe.
- The content needs reviewing before validating the merge (no automatic commit).
- Several worktrees have to converge into a single integration branch.
Steps
- Spot the active worktrees:
git worktree list, check the path and branch of each one before doing anything. Know where you stand: whengit rev-parse --git-dirandgit rev-parse --git-common-dirdiffer, you are inside a linked worktree and not in the main checkout. A detached HEAD is a state to resolve before removing or merging anything, never a branch to delete from under. - Choose the strategy according to the need:
- Targeted file(s): we know exactly what to retrieve, everything else is ignored:
git checkout <worktree-branch> -- path/file - Interactive patch: we want to pick hunk by hunk within a file:
git checkout -p <worktree-branch> -- path/file - Cherry-pick without commit: a specific commit from the worktree, but we want to drop
some files from the commit before validating:
git cherry-pick --no-commit <sha>thengit restore --staged path/file-to-exclude - Merge under review: all of the branch's content, but a last look before committing:
git merge --no-commit --no-ff <worktree-branch>then re-read the staged diff (git diff --staged) beforegit commit. - Multi-worktree: several branches have to converge into a single integration branch: repeat the merge-under-review per branch, one at a time, resolving conflicts before moving on to the next.
- Neighbouring branches that overlap: when it is unclear which branch should be the base or in what order
they fold in, decide that first, read-only, before any merge command:
references/01-consolidating-branches.md.
- Targeted file(s): we know exactly what to retrieve, everything else is ignored:
- Validate: commit once the content has been checked (never an automatic commit on a cherry-pick/merge until the staged diff has been re-read).
- Clean up: list the remaining worktrees (
git worktree list), remove the one(s) that have become useless (git worktree remove <path>), thengit worktree pruneif orphan entries remain (worktree deleted by hand, external drive unplugged…). Remove only worktrees this task created or that the operator named; one made by a tool or by someone else is left in place and mentioned. Never remove the worktree you are standing in from inside it.
| § | Covers | Read it when | File |
|---|---|---|---|
| 1 | Consolidating neighbouring branches: roster, shared read-only plan file, one reader per branch, rounds, conclusion | several branches overlap and the base and order are not decided | 01-consolidating-branches.md |
Output / checkpoint
The targeted content merged into the current branch, the source worktree(s) removed cleanly.
If the step chains into finish, that block takes over for the task's main worktree and updates
the integration base.
Guardrails
- Never a
git merge/cherry-pickwithout--no-commitwhen there's any doubt about the content: always re-read the staged diff before validating. - Don't confuse it with
finish:finishcloses a whole task after the MR has been merged by a human;merge-worktreeis used during development, for selective or multi-source merges. - Merge conflict: resolve file by file, never
git checkout --theirs/--oursen masse without re-reading: it silently overwrites the other side. - Files modified locally on top of the worktree: stash or commit before merging, otherwise the merge can fail or mix in unwanted changes.
- Stale worktree (path gone, branch deleted on the remote):
git worktree prunebefore taking it over again, don't force aremoveon an already-broken entry without checkinggit worktree listfirst.
Origin
Idea taken from: a market context-engineering kit,
plugins/git/skills/git-worktrees/SKILL.md, "How to Merge Worktree" section. Mechanism rewritten
our way (mentis template, articulation with finish).
The consolidation of overlapping branches (§1) is the mechanism of the standup skill of claude-mem
(Apache-2.0, read 2026-10-02): a read-only shared room, one agent per branch, rounds driven by a facilitator, a
conclusion written by the facilitator. Rewritten in our words and without its helper scripts, since a plain file
and a lock are enough; no text copied, so the NOTICE obligations do not apply. The worktree-detection and
removal-scope rules of step 1 and step 4 come from the using-git-worktrees and
finishing-a-development-branch skills of superpowers (MIT, same date), rewritten.