Common Git Errors and How to Fix Them

Git's error messages are precise but not always obvious to newcomers. This guide walks through four errors nearly every developer hits — merge conflicts, detached HEAD, unrelated histories, and failed pushes — with the exact commands to resolve each one safely.

Merge Conflict

Auto-merging src/app.js
CONFLICT (content): Merge conflict in src/app.js
Automatic merge failed; fix conflicts and then commit the result.

Git couldn't automatically combine changes because both branches edited the same lines. Open the file and look for conflict markers:

<<<<<<< HEAD
const PORT = process.env.PORT || 3000;
=======
const PORT = process.env.PORT || 8080;
>>>>>>> feature/change-default-port

# 1. Edit the file, keep the correct code, delete the <<<, ===, >>> markers
# 2. Stage the resolved file
git add src/app.js
# 3. Complete the merge
git commit
# (or if mid-rebase)
git rebase --continue

Detached HEAD

Note: switching to 'a1b2c3d'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

This happens after git checkout <commit-hash> instead of a branch name. Any commits made here are not attached to a branch and can be lost.

# If you haven't made new commits yet, just go back:
git checkout main

# If you already made commits you want to keep,
# create a branch right now to save them:
git checkout -b recovered-work
git checkout main
git merge recovered-work

Refusing to Merge Unrelated Histories

fatal: refusing to merge unrelated histories

This happens when the two branches (or your local repo and a remote) don't share a common ancestor commit — common when you initialize a new local repo and then try to pull from a remote that already has its own history (like a fresh GitHub repo created with a README).

git pull origin main --allow-unrelated-histories

# or for a merge directly
git merge other-branch --allow-unrelated-histories

Expect to resolve merge conflicts afterward since Git now has to reconcile two completely separate commit trees.

Failed to Push

! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'https://github.com/you/repo.git'
hint: Updates were rejected because the remote contains work that you do not
hint: have locally. This is usually caused by another repository pushing to
hint: the same ref.

The remote branch has commits your local branch doesn't have — typically a teammate pushed first. Pull and integrate before pushing again.

# Safest: pull with rebase to keep history linear
git pull --rebase origin main
# resolve any conflicts, then:
git push origin main

# Never use --force on a shared branch to "solve" this —
# it overwrites your teammate's commits on the remote.

General Prevention Tips

• Pull before you start working and before you push, to reduce the odds of a conflict
• Commit small, focused changes — smaller diffs conflict less often and are easier to resolve when they do
• Always check git status before switching branches or pulling, so you know if you have uncommitted work
• Never use git push --force on a shared branch; use --force-with-lease if you must force-push your own feature branch

Frequently Asked Questions