Git Error Troubleshooting — The Complete Guide

Git Error Troubleshooting — The Complete Guide#

Git's error messages have a way of sounding like disasters when they're usually a two-command fix. The fear is understandable: it's your work on the line. But almost every Git problem you'll hit is one of a small, well-known set, and each has a safe, repeatable way out. This guide is the map: what each message means, the fix, and how not to lose anything on the way.

Before any specific error, two commands tell you where you stand:

git status      # what's staged, modified, untracked, and which branch you're on
git log --oneline --graph --decorate --all   # where the branches and HEAD actually are

Most Git panic comes from not knowing the current state. status and log remove the mystery.

"It won't let me switch or pull"#

• Your local changes would be overwritten: uncommitted changes block a checkout or merge. Commit or stash them first, explained in local changes would be overwritten.
• fatal: not a git repository: you're in a folder that was never initialized, or the wrong folder entirely. Fixed in not a git repository.

"It won't let me push"#

• Updates were rejected: the remote has commits you don't. You need to pull/rebase before pushing, and force-push only when you truly own the branch. Walked through in git push rejected.

"I need to undo something"#

• Undo a commit: soft, mixed, or hard reset, --amend, or revert, depending on whether it's pushed. The full decision tree is in undo the last commit, and the reset-vs-revert distinction is in git revert vs reset.
• Remove a large or secret file from history: a rewrite with git-filter-repo or BFG, plus Git LFS going forward. Covered in remove a large file from git history.

"Git is in a weird state"#

• Merge conflicts: two changes to the same lines. Not an error so much as a decision, handled calmly in resolve merge conflicts.
• Detached HEAD: you checked out a commit instead of a branch. What it means and how to get back is in detached HEAD.
• Rebase vs merge: not an error, but the choice behind half of them. Compared in rebase vs merge.

Quick lookup#

The mental model#

Git errors fall into a few buckets: your working tree is dirty (commit or stash), your branch diverged from the remote (pull/rebase), you need to undo (reset/revert/amend by whether it's pushed), or you're just somewhere unexpected (detached HEAD, wrong folder). Almost nothing in Git is truly lost, because git reflog remembers where HEAD has been. That safety net is why you can experiment without fear.

The call we'd make#

Run git status and git log --graph before you touch anything; most "errors" are just an unexpected state. Learn that reset/revert differ by whether the commit is shared, and that reflog can rescue almost any mistake. Each linked guide is the safe path for one specific situation. Git looks unforgiving and is actually the opposite: once you trust the reflog, the scary messages become routine.