| name | merge-worktree |
| description | Merge current worktree branch into the original branch, resolve conflicts with AI, then mark worktree for cleanup |
Merge Worktree
Merge the current worktree's branch into the original (parent) branch. Resolves merge conflicts intelligently. Marks the worktree for cleanup after successful merge.
Instructions
1. Detect Context
Run these commands to understand the current state:
git rev-parse --git-common-dir
git rev-parse --git-dir
git rev-parse --show-toplevel
git rev-parse --abbrev-ref HEAD
git worktree list --porcelain
Determine:
WORKTREE_NAME: extracted from current branch (strip worktree- prefix) or directory name
WORKTREE_BRANCH: current branch (e.g., worktree-bold-fox-gjac)
MAIN_TREE_PATH: path of the main worktree (first entry in git worktree list)
PARENT_BRANCH: branch checked out in the main worktree
If NOT in a worktree, tell the user and exit. This skill is designed to run from inside a worktree session.
2. Pre-merge Check
git status --porcelain
If there are uncommitted changes:
.claude/settings.json: This file is auto-managed by Claude Code at runtime. Deep-compare (parse JSON, compare key-value pairs ignoring order) against the committed version. If semantically equivalent, git restore it. If there are real value differences, git restore it anyway — runtime settings changes are ephemeral and should not be merged.
- Other files: Commit them first using the
/commit skill or ask the user.
3. Commit Plan Files
Plan files are versioned artifacts that should travel with the branch. Before merging, ensure any plan files created during this worktree session are committed.
PLANS_DIR=$(git rev-parse --show-toplevel)/plans
if [ -d "$PLANS_DIR" ]; then
git status --porcelain "$PLANS_DIR"
fi
If there are uncommitted plan files:
- Stage them:
git add plans/
- Commit with message:
chore: commit plan files from worktree session
This prevents plan files from being orphaned when the worktree is removed (gitignored files and untracked files don't survive cwrm).
4. Check Commits to Merge
git rev-list --count <PARENT_BRANCH>..<WORKTREE_BRANCH>
If 0 commits ahead, report "Already up to date" and exit.
5. Check Main Tree State
Before merging, verify the main tree has no uncommitted changes:
git -C <MAIN_TREE_PATH> status --porcelain
If the main tree has uncommitted changes, warn the user and ask them to commit or stash first. Do NOT proceed with the merge — it will mix their uncommitted work with the merge result.
6. Attempt Merge
Run the merge from the main tree:
git -C <MAIN_TREE_PATH> merge --no-edit <WORKTREE_BRANCH>
If merge succeeds: Report success with commit count, skip to step 8.
If merge fails (conflicts): Continue to step 7.
7. Resolve Conflicts
Do NOT abort the merge. Instead:
-
List conflicting files:
git -C <MAIN_TREE_PATH> diff --name-only --diff-filter=U
-
For each conflicting file:
- Read the file (it has conflict markers
<<<<<<<, =======, >>>>>>>)
- Read the worktree's version:
git show <WORKTREE_BRANCH>:<file>
- Read the parent branch's version:
git show <PARENT_BRANCH>:<file>
- For JSON files (
.claude/settings.json, etc.): do a deep comparison — parse both sides and check if the actual key-value pairs are semantically equivalent (ignoring key ordering, whitespace). If equivalent, keep the parent branch's version. Only treat as a real conflict if values differ.
- For other files: resolve the conflict by understanding both sides' intent
- Write the resolved file
- Stage it:
git -C <MAIN_TREE_PATH> add <file>
-
After all conflicts resolved:
git -C <MAIN_TREE_PATH> commit --no-edit
-
If you cannot confidently resolve a conflict, leave it and tell the user which files need manual attention.
8. Mark for Cleanup
After successful merge, tell the user:
Merged <N> commit(s) from <WORKTREE_BRANCH> into <PARENT_BRANCH>.
This worktree is now safe to remove:
cwrm --no-merge <WORKTREE_NAME>
Or continue working — run /merge-worktree again later to sync new commits.
Important
- Never force-push or rebase the parent branch
- Never delete the worktree branch —
cwrm handles that
- Prefer the worktree's version when both sides changed the same thing and intent is unclear (the worktree has the newer work)
- Main tree uncommitted changes are checked in step 5 — do not skip this check