Topic 45

When Something Looks Terrifying

Habits

Something has gone wrong. The terminal is showing a message you have never seen, work you were sure existed is not in the log, and your instinct is to start typing commands until it stops.

This page is the alternative, and it is written to be readable in that state rather than in this one. A procedure and a decision tree, both short.

1. Stop typing

Most work that is genuinely lost with Git is lost in the commands typed after the mistake, not in the mistake itself. Nothing gets worse while you read, and nothing in a Git repository decays if you leave it alone for ten minutes.

Take your hands off the keyboard. That is the entire first step, and it is the one that saves the most.

2. Find out where you are

Two safe commands that change nothing

git status
git log --oneline -5

status tells you which branch you are on and which of the three places holds what. log tells you what the history currently thinks happened. Between them they answer most of the question, and neither can make anything worse.

If a commit you expected is missing from the log:

Everywhere the branch has been

git reflog

3. Match the situation to the fix

The whole book's recovery, on one screen

Edited but never staged, and you want it gone→git restore · destroys it · 4.1

Staged something by mistake→git restore --staged · safe · 4.2

Last commit wrong, nothing pushed yet→git commit --amend · 4.3

Commit is wrong and already pushed→git revert · 4.4

A commit or branch has vanished→git reflog · 4.5

Conflict markers in a file→resolve, or git merge --abort · 6.4

Push rejected as non-fast-forward→git pull, resolve, git push · 7.5

Cannot switch: local changes would be overwritten→commit them, or git stash · 6.2

Every accident in this book fits somewhere on that list. The colour scheme you discarded on Sandpiper's stylesheet, the phone list staged by mistake, the commit amended a second too late, the home-page redesign the club hated, the push rejected because you had edited a page in the browser on the train. Five situations, five rows.

4. Read the error properly

Git's messages are unusually good and unusually long, which is a bad combination for a frightened reader. Two things help.

The last line is usually the instruction. Git very often prints the exact command it thinks you want, under a line starting with hint:.

And a refusal is protection. "would be overwritten", "rejected", "not fully merged" — every one of those is Git declining to destroy something. The dangerous commands are the ones that succeed quietly.

5. Asking for help well

When you do ask someone, three things turn twenty questions into a five-minute answer:

The command you ran, exactly. The full message, pasted rather than summarized — "it said something about a merge" is not enough to work with. And the output of git status, which answers the first question any experienced person is going to ask.

Everyone reaches for help with Git, including people who have used it for a decade. The difference between a good question and a bad one is those three things, not the level of the person asking.

Common Confusions

"A scary message means data has been lost." Almost every Git message is a refusal to do something risky. Refusals protect you; the commands that succeed silently are the ones to watch.
"Copying a command from a forum is the fastest fix." It is the fastest way to turn a small problem into a large one, especially when the command contains --force or --hard.
"Asking for help means admitting I do not know Git." Everyone asks. The three things above are what make the answer useful, and they are the entire difference.
"If I cannot see it in git log, it is gone." The reflog knows where the branch has been, and git stash list knows what is in the drawer. Between them they find nearly everything.

Why It Matters

One page you can return to under stress is worth more than remembering Chapter 4 perfectly, because stress is exactly when recall fails.
Diagnosing before acting is the same habit that made Chapter 4 safe in the first place, stated once more where it is needed most.
Knowing that a refusal is protection changes how Git's messages feel — from "something is broken" to "something was prevented".

Knowledge Check

What is the first step when something has gone wrong?

Stop typing, because most lost work is lost after the mistake
Run git reset --hard to get back to a known good state quickly
Clone the repository again so you have a clean copy to work from
Push what you have, so at least the current state is stored somewhere

Which two commands are the safe diagnosis, changing nothing?

git status and then git log --oneline -5, in that order
git reset and git checkout to return to a known position
git pull and git push to resynchronize with the remote copy
git stash and git branch -D to clear the working state first

Git refuses a command with a message about changes being overwritten. How should you read that?

As protection, since Git declined rather than destroying something of yours
As an error in the repository that must be repaired before continuing
As a sign that the previous command failed and left things inconsistent
As a permissions problem that needs the command to be run with more access

What three things should you include when asking someone for help?

The exact command, the full message, and the output of git status
A description of what you were trying to achieve and how urgent it is
A copy of the repository, so the other person can investigate it themselves
The list of every command you have run since the project was created

You got correct