Handling Merge Conflicts: How to Resolve Git Conflicts Manually

Previously in this course, we covered the mechanics of merging branches. While Git is excellent at automating the integration of code, it isn't psychic; this lesson adds the essential skill of manual intervention when Git encounters a merge conflict.

A merge conflict occurs when two branches have made competing changes to the same line of a file, or when one person deletes a file that another person is still editing. Git halts the process and asks you to make the final decision on what the code should look like.

Identifying a Merge Conflict

When you run git merge, Git will attempt to combine your history. If it fails, you will see a message in your terminal notifying you of a merge conflict.

The terminal output will look something like this:

Bash
Auto-merging index.html
CONFLICT (content): Merge conflict in index.html
Automatic merge failed; fix conflicts and then commit the result.

At this point, your repository enters a "merging" state. If you run git status, Git will list the files that are currently unmerged under "Unmerged paths."

How to Resolve Conflicts Manually

To resolve the conflict, you must open the affected files in your code editor. Git has injected special "conflict markers" into the file to show you exactly what is clashing.

Open the file and look for these markers:

• <<<<<<< HEAD: Everything between this and the ======= is the code in your current branch.
• =======: The divider between your changes and the incoming changes.
• >>>>>>> branch-name: Everything between ======= and this is the code from the branch you are trying to merge in.

Worked Example

Imagine you have a file named hello.txt. Your main branch has the line "Hello World," but your feature branch changed it to "Hello Git."

If you try to merge feature into main, Git will stop and show this inside hello.txt:

TEXT
<<<<<<< HEAD
Hello World
=======
Hello Git
>>>>>>> feature

To resolve this, you simply delete the markers and the version you don't want. If you want "Hello Git," you edit the file until it looks like this:

TEXT
Hello Git

Once you have saved the file, you must tell Git the conflict is resolved:

1. git add hello.txt (This marks the file as resolved in the staging area).
2. git commit (This completes the merge commit).

Hands-on Exercise

1. Create a new branch called conflict-test.
2. Edit a file, commit it, and switch back to main.
3. Edit the same line of the same file in main and commit.
4. Attempt to git merge conflict-test.
5. Observe the conflict, open the file, remove the markers, and finalize the merge.

Common Pitfalls

• Leaving the markers behind: If you forget to delete <<<<<<<, =======, or >>>>>>>, your code will literally try to run those characters. Always double-check your files before staging.
• Panicking: A merge conflict is not a sign that you broke your repository; it is a standard part of the Git lifecycle. Take a deep breath and look at the markers.
• Ignoring the "merging" state: If you try to switch branches or perform other operations while a merge is in progress, Git will block you. Always finish the resolution by committing before moving on.

Frequently Asked Questions

Does a merge conflict mean I lost my work? No. Your work exists in both branches. You are simply choosing which version (or combination) to keep.

Can I undo a merge conflict attempt? Yes. If you get stuck or realize you shouldn't have started the merge, run git merge --abort to return the repository to its state before the command was run.

Should I use a tool to help? Yes, modern editors like VS Code have built-in conflict resolution interfaces that provide "Accept Current," "Accept Incoming," or "Accept Both" buttons, which are much safer than manual editing. For advanced workflows, you might eventually explore Git Rerere to automate repetitive resolutions.

Recap

We've learned that a merge conflict is simply a request for human intervention when Git's automation isn't enough. By identifying the conflict markers and manually editing the file to your desired final state, you maintain control over your codebase. Using git add and git commit finalizes the process, moving your project forward.

Up next: We will cover how to keep your workspace tidy by deleting branches after you've successfully merged them.