TL;DR Quick Fix
Hit a merge conflict? The quickest way to sort it out is by manually fixing the conflicting parts in your files. Here's a rapid guide:
- **Check status:**
git status
This command shows you which files are in a conflicted state. You'll find them listed under "Unmerged paths."
- **Open and edit:** Open each conflicted file in your favorite text editor. Git marks conflicts with special markers, like these:
<<<<<<< HEAD
// Code from your current branch (HEAD)
=======
// Code from the branch you are merging
>>>>>>> branch-name
Decide which changes to keep, or combine them as needed. Then, crucially, remove the <<<<<<<, =======, and >>>>>>> markers.
- **Mark as resolved:** After editing a file and clearing all conflict markers, tell Git that you've fixed the conflict for that file:
git add file.txt
Repeat this step for every conflicted file.
- **Complete the merge:** Once all conflicts are resolved and staged, finalize the merge with a commit:
git commit -m "Resolve merge conflict in file.txt"
Git often pre-populates a merge commit message for you. Feel free to accept or modify it.
Detailed Root Cause: Why Merge Conflicts Happen
A CONFLICT (content): Merge conflict in file.txt error pops up when Git can't automatically figure out how to combine changes made to the same lines in the same file across two different branches you're trying to merge.
Let's break down why this occurs:
- **Divergent Histories:** Imagine you and a teammate (or you working on a separate feature) both start from the same point (a common commit). You both make different changes, and when you try to bring those changes together, your project's histories have diverged.
- **Same Line, Different Changes:** The most common culprit is when both branches modify the *exact same lines* within a file. It also happens if one branch deletes lines that the other branch modified. In these cases, Git needs a human to decide which change should win. Git is usually smart enough to merge changes to different parts of a file automatically, but when it's ambiguous, it flags a conflict.
- **The Three-Way Merge:** Git uses a "three-way merge" strategy. It compares the common ancestor of the two branches with the latest version of both branches. If the same section of a file was altered differently in both branches since that common ancestor, a conflict arises. This is Git asking for your input because it can't make the call.
When Git spots a conflict, it pauses the merge process. It leaves the problematic files in a special state, clearly marking the conflicting sections with those familiar <<<<<<<, =======, and >>>>>>> markers. This is your cue to step in and manually resolve these ambiguities.
Fixing Conflicts: Your Options
Resolving Git merge conflicts can be tackled in a couple of main ways: manual editing or using a dedicated merge tool.
Approach 1: Manual Resolution in a Text Editor (The Hands-On Way)
This method is often the quickest and most direct, especially for smaller, straightforward conflicts.
- **Identify Conflicted Files:**
After starting a merge (e.g., git merge feature-branch) and seeing the conflict message, run git status. This is your go-to command for understanding the situation.
git status
You'll see output similar to this:
On branch main
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abandon merge)
Unmerged paths:
(use "git add <file>..." to mark resolution)
both modified: file.txt
This message clearly tells you that file.txt is currently experiencing a conflict.
- **Edit the Conflicted File:**
Now, open file.txt in your preferred text editor. Inside, you'll encounter conflict markers that look like this example:
// Some shared code that hasn't changed
<<<<<<< HEAD
// This is the content from your current branch (HEAD).
// Perhaps you've added a new function or fixed a bug here.
=======
// This is the content from the branch you're merging (e.g., 'feature-branch').
// A colleague might have implemented different logic here.
>>>>>>> feature-branch
// More shared code that remains unchanged
`<<<<<<< HEAD`: This marks the beginning of the changes from your current active branch.
- `=======`: This line acts as a divider, separating your changes from the incoming changes.
- `>>>>>>> branch-name`: This indicates the end of the changes coming from the branch you're merging.
Your job is to carefully review these sections. You need to decide:
- Which version should be kept?
- Should you combine parts from both versions?
- Is there a completely new, better way to integrate both sets of changes?
Let's consider an Example Resolution:
Suppose file.txt initially contained:
function greet() {
return "Hello";
}
And your HEAD branch modified it to:
function greet() {
return "Hello, World!";
}
Meanwhile, the feature-branch you're merging changed it to:
function greet() {
return "Hi!";
}
The conflicted file would then appear as:
function greet() {
<<<<<<< HEAD
return "Hello, World!";
=======
return "Hi!";
>>>>>>> feature-branch
}
You might resolve this by choosing to keep "Hello, World!", or by creating a new, combined message. For instance, to keep "Hello, World!":
function greet() {
return "Hello, World!";
}
Or, if the logic allows for a combined approach:
function greet() {
// Here, you'd decide which greeting makes sense, or combine for specific application logic
return "Greetings, fellow developer!";
}
Absolutely critical: you must remove all <<<<<<<, =======, and >>>>>>> lines. Git won't let you commit until these markers are gone.
- **Stage the Resolved File:**
Once you've manually edited file.txt and removed all conflict markers, save your changes. Then, tell Git that this file's conflict has been resolved by adding it to the staging area:
git add file.txt
Run git status again. You should now see file.txt listed under "Changes to be committed" instead of "Unmerged paths." This confirms it's ready for the next step.
- **Commit the Merge:**
With all conflicted files resolved and staged, complete the merge process by creating a merge commit:
git commit
This command will launch your default text editor, pre-filled with a merge commit message. This message typically explains which branches were merged and notes that conflicts were resolved. You can customize this message if you wish, then save and close the editor to finalize the commit.
Approach 2: Using a Visual Merge Tool (The Graphical Helper)
When conflicts get intricate, or if you simply prefer a graphical interface, Git offers robust support for external merge tools.
- **Configure a Merge Tool (if you haven't already):**
You can set up Git to use popular tools like Beyond Compare, KDiff3, Meld, or even your IDE's built-in merge capabilities (like VS Code). For example, to integrate VS Code as your preferred merge tool:
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait --merge $REMOTE $LOCAL $BASE $MERGED'
git config --global mergetool.vscode.trustExitCode false
Note: The exact commands might vary slightly based on your chosen tool and operating system. Always refer to your tool's documentation for precise setup instructions.
- **Launch the Merge Tool:**
Once your tool is configured and Git detects a conflict, simply run:
git mergetool
Git will then go through each conflicted file, launching your configured merge tool one by one. Typically, the tool will present you with three or four panels: the common ancestor, your changes, and the incoming changes. Some tools also show the final merged output. This visual comparison makes it much easier to select the parts you want to keep or combine.
- **Save and Exit the Tool:**
After you've visually resolved the conflict within the merge tool, save your changes and close the tool. Git will automatically stage the file, marking it as resolved in the process.
- **Commit the Merge:**
Just as with manual resolution, once all conflicts are resolved (either manually or via the tool), finalize the merge by running git commit.
Approach 3: Aborting a Merge (When Things Go Sideways)
Sometimes, conflicts might seem overwhelming, or you might realize you jumped into a merge too soon. In such cases, you can safely abort the merge operation, returning your repository to its state before you even started the merge.
- **Abort the Merge:**
git merge --abort
This powerful command stops the merge process dead in its tracks. It resets your working directory and Git index to precisely how they were before you called git merge. Important: Be aware that any uncommitted changes in your working directory might be lost if they conflict with the state Git reverts to. It's always a good practice to commit or stash your work before attempting a merge.
Verification Steps: Confirming Your Merge
After successfully resolving a merge conflict and creating that crucial merge commit, taking a few moments to verify everything is in order is smart practice. This ensures your hard work hasn't introduced new problems.
- **Check Git Status:**
Your very first step should always be to confirm the status of your repository:
git status
A reassuring output like On branch main nothing to commit, working tree clean means your merge was successful, and there are no lingering changes or unresolved conflicts.
- **Review Commit History:**
Next, take a look at your commit history. This ensures the merge commit was created correctly and that the history accurately reflects how the changes were integrated:
git log --oneline --graph --all
This command provides a concise, graphical view of your commit history. It's perfect for quickly visualizing the merge commit and seeing how branches were woven together.
- **Test Your Application/Codebase:**
The ultimate test is to run your code! Execute any automated tests, kick off your build processes, or even manually test the functionality that was affected by the merged changes. This critical step verifies that your conflict resolution didn't accidentally introduce new bugs or break existing features. Don't skip it!
Further Reading & Resources
- [Git Branching - Basic Branching and Merging](https://git-scm.com/book/en/v2/Git-Branching-Basic-Branching-and-Merging)
- [Git Tools - Advanced Merging](https://git-scm.com/book/en/v2/Git-Tools-Advanced-Merging)
- Consult your chosen merge tool's documentation for specific usage instructions and advanced features.