Quick answer
A Git merge conflict occurs when two branches modify the same part of a file. It is resolved by opening the files with conflict markers, manually choosing or combining changes, saving, running `git add`, and finishing with `git commit` or `git merge --continue`. If you get stuck, `git merge --abort` returns everything to the state before the merge.
How to recognize the problem
- Message `CONFLICT (content): Merge conflict in ...` in the terminal
- Files contain markers `<<<<<<<`, `=======`, `>>>>>>>`
- `git status` shows files under "Unmerged paths"
- Merge has started but not finished, `git log` does not show a new commit
- Editor or IDE shows red markers on lines with conflicts
Most common causes
Changes to the same part of a file in two branches
Two branches changed the same lines of code or the same block of text, so Git cannot automatically decide which version is correct.
Deleting or moving a file in one branch
If a file was deleted in one branch and modified in another, Git reports a modify/delete conflict.
Simultaneous work on the same branch
Two developers changed the same file without pulling the latest changes, so the merge later detects an overlap.
Custom merge settings
`.gitattributes` or custom merge drivers can affect how Git treats changes and when it reports a conflict.
Step-by-step fix
- 1
Check the repository state
Run
git status. Files with conflicts will be listed under "Unmerged paths". Note them down or open a terminal in the project root. Do not abort the merge until you decide what you want. - 2
Open the file with the conflict
Open each file from the list in your editor. Look for markers
<<<<<<< HEAD,=======, and>>>>>>> branch-name. In the default style, the part between<<<<<<<and=======is your current branch, and the part between=======and>>>>>>>comes from the branch being merged. If you use thediff3style, there is also a common ancestor section between|||||||and=======. - 3
Manually combine the changes
Delete all conflict markers and leave only the desired code. You can keep one side, the other, or combine both. Pay attention to brackets, commas, and indentation. If unsure, open the file history (
git log -- file) to see who changed what. - 4
Use an editor or IDE for review
VS Code offers options "Accept Current Change", "Accept Incoming Change", and "Accept Both Changes"; other editors have similar options. It is faster, but always review the result. Do not blindly accept both sides if the code logic overlaps.
- 5
Save and mark as resolved
When you finish the file, save it and run
git add filename. Repeat for all files from the list.git statusshould now show "All conflicts fixed but you are still merging". - 6
Finish the merge
Run
git commit(without-mif you want to edit the message) orgit merge --continue. This creates a merge commit. Checkgit log --oneline -3to see that the merge was recorded. - 7
Test before pushing
Run the build and tests (
npm test,mvn test, or whatever the project uses). A conflict can hide an error that only appears at runtime. Only when tests pass, dogit push. - 8
If you want to abort
The command
git merge --abortreturns the working directory to the state before the merge started. Use it if you decide it is better to first pull changes or consult a colleague. Do not usegit reset --hardif you have unsaved changes.
When the conflict becomes too large
If a file has dozens of conflict blocks or you do not understand the code, do not randomly choose sides. If you want to save the state before the merge, create a backup branch before starting the merge (git branch my-backup); it does not save unsaved changes in the working directory. If you are starting the merge anew, on the target branch you can use git merge --no-commit to review changes before committing. For large conflicts, it is useful to enable git config merge.conflictstyle diff3 which also shows the common ancestor, making it easier to understand. If the conflict involves binary files, Git cannot merge them; then you must manually choose one version (git checkout --ours file or --theirs), then run git add file.
How to prevent it
- Frequently pull changes from the main branch (`git pull --rebase`) before starting larger work.
- Keep changes small and focused on one task; commit more often.
- Agree in the team who changes which files and parts of code.
- Enable `git config merge.conflictstyle diff3` to better understand conflicts.
When to call a professional
If the conflict involves dozens of files, binary files, or you do not understand the code well enough to safely combine changes, call IT support or a more experienced colleague to resolve the conflict together and preserve history.
Software and product development · Custom apps, SaaS and an MVP in 4 to 8 weeksFAQ
What do the markers `<<<<<<<`, `=======`, and `>>>>>>>` mean?
`<<<<<<< HEAD` marks the beginning of your current branch, `=======` separates the two versions, and `>>>>>>> branch-name` marks the end of the part from the branch being merged. All conflict markers must be deleted before you mark the file as resolved.
Can I undo the merge if I have already run `git add`?
Yes, `git merge --abort` works as long as you have not completed the merge commit. If you have already made the merge commit and have not pushed it, you can undo it with `git reset --hard HEAD~1`, but first create a backup branch or copy of the repository. If the commit has already been pushed, use `git revert -m 1 <hash>`.
How do I resolve a conflict in a binary file?
Git cannot automatically merge binary files. Decide which version is correct and run `git checkout --ours file` (your branch) or `git checkout --theirs file` (the other branch), then `git add file`.