---
name: "worktree-merge"
description: "Squash-merge a git worktree branch into the target branch with structured commit messages"
short_desc: "Worktree squash-merge with structured commit messages"
version: "1.0.0"
tags: ["git", "worktree", "merge", "commit"]
---

# Merge Worktree Skill

Squash-merge the current worktree branch back into the target branch with a comprehensive, structured commit message.

## When to Use

- After completing work in a git worktree
- When you want to squash multiple WIP commits into a single clean commit
- Before pushing feature work back to the main branch
- When working with Claude Code's worktree isolation (`EnterWorktree`)

## Workflow

### Phase 1: Validation

1. **Verify worktree**: Check if the current git directory is a worktree.

```bash
git rev-parse --git-dir
```

The output must contain `/worktrees/`. If not, stop and tell the user:
> "This skill must be run from inside a git worktree. Use worktree isolation to create one first."

2. **Identify current branch**: `git branch --show-current`

3. **Resolve target branch**:
   - If an argument is provided, use it as the target branch
   - Otherwise, detect default: check `main`, then `master`
   - If neither exists, ask the user

4. **Identify original repo path**: Use `git rev-parse --git-common-dir` to find the main repo's git directory, then derive its working directory (parent).

5. **Clean working tree**: Run `git status --porcelain`. If uncommitted changes exist, stop and ask the user to commit or stash first.

### Phase 2: Research

This is the most critical phase. Deeply understand the changes before writing any commit message.

1. **Commit history**: `git log --oneline <target>..HEAD`
2. **File change summary**: `git diff <target>...HEAD --stat`
3. **Full diff**: `git diff <target>...HEAD` — read carefully
4. **Read key files**: For the most significantly changed files (largest diffs, new files, deleted files), read full context
5. **Categorize changes**:
   - Features (new functionality)
   - Fixes (bug corrections)
   - Refactors (code restructuring without behavior change)
   - Tests (new or updated tests)
   - Docs (documentation changes)
   - Config/Chore (build, CI, tooling, dependencies)
6. **Identify dominant type**: Determine which conventional commit type (`feat`, `fix`, `refactor`, `docs`, `chore`, `test`) best represents the overall work

### Phase 3: Target Branch Preparation

1. Check target branch state: `git -C <original-repo-path> log --oneline -10 <target>`

2. **Detect stray WIP commits**: If the target branch has commits starting with `wip:`, `auto-commit`, `WIP`, warn the user and ask if they want to reset to the last clean commit before merging.

3. **Fetch latest** (if remote exists):
```bash
git -C <original-repo-path> fetch origin <target> 2>/dev/null
```

### Phase 4: Squash Merge

1. Checkout target in original repo:
```bash
git -C <original-repo-path> checkout <target>
```

2. Perform squash merge:
```bash
git -C <original-repo-path> merge --squash <worktree-branch>
```

3. **Handle conflicts**: If conflicts occur:
   - List all conflicted files
   - Show conflict markers
   - **Stop and report** — do NOT auto-resolve
   - Tell user to resolve in the original repo and re-run

### Phase 5: Commit

Based on Phase 2 research, craft a commit message with this **exact structure**:

```
<type>: <concise summary in imperative mood, max 72 chars>

<2-4 sentences explaining what was done and WHY. Focus on motivation
and high-level approach, not implementation details.>

Changes:
- <grouped bullet points of what changed>
- <use sub-bullets for details within a group>

Co-Authored-By: Claude <noreply@anthropic.com>
```

**Rules:**
- `<type>`: one of `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
- If changes span multiple types, use the dominant one
- Summary: imperative mood ("add", "fix", "refactor"), no period, max 72 chars
- Body: explain *why* and *context*, not just *what*
- Changes: group related items, most important first

Create the commit using a heredoc:
```bash
git -C <original-repo-path> commit -m "$(cat <<'EOF'
<commit message>
EOF
)"
```

### Phase 6: Verification

1. Confirm: `git -C <original-repo-path> log --oneline -3`

2. Report to user:
   - Final commit hash and summary
   - Which branch it was merged into
   - Reminder: worktree branch still exists — `git worktree remove <path>` to clean up
   - Reminder: `git push` if they want to push to remote

## Safety Rules

- **Never force-push** or use destructive git operations without explicit user confirmation
- **Never skip pre-commit hooks** (`--no-verify`)
- If anything unexpected happens, **stop and explain** rather than guessing
- Commit message quality is paramount — take time in Phase 2 to truly understand the changes
