When something looks broken
Written by a person. Last read by a person on 2026-09-04, 4 days ago. Its facts were checked by the eval suite on 2026-09-07.
Something has gone wrong in a repository and you are afraid of making it worse, or you have seen an error message that sounds more final than it is.
The useful first move is almost never a command. It is to find out where you are, because most things that look broken are actually you standing somewhere other than you thought.
Orient before you act
Three questions, in this order. Answer all three before doing anything that changes state.
Which branch am I on? git branch --show-current
What has changed that I have not recorded? git status
What have I recorded that I have not sent? git log origin/main..HEAD --oneline
That third one is the question nobody thinks to ask, and it is the answer to "where did my work go" about half the time. Work that is committed but not pushed is invisible to everyone else and completely safe. It has not vanished. It is on your computer, exactly where you left it.
Undoing, which is four different things
"Undo" is the word that gets people into trouble, because it names four operations with very different consequences. Decide which one you actually want before you type anything.
I have edits I do not want, and I have not committed them
The safest situation you can be in. Nothing is recorded, so nothing needs unpicking.
Discard changes to one file, returning it to your last commit: git restore <file>
This throws the edits away permanently. There is no history of uncommitted work, so there is nothing to recover afterwards. If you are unsure, copy the file somewhere else first — an inelegant move that has saved more work than any clever one.
I committed something and want to take it back
If you have not pushed, you can move the commit off and keep the changes as edits:
git reset --soft HEAD~1
Your files are untouched. Only the history entry goes away. This is the one people are most afraid of and it is almost entirely benign, provided you have not pushed.
I pushed something and want to take it back
Do not rewrite the history. Add a new commit that reverses the old one: git revert <commit>
This is slower and leaves both the mistake and the correction in the record, which is exactly right. Other people may already have your commit, and rewriting shared history is how you create the problem where everyone's repository disagrees about what happened.
I want the history itself changed
You almost certainly do not, and if you genuinely do, it is a conversation with whoever maintains the repository rather than a command you run alone. The only common legitimate case is a secret committed by accident, and that case is urgent for a different reason: assume the secret is compromised and rotate it, rather than assuming removal from history is sufficient.
Signals, and what they usually mean
| What you see | What it usually is |
|---|---|
| "Your branch is behind" | Somebody pushed; you need to pull |
| "Your branch is ahead" | You have commits not yet pushed. Nothing is wrong |
| "Updates were rejected" | Remote has work you do not have. Pull, then push |
| Merge conflict markers in a file | Two people changed the same lines. You decide which survives |
| "detached HEAD" | You are looking at a specific commit rather than a branch |
| Your change is nowhere on the site | Committed but not pushed, or pushed to another branch |
None of these is an error in the sense of something being damaged. Every one of them is git declining to guess about something only you can decide.
When to ask for help, and when to keep going
The instinct is to ask when you feel stuck, which is a poor signal because it fires constantly at the beginning and almost never later.
Here is a better test.
Keep going when the thing you are unsure about affects only your own computer, and you could throw the whole folder away and clone it again without losing anything that matters. That covers most local confusion, and the ability to start over cheaply is what makes exploring safe.
Ask when any of these is true:
- The operation would change history that other people already have.
- You are being asked to force something, and you do not know precisely what it will overwrite.
- A credential or secret has been committed.
- The same operation fails identically no matter what you change, which means it is permissions or configuration and not you.
- You have made the same attempt three times expecting a different result.
When you do ask, include the exact command you ran and the exact message you got back, as text rather than a description. "It says it can't push" and the actual seven lines it printed are different amounts of information, and the second one usually contains the answer.
What this page does not cover
Rebasing, submodules, and anything involving force. Those are not omitted because you could not learn them. They are omitted because they are not part of the job this runbook exists to make survivable, and a page that covers everything is one nobody finishes.