Practical guide · verified against the real thing
Git errors decoded: merge conflicts, detached HEAD, and the mistakes that cause them
In one line: The five errors every beginner meets, what Git is actually saying in each, and the fix that doesn't lose work.
Git's error messages are precise — the problem is that they're precise in Git's worldview, not yours. Here are the five every newcomer meets, translated, with fixes that keep your work. (The concepts behind these live in the Git-and-G concepts guide; this piece is the emergency room.)
1. The merge conflict
CONFLICT (content): Merge conflict in filename — Git is saying: your change and another change touched the same lines, and it refuses to guess which wins. The file now contains markers: <<<<<<< HEAD above your version, =======, and >>>>>>> branch-or-commit above theirs. The fix is editorial, not magical: open the file, decide what the correct text should be (yours, theirs, or a blend), delete the markers, save. Then git add filename and commit. Never delete the file and start over — that's how a twenty-line conflict becomes a lost afternoon. And a conflict you can't resolve now has a clean escape: git merge --abort returns the repository to its pre-merge state, untouched.
2. Detached HEAD
You are in 'detached HEAD' state — you checked out a specific past commit instead of a branch. Perfectly legal and useful for reading history; dangerous only if you commit there, because those commits belong to no branch and get garbage-collected away. If you made commits in this state and want them: git switch -c my-rescue-branch pins them to a new branch immediately. If you changed nothing: git switch main and move on.
3. Push rejected
! [rejected] ... fetch first — the remote has commits you don't have. Git refuses to overwrite other people's work. The fix: git pull first (resolve any conflicts from step 1), then push. The mistake to avoid: --force, which exists for rewriting your own published history and annihilates everyone else's commits on shared branches.
4. "fatal: not a git repository"
You're running Git in a folder Git doesn't govern — usually the wrong directory, occasionally a deleted .git folder. Check where you are (pwd), cd into the project root, retry. If the folder genuinely lost its .git, the history is gone from that copy; re-clone from the remote and re-apply whatever wasn't pushed — which is the argument for pushing small and often.
5. The accidental commit
Wrong message, or a secret file included: not yet pushed — git commit --amend fixes the message; git reset --soft HEAD~1 unwinds the commit while keeping the changes staged. Already pushed — a later commit that removes the file is the safe move, and if the file was a credential, treat the key as burned and rotate it regardless of the cleanup (token hygiene, and check git log -S for how deep it goes). History rewriting on shared branches buys cleanliness at the cost of everyone's sanity.
The meta-lesson from every incident here: Git almost never loses committed work — uncommitted work is what vanishes. When panic hits: git status first. It tells you exactly what state you're in, and its suggestion is usually the fix.
Sources
Next