Git shows "unmerged paths" when a merge, rebase, or cherry-pick has conflicts that you haven't resolved. The repository is in a paused state waiting for your decision.
The Error
After attempting a merge:
git merge feature-branchYou see:
Auto-merging src/config.js
CONFLICT (content): Merge conflict in src/config.js
Automatic merge failed; fix conflicts and then commit the result.Running git status shows:
``` On branch main You have unmerged paths. (fix conflicts and run "git commit") (use "git merge --abort" to abort the merge)
Unmerged paths: (use "git add <file>..." to mark resolution) both modified: src/config.js ```
Why This Happens
Git enters the "unmerged paths" state when:
- Two branches modify the same lines in the same file
- A file is deleted in one branch but modified in another
- Binary files conflict and cannot be auto-merged
- File renamed in one branch but modified in another
The merge is incomplete until you resolve all conflicts and commit, or abort entirely.
Diagnosis Steps
Check current state:
``bash
git status
Shows which files are unmerged and the operation type (merge/rebase/cherry-pick).
List all conflicted files:
``bash
git diff --name-only --diff-filter=U
Check for remaining conflict markers:
``bash
git diff --check
Shows lines with unresolved conflict markers (<<<<<<<, =======, >>>>>>>).
See the merge state:
``bash
cat .git/MERGE_HEAD
Shows the commit being merged (if merge operation).
Solution 1: Resolve Conflicts Manually
Open each conflicted file:
git diff --name-only --diff-filter=UEdit each file to remove conflict markers:
nano src/config.jsYou'll see conflict markers:
``
<<<<<<< HEAD
const apiUrl = "https://api.example.com";
=======
const apiUrl = "https://api.staging.com";
>>>>>>> feature-branch
Resolve by choosing or combining:
``javascript
const apiUrl = "https://api.example.com"; // Production
Remove all conflict markers, then stage:
``bash
git add src/config.js
Complete the merge:
``bash
git commit
Solution 2: Keep One Version Entirely
For files where you want your branch's version:
git checkout --ours src/config.js
git add src/config.jsFor files where you want the incoming branch's version:
git checkout --theirs src/config.js
git add src/config.jsImportant: During a merge, --ours is HEAD (your current branch), --theirs is the branch you're merging. During a rebase, this is reversed.
Solution 3: Abort the Operation
If you want to cancel entirely:
Abort a merge:
``bash
git merge --abort
Abort a rebase:
``bash
git rebase --abort
Abort a cherry-pick:
``bash
git cherry-pick --abort
This returns the repository to the state before the operation started.
Solution 4: Resolve All Conflicts with Strategy
Use automatic resolution strategy:
```bash # Prefer your changes for all conflicts git checkout --ours . git add .
# Or prefer their changes for all conflicts git checkout --theirs . git add . ```
Then commit:
``bash
git commit
Solution 5: Use Merge Tool
Launch visual merge tool:
git mergetoolConfigure VS Code as merge tool:
``bash
git config --global merge.tool vscode
git config --global mergetool.vscode.cmd 'code --wait $MERGED'
Solution 6: Handle Deleted/Modified Conflicts
When a file was deleted in one branch but modified in another:
CONFLICT (modify/delete): src/old-module.js deleted in feature-branch and modified in HEADKeep the file (your modification):
``bash
git add src/old-module.js
Accept the deletion:
``bash
git rm src/old-module.js
Solution 7: Handle Rename Conflicts
When a file was renamed with conflicts:
CONFLICT (rename/rename): src/old-name.js renamed to src/new-name.js in HEAD and to src/alt-name.js in feature-branchResolve by choosing which name to keep:
``bash
git mv src/old-name.js src/new-name.js
git add src/new-name.js
Verification
Confirm no unmerged paths:
``bash
git status
Should show:
``
On branch main
nothing to commit, working tree clean
Or after staging:
``
Changes to be committed:
modified: src/config.js
Verify no conflict markers remain:
``bash
git diff --check
No output means all markers are resolved.
Complete the merge:
``bash
git commit
View the merge result:
``bash
git log --oneline --graph -3
Shows the merge commit connecting both branches.
Common Pitfalls
Forgetting to commit after resolving: Git stays in merge state until you commit. If you resolve and add files but don't commit, the unmerged state persists.
Partial resolution:
Each file must be staged with git add after editing. Files remain unmerged until staged.
Conflict in .gitignore or .gitattributes: These can cause unexpected behavior. Resolve carefully as these affect repository behavior.
Best Practices
Check status frequently:
``bash
git status
Keep this visible while resolving conflicts.
Resolve one file at a time: Focus on understanding each conflict rather than batch processing.
Test after resolving:
``bash
npm test # or your test command
Ensure the merged code still works.
Use descriptive commit messages:
``bash
git commit -m "Merge feature-branch: resolve config conflicts by using production API URL"
Documents how conflicts were resolved.