GitLab Merge Conflicts
A merge conflict appears when two branches change the same lines of the same file and Git cannot decide which version to keep. Git pauses the merge and asks a human to choose. Conflicts feel scary at first, but each one follows the same pattern and has a clear fix.
Imagine two editors who both rewrite the same sentence in a shared document. The software cannot guess whose sentence wins. A person reads both versions and picks the final wording.
How a Conflict Happens
main branch: A ── B ── C (Sara changes line 10 to "Welcome")
\
feature branch: D ── E (Arjun changes line 10 to "Hello there")
Merge feature into main
Line 10 differs on both sides → CONFLICT
Different files or different lines merge without trouble. Trouble starts only when both sides touch the same spot.
Read the Conflict Markers
Git writes both versions into the file and wraps them in marker lines.
<<<<<<< HEAD <h1>Welcome</h1> ======= <h1>Hello there</h1> >>>>>>> feature/greeting
| Marker | Meaning |
|---|---|
| <<<<<<< HEAD | Start of your current branch version |
| ======= | Divider between the two versions |
| >>>>>>> feature/greeting | End of the incoming branch version |
Spot a Conflict in a Merge Request
GitLab shows a warning on the merge request page: "There are merge conflicts." The Merge button stays disabled until someone resolves them. Two buttons appear near the warning: Resolve conflicts and Resolve locally.
Resolve Conflicts in the GitLab Editor
The web editor suits small conflicts in text files.
- Open the merge request and select Resolve conflicts.
- Review each conflicting block. GitLab labels the two sides "Our changes" and "Their changes".
- Select Use ours or Use theirs for a simple choice.
- Select Edit inline to blend both versions by hand.
- Write a commit message and select Commit to source branch.
The pipeline restarts after the commit, and the merge button turns active when the checks pass.
Resolve Conflicts on Your Computer
Large or tricky conflicts deserve a proper editor and a local test run.
git switch feature/greeting git fetch origin git merge origin/main
Git reports the conflicting files. Open each file, remove the marker lines, and keep the final text you want.
<h1>Welcome, friend</h1>
Mark the file as resolved and finish the merge.
git add index.html git commit -m "Resolve greeting conflict with main" git push
Check Conflict Status
git status
The output lists "Unmerged paths" for each unresolved file. An empty list means every conflict is gone.
Use Rebase as an Alternative
Rebase replays your commits on top of the latest main branch. Conflicts appear one commit at a time.
git rebase origin/main # fix the file, then git add index.html git rebase --continue git push --force-with-lease
Rebase rewrites history. Use it only on branches that you alone own.
Cancel a Merge That Went Wrong
git merge --abort
This command restores the branch to the state before the merge began. Nothing is lost.
Prevent Conflicts Before They Start
- Pull the latest main branch into your feature branch every day.
- Keep branches small and short-lived.
- Split large files into smaller modules so people edit different files.
- Tell teammates which files you plan to change.
- Avoid mass formatting changes in shared files.
Conflict Checklist
| Check | Why It Matters |
|---|---|
| No marker lines remain in any file | Leftover markers break the code |
| The project builds and tests pass | A merged result can fail even when each side worked |
| The teammate who wrote the other change agrees | The author knows the intent behind the change |