merge-resolve

Files (6)

• SKILL.md
• batch-resolve.py · scripts/
• conflict-pick.py · scripts/
• conflict-summary.py · scripts/
• git_utils.py · scripts/
• lockfile-resolve.py · scripts/

SKILL.md (first lines)

# merge-resolve

Resolve merge conflicts using the structural merge chain: mergiraf → rerere → kdiff3.

> **File IO delegation**: This skill does NOT hold `Read`, `Edit`, `Write`, or `Glob`. For
> per-file conflict inspection or manual edits, delegate to:
> - **cheez-read** — inspect conflicted files, view conflict hunks, list directory contents
> - **cheez-search** — locate conflict markers, search for related symbols across the tree
> - **cheez-write** — apply resolved content with hash anchors
>
> The bash-driven flows below (git, mergiraf, python scripts) handle the bulk of resolution.
> Drop into the cheez skills only when you need to inspect or rewrite a specific file.

---

## Resolution Chain

The three tools form a cascade — each handles what the previous couldn't:

1. **mergiraf** runs automatically as a git merge driver. It parses all three file versions
   (base, ours, theirs) into Tree-sitter ASTs and merges structurally. Independent additions
   (imports, functions, struct fields) merge cleanly even when text-based merge would conflict.
   Falls back to text merge if parsing fails — never makes things worse.

2. **rerere** ("reuse recorded resolution") activates after mergiraf. If you manually resolved
   the same conflict before, rerere replays that resolution automatically. Especially valuable
   during long rebases where the same conflict recurs across commits.

3. **kdiff3** is the manual fallback for conflicts neither tool could resolve. Launch with
   `git mergetool` — it opens a 3-way diff view for human decision-making.

---

## Protocol

### 1. Diagnose the Conflict State

Run the summary script first — it replaces the need for `grep -n '<<<<<<<'` and ad-hoc parsers:

```bash
python3 skills/merge-resolve/scripts/conflict-summary.py
```

Default output is terse and LLM-oriented: one metadata line per file, then minimally-framed
hunks. Each hunk shows up to 5 lines of ours/theirs and 3 of base, capped to keep token cost low.

Flags:
- `--json` — structured output for scripting
- `--verbose` — markdown-formatted human view (the previous default)
- `--context N` — context lines around each hunk (default 3)

If you need raw git info too:

```bash
git log --merge --oneline            # What commits are involved?
```

### 2. Attempt Structural Resolution

For files where mergiraf is configured but conflicts remain (meaning the structural merge
already ran and couldn't fully resolve), you can inspect what mergiraf produced vs text merge:

```bash
# Extract the 3-way inputs from git's stage slots
git show :1:<path> > /tmp/base    # Stage 1 = common ancestor
git show :2:<path> > /tmp/ours    # Stage 2 = current branch (HEAD)
git show :3:<path> > /tmp/theirs  # Stage 3 = incoming branch

# Preview what mergiraf would produce (writes to -o, doesn't touch working copy)
mergiraf merge /tmp/base /tmp/ours /tmp/theirs -o /tmp/merged -p <path>
# Check if clean (no conflict markers)
grep -c '<<<<<<' /tmp/merged  # 0 = clean
```

If the merged output has no conflict markers, mergiraf resolved it cleanly — the git
merge driver may have fallen back to text merge due to a parse error or size limit.
Apply the clean output:

```bash
cp /tmp/merged <path>
git add <path>
```

### 3. Batch Resolution

For repos with many conflicted files, use the batch script:

```bash
# Preview what can be resolved (no file changes; dry-run is the default)
python3 skills/merge-resolve/scripts/batch-resolve.py

# Apply all clean resolutions
python3 skills/merge-resolve/scripts/batch-resolve.py --apply

# Markdown-formatted output and mergiraf debug logs
python3 skills/merge-resolve/scripts/batch-resolve.py --verbose
```

The script extracts 3-way inputs for every conflicted file, runs `mergiraf merge`
on them, and reports which files resolved cleanly vs which need manual intervention.

### 4. Handle Remaining Conflicts

After structural resolution, for files that still have conflict markers:

**Check rerere first:**

```bash
git rerere status    # Files with recorded resolutions
git rerere diff      # Show what rerere would apply
```

If rerere has a resolution, it was already applied. If not, guide the user to manual resolution:

```bash
git mergetool        # Opens kdiff3 for each conflicted file
# Or for a specific file:
git mergetool <path>
```

From paulnsorensen/cheese-flow, MIT.

More from paulnsorensen/cheese-flow