Resolve Merge Conflicts

Resolve merge conflicts (non-destructively)

Resolve git conflicts so that both sides' intent survives, verify the result, and stop and ask a human the moment a safe resolution isn't obvious. The git mechanics are the easy part; the danger is silently dropping someone's work — a blind "take theirs," a clean-looking textual merge that's logically broken, or a force-push over a teammate's commits.

Command recipes live in [reference/playbook.md](./reference/playbook.md) (load on demand). This body is the decision rules.

First: rebase or merge?

You update a feature/PR branch against its base one of two ways. Either is fine — pick by context, not dogma:

| | git rebase origin/main | git merge origin/main | | --- | --- | --- | | History | linear (replays your commits) | adds a merge commit | | Conflicts | may re-hit the same conflict per replayed commit (turn on rerere) | resolve once | | Push after | --force-with-lease (rewrites your branch) | normal push | | Best for | your own unshared PR branch | a branch others also commit to |

In a squash-merge repo (see [git-trunk-branch-and-pr-automation](../git-trunk-branch-and-pr-automation/SKILL.md)) the feature branch's history is flattened at merge anyway, so a merge commit on the branch is harmless — when a rebase keeps re-conflicting, merge instead and resolve once. Never rebase a branch other people are actively committing to.

The non-negotiable safety rules

1. Never blind-resolve a whole side. -X ours / -X theirs (strategy options)

and git checkout --ours/--theirs take one side wholesale and throw the other away silently. They're only correct for files you will regenerate (e.g. lockfiles) or a file that genuinely should be one side entirely — never as a "make the markers go away" shortcut.

1. Resolve hunk-by-hunk, preserving both intents. A conflict means both sides

changed the same region. The correct result is usually neither side verbatim but a combination. Turn on diff3/zdiff3 so you can see the common ancestor and reason about what each side changed from (recipe in the playbook).

1. Know the rebase ours/theirs inversion. During git merge, ours=your branch,

theirs=incoming. During git rebase, it's flipped: ours=the branch you're replaying onto (e.g. main), theirs=your commits. Acting on the wrong one discards exactly the work you meant to keep.

1. Keep the escape hatch ready. git merge --abort / git rebase --abort /

git cherry-pick --abort returns you to a clean pre-conflict state. If unsure, abort and reassess rather than push a half-resolved tree. git reflog + ORIG_HEAD recover from a bad finish.

1. Force-push only --force-with-lease, only your own PR branch. Plain

--force clobbers teammate commits pushed since your last fetch; --with-lease refuses if the remote moved.

1. Never commit conflict markers. Run git diff --check and

git diff --cached --check (staged markers won't show in the unstaged diff after git add), plus a grep for `,

• GitHub PR mergeability fields (mergeable, mergeStateStatus = DIRTY on

conflict):

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stealth-engine
• Source: stealth-engine/skills
• License: MIT

Install and usage instructions live in the source repository linked above.