Troubleshooting — The Librarian's Problem Desk
Everyone eventually sees a scary Git message. This is the Problem Desk: what the message means, why it happened, and how to get out. Each problem follows the same Problem → Cause → Fix rhythm you know.
1 · "You are in 'detached HEAD' state"
Git prints a long warning, and you feel like you broke something.
Cause: You ran git checkout <some-commit-hash> (like in Exercise 4). HEAD — the name on your notebook — is now pointing at a past commit with no branch. You're standing in the past, not on any named branch.
Fix: Nothing is lost. Get back to a branch:
git switch main
Or, if the work you did in the past is worth keeping, name it:
git switch -c feature-from-past
Detached HEAD = "you are in the past with no notebook name." Creating a branch before adding commits prevents losing work.
2 · "You have unstaged changes" — can't switch branches
git switch refuses and mentions your uncommitted changes.
Cause: Your working copy has changes that would collide with the branch you're moving to. Git won't risk the mess.
Fix (choose one):
git add .
git commit -m "Save current work"
git stash
git restore .
3 · "fatal: not a git repository"
Git commands fail immediately with this error.
Cause: You're in a folder that isn't inside a repository — usually the wrong directory, or you never ran git init/git clone there.
Fix:
pwd
ls -a
Then either move into the right folder, or open a register here:
git init
4 · "non-fast-forward" — push rejected
git push is rejected and mentions non-fast-forward or fetch first.
Cause: The central library has commits you don't have yet. You're trying to push pages built on a stale copy.
Fix:
git pull
git push
If the pull creates a conflict, resolve it like in Exercise 3, commit, then push.
5 · Typo or missing file in my last commit
The last commit message is wrong, or a file was left out.
Cause: You committed too fast. Happens to everyone.
Fix (only if not pushed yet):
git commit --amend -m "The correct message"
git add the-file
git commit --amend --no-edit
Don't amend a commit your teammates already pulled — use git revert instead. See the Rescue Toolkit.
6 · "Please tell me who you are"
Git refuses to commit because it doesn't know your name.
Cause: You never ran git config after installing Git (skipped Exercise 0).
Fix:
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Still stuck?
The Problem Desk always starts with the same two tools:
git status
git log --oneline -5
If you can answer "which branch am I on?" and "what's the last commit?", the fix for almost any problem becomes obvious. And if a term still confuses you, the Glossary is one click away.