resolving-merge-conflicts

name	resolving-merge-conflicts
description	Resolve in-progress git merge or rebase conflicts systematically. Use when you hit conflicts during merge, rebase, or cherry-pick.

Resolving Merge Conflicts

Resolve an in-progress git merge or rebase conflict with a disciplined, reproducible process.

Process

1. See the current state

Check what operation is in progress (git status), list conflicting files, and read the current conflict state. Understand the merge/rebase direction:

• Merge: ours = current branch, theirs = branch being merged in
• Rebase: ours = branch being rebased onto (upstream), theirs = your commits being replayed

2. Find the primary sources for each conflict

For every conflicting hunk, understand why each side made its change:

• Read the commit messages (git log <branch> --oneline)
• Check related PRs or issues referenced in commit messages
• Read surrounding context in both versions of the file
• Identify the intent behind each change — what problem was being solved?

3. Resolve each hunk

• Preserve both intents where possible (merge both changes)
• Where incompatible, pick the one matching the merge's stated goal
• Note any trade-offs in the resolution commit message
• Never invent new behavior — the resolution should combine existing intent, not introduce new logic
• Always resolve; never --abort without explicit user instruction

4. Run automated checks

After resolving all conflicts but BEFORE committing:

• Run the project's type checker
• Run affected tests
• Run the full test suite if practical
• Run the linter
• Fix anything the merge broke

5. Finish the merge/rebase

• Stage all resolved files (git add .)
• If merging: commit with a clear message explaining resolution decisions
• If rebasing: git rebase --continue and repeat 1-5 for remaining commits
• Push when complete

Safety rules

• Never force-push after resolving — always merge or rebase-continue
• Never git reset --hard during conflict resolution
• Commit after each resolution step during long rebases
• Verify the build passes before pushing

After resolution

• Run python .github/scripts/checklist.py . if available
• Verify all tests pass on the resolved branch
• If this is a PR, note any non-trivial conflict resolutions in the PR description