Resolving Merge Conflicts Calmly

A conflict is a question, not an error

When Git merges two lines of work, it combines changes automatically wherever it can. If you edited the top of a file and a colleague edited the bottom, Git has no trouble. A conflict arises only when both sides changed the same region in different ways, or when one side changed something that the other deleted. Git cannot know which version is right, so it stops and asks.

That is a reasonable request rather than a failure. Nothing has been lost; both versions still exist. Seeing a conflict message tells you the tool is protecting you from silently overwriting someone’s work.

Why conflicts happen

The common causes are straightforward:

• Two people edit the same lines of the same file on different branches.
• One person renames or moves a file while another edits it.
• One person deletes a file or function that another has modified.
• A branch stays open for a long time, so more has changed on the main line by the time it is merged.
• Automatic reformatting touches many lines, which then overlap with other people’s edits.

Conflicts are most likely in files that everyone touches, such as configuration, project files and lists that grow at the end. They are also much more common with long-lived branches, which is one reason many teams prefer short ones, as discussed under branching strategies.

What a conflict looks like

After a failed merge, git status lists the files with problems. Open one and you will see markers:

<<<<<<< HEAD
timeout = 30
=======
timeout = 60
>>>>>>> feature-longer-timeout

• The part between <<<<<<< and ======= is your current branch’s version.
• The part between ======= and >>>>>>> is the version from the branch being merged in.

Your job is to edit the region so that it contains what the file should say, then delete all three marker lines. The result might be one side, the other, or a blend of both. Sometimes the right answer is something neither person wrote.

A careful routine

1. Do not panic, and do not guess. Run git status and read what Git says. It lists the conflicted files and reminds you how to abort.
2. Know that you can back out. git merge --abort returns you to the state before the merge started, as long as you have no uncommitted work you would lose. Commit or stash your own changes before starting a merge so there is nothing at risk.
3. Understand both changes. Look at what each side was trying to achieve, not only the text. Check the commit messages and, if needed, ask the colleague. Good commit messages make this much easier.
4. Edit the file. Combine the intent of both changes, remove the markers, and make sure the file is valid. A file with leftover marker lines will not compile or parse.
5. Check the result. Read the final text, then run whatever builds or tests your project has. A merge can be textually clean and still be logically broken, for example if one side renamed a function that the other side still calls.
6. Mark the file as resolved. Stage it with git add <file>.
7. Finish the merge. When every conflicted file is staged, run git commit. Git supplies a default message, which you may keep or improve.

Many editors and dedicated merge tools show the two versions side by side, which some people find easier than raw markers. Use whatever you find clearest, but still read the final file yourself.

Choosing what to keep

Some conflicts have an obvious answer. Others do not, and these deserve a short conversation. A few questions help:

• Which change is newer, and does it replace the other or add to it?
• Do both changes need to survive, for example two new settings added in the same place?
• Is one change based on an assumption that the other has made false?
• Does a specification, requirement or decision record settle the question?

It is possible to take one entire side with commands such as git checkout --ours or --theirs, but use them with care. They discard the other side’s edits to that file, and it is easy to confuse which side is which, since the meaning flips during a rebase.

Reducing how often it happens

You cannot remove conflicts, but you can make them smaller and rarer:

• Keep branches short-lived, and merge often.
• Bring the latest changes from the main branch into your branch regularly.
• Commit small, focused changes rather than large rewrites.
• Avoid mass reformatting mixed in with real changes; do it in its own commit and tell the team.
• Talk before two people start major edits in the same file.
• Split very large files into smaller ones along natural boundaries.
• Use automated checks such as continuous integration so a broken merge is noticed quickly.

Binary files

Text conflicts can be edited by hand. Binary files, such as CAD models, cannot be merged line by line, so Git can only offer you one whole version or the other. Teams that work with such files usually agree who edits what at a time. This problem has its own article under binary file versioning.

After the merge

Test the merged result before sharing it. If you are working through pull requests, mention in the description that you resolved conflicts and where, so reviewers can look at those areas with extra care. If you merged by mistake, it is usually possible to undo it; the guidance on undoing git changes explains how to do it without disturbing shared history.

Conflicts become routine with practice. The pattern is always the same: read, understand, combine, check, record. Taking each step in order is what keeps work from being lost.