Resolve merge conflicts on GitHub: web editor, CLI and AI
Zihua Li · · 10 min read
A merge conflict on GitHub looks alarming the first time: a gray “This branch has conflicts that must be resolved” box, and a merge button that won’t work. Underneath, it’s Git asking a person to decide between two edits to the same lines, and most of the time you can resolve conflicts on GitHub, or in your own clone, in a few minutes.
To resolve conflicts on GitHub, open the pull request and select Resolve conflicts, pick or combine the lines between the conflict markers, select Mark as resolved for each file, then Commit merge. GitHub’s web editor handles simple competing line changes; anything else, such as a file one branch deleted, is resolved in a local clone with git merge or git rebase and pushed back to the pull request branch.
Why merge conflicts happen
Git merges most changes without asking anyone. It compares both branches against the commit where they split, takes whatever changed on one side only, and moves on. A git merge conflict happens when both sides changed the same lines since that split, or when one side edited a file the other deleted. Git won’t guess which version wins, so it stops and writes both into the file.
On GitHub you see this on the pull request: the merge box says the branch has conflicts, and the Merge pull request button stays disabled until they’re resolved. Nothing is broken yet; nothing has merged. The conflict exists only in the merge GitHub would like to do.
The usual cause is time. A branch that sat open for a week while main moved on touches the same config file, the same import list or the same lockfile someone else just changed. Long-lived branches and files everyone edits are where conflicts come from, which is also where the fixes at the end of this guide aim.
How to read merge conflict markers
Every conflict, whether you see it in the GitHub editor or in your own, is written into the file with the same three merge conflict markers:
<<<<<<< HEAD
const timeout = 30_000;
=======
const timeout = Number(process.env.API_TIMEOUT ?? 10_000);
>>>>>>> main<<<<<<< HEADstarts the version from the branch you are on.=======separates it from the other version.>>>>>>> mainends the other branch’s version, named after it.
The markers show the two endings but not the starting point, and the starting point is what tells you who changed what. Here, was the timeout raised to 30 seconds on your branch, or lowered on main? Turn on the zdiff3 conflict style and Git adds the common ancestor between ||||||| and =======:
<<<<<<< HEAD
const timeout = 30_000;
||||||| base
const timeout = 10_000;
=======
const timeout = Number(process.env.API_TIMEOUT ?? 10_000);
>>>>>>> mainNow the story is clear. The original was 10 seconds; your branch raised it to 30; main made it configurable. The right answer keeps both intentions, which neither side alone does:
const timeout = Number(process.env.API_TIMEOUT ?? 30_000);That is the whole skill. Read what each side was trying to do, write the code that does both, and delete every marker line. A marker left in a file is a syntax error at best and a string in production at worst.
How to resolve conflicts in GitHub’s web editor
For a small conflict, GitHub’s own editor is the fastest route, and it works from any browser:
- Open the pull request and select Resolve conflicts in the merge box.
- The first conflicting file opens with its markers. Edit the text into the version you want and remove the marker lines.
- Select Mark as resolved, then pick the next file under conflicting files.
- When every file is resolved, select Commit merge.
Know what that last button does. GitHub merges the entire base branch into the head branch, so your pull request gains a merge commit that brings in everything new on main, not only the lines you touched. If the head branch is protected, GitHub asks you to create a new branch for the pull request instead.
The editor is limited to simple competing line changes. When Resolve conflicts is grayed out, the conflict is one GitHub leaves to a local clone, such as a file one branch deleted while the other edited it. The editor also can’t run your code, so a resolution that looks right but doesn’t compile shows up only when CI runs on the merge commit.
How to resolve merge conflicts from the command line
Locally you have your editor, your tests and the full history, which is why anything bigger than a one-line clash belongs here. First decide how to bring the base branch in.
Merge the base branch (the default choice)
This does on your machine what GitHub’s button does: one merge commit on your branch, nothing rewritten. It is the right choice for a branch other people have pulled or reviewed.
git fetch origin
git switch fix-api-timeout
git merge origin/main
# CONFLICT (content): Merge conflict in src/api/client.ts
git status # lists the files under "both modified"
# edit each file, remove the markers, run the tests
git add src/api/client.ts
git merge --continue # or: git commit
git pushRebase onto the base branch
Rebasing replays your commits on top of the latest main, so the history stays linear. The cost: Git stops at each of your commits that conflicts, so a branch with ten commits touching one file can make you resolve the same region ten times, and the result has to be force-pushed.
git fetch origin
git switch fix-api-timeout
git rebase origin/main
# CONFLICT (content): Merge conflict in src/api/client.ts
# edit the file, remove the markers
git add src/api/client.ts
git rebase --continue # repeat for each commit that conflicts
git push --force-with-leaseUse --force-with-lease, never plain --force. It refuses to overwrite the remote branch if someone pushed to it since you last fetched, which turns a silently lost commit into an error message.
Commands for the awkward cases
git checkout --ours -- package-lock.json # keep your side for this file
git checkout --theirs -- package-lock.json # keep the other side
git rm docs/old-setup.md # one side deleted it, and so do you
git merge --abort # give up and return to before the merge
git rebase --abort # same, for a rebaseTwo warnings. First, during a rebase ours and theirs swap places: “ours” is the branch you are rebasing onto and “theirs” is your own commit. Second, for lockfiles, taking one side and regenerating (for example, accepting main’s package-lock.json and running npm install) is more reliable than merging lines of generated JSON by hand.
When the conflict is confusing, ask Git for context instead of staring at markers. git log --merge -p src/api/client.ts shows the commits on each side that touched the file, and git show :1:src/api/client.ts prints the common ancestor.
GitHub Desktop and VS Code
GitHub Desktop warns you about conflicts before you merge another branch into yours, and won’t complete the merge until every conflict is resolved. Resolve them in your editor, finish the merge, and select Push origin to update the pull request.
VS Code shows each conflict inline with Accept Current Change, Accept Incoming Change, Accept Both Changes and Compare Changes above it. For anything more than a line or two, select Resolve in Merge Editor: a three-way view with the incoming side, the current side and the result you are building. Accept Both only stacks the two versions one after the other, so read the result before saving; with the timeout example it would produce two declarations of the same constant.
After resolving: push and re-run checks
A resolved conflict is new code that nobody reviewed. Before pushing, build it and run the tests that cover the files you touched. After pushing, let CI finish on the new commit; a passing run on the old head says nothing about the merge.
Then make the change visible. If the resolution needed real decisions, like the timeout example, say so in a pull request comment so the reviewer looks at those lines and not only at the original diff. If your repository dismisses stale approvals on new commits, expect to ask for another approval.
Resolving a merge conflict means deciding what the code should do when two changes overlap, not choosing a side. Read both versions against their common ancestor, write code that keeps both intentions, delete every marker, and let the tests run on the merge commit before anyone merges the pull request.
How to avoid merge conflicts
You can’t prevent every conflict, but you can keep them small and rare.
- Keep pull requests small and short-lived. A branch merged the same day rarely conflicts. One open for two weeks almost always does.
- Update your branch often. Merge
mainin daily on a long branch, or use the Update branch button while there are no conflicts yet. Five small conflicts are easier than one big one. - Separate formatting from logic. A pull request that reformats a whole file conflicts with everyone. Land it on its own, quickly, and run the formatter in CI so it never happens by accident.
- Turn on rerere. With
rerere.enabled, Git records how you resolved a conflict and reapplies it when the same conflict appears again, which saves real time when you rebase a branch more than once.
git config --global merge.conflictStyle zdiff3
git config --global rerere.enabled trueThe merge.conflictStyle zdiff3 line from earlier belongs in the same global config; it costs nothing and makes every future conflict easier to read.
AI merge conflict resolution
Most conflicts are mechanical once you know what each side meant, and reading intent from code is something current coding agents do well. AI merge conflict resolution now shows up in several places: VS Code has an experimental Resolve Conflicts with AI button that compares both sides against the merge base and proposes edits, and GitHub offers Fix with Copilot in the merge box when Copilot’s cloud agent is enabled for the repository.
HeyDeer does it from the pull request conversation. Comment on a pull request with something like @heydeer resolve the merge conflicts, and HeyDeer merges the base branch into the pull request’s branch, resolves the conflicts and pushes the result as a regular commit, so the branch history stays as it was. It acts with the access of the person who asked, so branch protection applies as usual, and on a pull request from a fork the fork’s author pushes the resolution, since only they can push to that branch.
On a pull request that should simply get to green, Autopilot folds conflicts into the rest of the work: started with @heydeer autopilot, it fixes review findings, failing checks and merge conflicts on the pull request’s own branch, merging the base branch rather than rebasing, and reviews each change until the pull request is ready.
HeyDeer resolves merge conflicts when you ask it to: comment @heydeer on the pull request, and it merges the base branch into the pull request’s branch, resolves the conflicts and pushes a regular commit, without rebasing or force-pushing. Autopilot does the same while it fixes findings and failing checks to get the pull request ready to merge.
Whoever resolves the conflict, a person or an agent, the same rule from above holds: the resolution is new code, so it gets read and tested before it merges. If your team reviews pull requests on GitHub, the GitHub code review guide covers how to fit that step in, and the GitHub auto-merge guide covers merging automatically once the checks pass.
Sources
- GitHub Docs: About merge conflicts
- GitHub Docs: Resolving a merge conflict on GitHub
- GitHub Docs: Resolving a merge conflict using the command line
- GitHub Docs: Keeping your pull request in sync with the base branch
- GitHub Docs: Syncing your branch in GitHub Desktop
- Git documentation: git merge
- Git documentation: git checkout
- Git documentation: git rerere
- Visual Studio Code: Resolve merge conflicts
Frequently asked questions
What are merge conflicts in GitHub?
Merge conflicts in GitHub happen when a pull request’s branch and its base branch change the same lines of a file, or when one branch edits a file the other deleted. Git can’t choose between the two versions safely, so GitHub disables the merge button until someone resolves the conflict.
Why is the Resolve conflicts button grayed out on GitHub?
The Resolve conflicts button on GitHub is grayed out when the conflict is more than a simple competing line change, for example a file that one branch deleted and the other edited. Those conflicts have to be resolved in a local clone, or another Git client, and pushed back to the pull request branch.
How do I merge after resolving conflicts?
After resolving conflicts, commit the resolution (Commit merge on GitHub, or git add followed by git merge --continue locally) and push it to the pull request branch. Wait for the checks to run again on the new commit, then use Merge pull request as usual.
Should I merge or rebase to fix a merge conflict?
To fix a merge conflict on a shared pull request branch, merging the base branch is the safer choice: it adds one merge commit and never rewrites history that others may have pulled. Rebasing gives a linear history but replays each commit, can make you resolve the same conflict several times, and requires a force push.
What do ours and theirs mean in a Git conflict?
In a Git merge conflict, ours is the branch you are on and theirs is the branch you are merging in. During a rebase the roles swap: ours is the branch you are rebasing onto, such as main, and theirs is your own commit being replayed.
How do I resolve merge conflicts in GitHub Desktop?
GitHub Desktop warns about merge conflicts before you merge another branch into yours, and the merge can’t finish until they are resolved. Resolve each conflicting file in your editor, complete the merge, then select Push origin to update the pull request on GitHub.
Can AI resolve merge conflicts?
AI merge conflict resolution works well for conflicts where the intent of both sides can be read from the code, such as two edits to the same function or config. Tools such as VS Code’s Resolve Conflicts with AI, Copilot on GitHub and HeyDeer’s @heydeer mentions propose or push a resolution; review the result and let the tests run before merging.
How do I stop the same conflict from coming back?
To stop the same merge conflict coming back, turn on git rerere with git config --global rerere.enabled true. Git records how you resolved each conflict and reapplies that resolution the next time the same conflict appears during a merge or rebase.



