Search across all documentation pages
A step-by-step playbook for resolving merge or rebase conflicts safely. Run the steps in order -- skipping ahead is how clean working trees get clobbered. Every step has an exit ramp (--abort) so you can back out at any point until the final commit.
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥
--abort).Do all of these BEFORE you start the merge or rebase. Skipping prep is the #1 cause of "I lost my changes" disasters.
git statusIf anything is staged or modified, commit it, stash it, or discard it. Never start a merge with a dirty tree -- conflicts will mix your in-progress work with the merge resolution and you will not be able to tell them apart.
# Stash if you want to keep work-in-progress
git stash push -u -m "wip before merging main"git branch --show-currentYou merge INTO the current branch. If you are about to run git merge main, you should be on your feature branch -- not on main itself.
git fetch origin
git pull --ff-only origin <your-branch>A conflict resolved against a stale main is wasted work -- the real conflicts are still ahead of you. --ff-only refuses to silently merge if your branch has diverged.
| Situation | Use |
|---|---|
| Feature branch already pushed and shared | git merge main (preserves history) |
| Personal branch, not yet pushed (or you force-push your own branches) | git rebase main (linear history) |
| Pulling teammate's changes into your branch | git pull --rebase if you have local commits, plain git pull otherwise |
If you are unsure, use merge. It is harder to lose work with a merge.
git rev-parse HEAD
# write this SHA somewhere -- a sticky note, a scratch file, anywhereIf everything goes wrong, git reset --hard <that-sha> puts you back exactly where you started. git reflog works too, but a written-down SHA is faster under stress.
# Merge approach
git merge main
# OR rebase approach
git rebase mainIf there are no conflicts, you are done -- skip to step 19.
Git prints exactly which files conflict and what kind of conflict each is (content vs. add/add vs. delete/modify). Read this list. Do not start opening files until you know how many conflicts you have and where they are.
git status
# Look for "Unmerged paths" -- that is your work list# Get a clean list of just the conflict files
git diff --name-only --diff-filter=UResolve the simplest conflicts first to shrink the surface area. Save the gnarly ones for last when you have momentum.
Conflict markers look like this:
<<<<<<< HEAD
your version (the branch you are merging INTO)
=======
their version (the branch you are merging FROM)
>>>>>>> main
During a rebase, the labels are inverted: HEAD is the base branch you are rebasing onto, and the >>>>>>> side is your incoming commit. This catches everyone off guard at least once.
# Show the full diff with both sides
git diff
# Or for one specific file
git diff -- path/to/file.ts
# See who wrote each side and why
git log --merge --oneline -- path/to/file.ts
git log -p HEAD..MERGE_HEAD -- path/to/file.tsKnowing why each side made a change -- not just what it changed -- is the difference between a real resolution and a guess that compiles.
Pick one before editing:
| Strategy | When |
|---|---|
| Keep ours | Their change is irrelevant to your branch |
| Keep theirs | Your change is now redundant (e.g., they did the same thing) |
| Combine both | Both changes are needed and do not collide semantically |
| Rewrite | Both sides are wrong now, given the other side exists |
# Take one side wholesale
git checkout --ours path/to/file.ts
git checkout --theirs path/to/file.tsDelete every <<<<<<<, =======, and >>>>>>> line. The file should compile and read naturally as if it had never been conflicted.
A common mistake is leaving stray markers in untouched parts of the file. Search for them:
grep -rn '<<<<<<<\|=======\|>>>>>>>' .For each resolved file, run whatever check is fast and local:
# Type check
npx tsc --noEmit
# Format
npx prettier --write path/to/file.ts
# Lint
npx eslint path/to/file.tsIf a Server Component and a Client Component both import each other after merging, fix the boundary now -- not after staging.
git add path/to/file.tsFor a rebase, git add does NOT auto-progress -- you still need step 16. For a merge, staging all conflicts puts you ready to commit.
Repeat steps 8-13 for every file in git status.
git statusEvery file under "Unmerged paths" must be gone. If git diff --name-only --diff-filter=U returns nothing, you are clean.
npm run build
npm run typecheck
npm testA merge that compiles individual files but breaks the build is the most common bad-merge outcome. Catch it now, not in CI.
git rebase --continueIf more conflicts appear, you are now resolving the NEXT commit's conflicts. Loop back to step 8 for each.
# For a merge: what will the merge commit contain?
git diff HEAD
# For a rebase: how does my branch differ from before?
git range-diff <starting-sha>..ORIG_HEAD <starting-sha>..HEADIf the diff has files you did not touch or expect, something went wrong. Stop and investigate before committing.
At ANY point before the final commit, you can return to step 1's state:
git merge --abort
git rebase --abortIf you already committed and need to undo:
git reset --hard <starting-sha-from-step-5>There is no shame in aborting. A clean re-attempt is faster than untangling a half-broken merge.
# Merge: commit the merge with the auto-generated message (or write your own)
git commit
# Rebase: should already be done after the final --continueFor a merge commit, write a body that explains what the conflicts were and how you resolved them. Future-you will thank you during a bisect.
# Merge: regular push is fine
git push
# Rebase: force-push, but ONLY to your own branches and ONLY with --force-with-lease
git push --force-with-lease--force-with-lease refuses the push if someone else committed to the remote branch since you last fetched -- it is the difference between rewriting your own history and overwriting a teammate's commit. Never --force (without -with-lease) on a shared branch.
| You are at... | Get out with... |
|---|---|
| Mid-merge, conflicts unresolved | git merge --abort |
| Mid-rebase, conflicts unresolved | git rebase --abort |
| Already committed the merge, regret it | git reset --hard ORIG_HEAD |
| Already pushed a bad merge | git revert -m 1 <merge-sha> (do NOT force-push to undo) |
| Lost track entirely | git reflog -- find the SHA from before, then git reset --hard <sha> |
main first (step 3). Resolving against last week's main means doing the work twice.git log to confirm which commit is which.<<<<<<< before staging.--force-with-lease, and never on main.Reviewed by Chris St. John·Last updated Jul 7, 2026
🤖 Read the SystemsArchitect.io Blog for over 100+ cloud architecture articles 🔥