Chapter 96Lesson 2

Reflog, bisect, and the rescue toolkit

Git's rescue and history-rewriting toolkit, reflog, bisect, cherry-pick, revert, and interactive rebase, governed by the single question of where a commit lives.

A rebase goes wrong and four hours of work vanish from your branch. A test that was green last week is red today, and all you know is that one of the forty commits since then is to blame. A one-line fix is sitting on a feature branch that won’t be ready to merge for another week, and production needs that fix now. These are not beginner problems. They show up precisely because you’ve started shipping like a team: more commits, more branches, more history to get lost in.

The previous lesson taught you the everyday loop: small branches, pull --rebase, and a squash-merge so main reads like a changelog. This lesson is what you do when a ship goes sideways, and the squash-merge discipline you just learned turns out to make most of these rescues much cheaper. You’ll pick up four power tools, plus the smaller commands each one leans on: reflog for getting lost work back, bisect for hunting down the commit that broke something, cherry-pick and revert for moving and undoing individual commits, and interactive rebase for cleaning up messy history before anyone else sees it. None of them are hard to type. The skill is knowing which one a given problem calls for, and that always comes back to a single question.

Where a commit lives decides what you can do to it

Here is the question, and you’ll ask it before reaching for any tool in this lesson: where does this commit live? There are three possible answers, and they form a gradient from “do whatever you want” to “look but don’t touch.”

The first zone is a commit that exists only on your machine. You committed it, but you haven’t pushed it anywhere. Nobody else has a copy, so nothing you do to it can surprise anyone. You can rewrite its message, fold it into another commit, reorder it, or delete it outright, and all of it is safe, because the only history you’re changing is one that only you can see.

The second zone is a commit you’ve pushed to your own feature branch but haven’t merged yet. Now there’s a copy on the remote, and in principle a teammate could have pulled your branch. In practice, on a short-lived feature branch that’s still yours, almost nobody has. So this zone is mutable with care: you can still rewrite, but once you do, the remote disagrees with your machine and you have to overwrite it with git push --force-with-lease. The --lease part, from the previous lesson, is the safety catch. It refuses the push if someone did pull and add a commit in the meantime, so you can’t silently bulldoze their work.

The third zone is a commit that has been merged to main. Other people have pulled it, and it’s woven into the shared history the whole team builds on top of. This zone is off-limits to rewriting, not because Git stops you, but because rewriting history that others already have creates a mess that can take the team a day to untangle. When something is already on main and it’s wrong, you don’t erase it. You add a new commit that undoes it. That tool is git revert, the one exception in this lesson that touches shared history, and it does so by adding a commit, never by rewriting one.

The diagram below lays out the three zones as a strip, from most mutable on the left to immutable on the right, with the move each one allows underneath it. This single picture is the decision you’ll make for every recovery in this lesson, so it’s worth fixing in your head now.

Freely mutable Local only Only on your machine

Allowed move Rewrite freely

Mutable with care Pushed to my feature branch On the remote, on your branch

Allowed move Rewrite, then --force-with-lease

Immutable Merged to main Everyone has pulled it

Allowed move git revert only — never rewrite

The same commit, three different sets of rules. The only question you ask before any rescue: which panel is this commit in?

That gradient rests on one mechanical fact about Git that you need before the next two sections will make sense. Recall from the previous lesson that a commit is a snapshot and a branch is just a movable pointer at one of those snapshots. The consequence, and the thing that makes recovery possible at all, is this: a commit is not deleted just because no branch points at it anymore. When you reset or rebase, you’re moving pointers; the old snapshots don’t evaporate, they simply become unreferenced. They linger on disk, fully intact, until Git’s garbage collection (GC) eventually sweeps them away. As you’re about to see, Git also keeps a journal of where every pointer has been, so even an unreferenced commit is usually one command away from coming back.

Before we get to the heavier tools, spend two minutes with the next embed. It’s the interactive Learn Git Branching sandbox, and the point of it here is to make pointers tangible. Type git commit a couple of times to grow a line of snapshots, then git checkout -b feature to drop a new pointer, then git commit again. Watch how the branch labels move while the commit nodes just accumulate. That mental image, pointers slide and snapshots stay, is the entire foundation for reflog and reset.

Type git commit, then git checkout -b feature, then git commit again. Moving a branch pointer never deletes a commit node, and that’s what makes everything in this lesson recoverable.

Open in a new tab ↗

One more term to pin down, since the next section depends on it. HEAD is Git’s name for where you are right now: the commit you currently have checked out, normally reached through whatever branch you’re on. Almost everything Git does moves HEAD, and the next tool is, quite literally, the log of every place HEAD has ever been.

The reflog is your undo history, and you set it up by knowing it exists

Most tools you learn when you need them. The reflog is the exception, and learning it early is worth the small effort. The moment you’d reach for it is the moment you think “I just lost my work,” which is the worst possible time to be reading documentation about a command you’ve never run. So you’re learning it now, before you need it, so that the rest of this lesson can be taught without fear. Once you know the reflog has your back, you can experiment with rebases and resets without worrying that one wrong move erases an afternoon.

Here’s what it is. Every time HEAD moves, on every commit, checkout, reset, rebase, and merge, Git appends a line to a private, per-repository journal called the reflog. It isn’t your project history; it’s the history of your pointer’s movements. And because the snapshots those movements left behind aren’t deleted (from the last section), the reflog is effectively a list of every state your repository has passed through recently, each one still reachable by its hash.

The recovery flow is two steps. First, read the journal with git reflog to find where you were before the mistake. Then jump back to it. Here’s what the reflog looks like right after a reset --hard discarded two commits, along with the two ways to recover.

$ git reflog
9f2c1ab HEAD@{0}: reset: moving to HEAD~2
3d8e4c7 HEAD@{1}: commit: Add status filter dropdown
a1b9f02 HEAD@{2}: commit: Wire filter to the query
7c4d2e9 HEAD@{3}: rebase (finish): returning to refs/heads/feat/invoice-status

# Recover by jumping the current branch back:
$ git reset --hard 3d8e4c7

# Or, safer — park the lost work on a new branch first:
$ git branch recover-work 3d8e4c7

Read the journal top-down. HEAD@{0} is where you are now, and the top line tells you the last thing you did, here the reset --hard that caused the problem.

$ git reflog
9f2c1ab HEAD@{0}: reset: moving to HEAD~2
3d8e4c7 HEAD@{1}: commit: Add status filter dropdown
a1b9f02 HEAD@{2}: commit: Wire filter to the query
7c4d2e9 HEAD@{3}: rebase (finish): returning to refs/heads/feat/invoice-status

# Recover by jumping the current branch back:
$ git reset --hard 3d8e4c7

# Or, safer — park the lost work on a new branch first:
$ git branch recover-work 3d8e4c7

The line just below the mistake is the commit you want back. Each entry shows the action and its message, so you can recognise the state you’re hunting for. Copy that hash.

$ git reflog
9f2c1ab HEAD@{0}: reset: moving to HEAD~2
3d8e4c7 HEAD@{1}: commit: Add status filter dropdown
a1b9f02 HEAD@{2}: commit: Wire filter to the query
7c4d2e9 HEAD@{3}: rebase (finish): returning to refs/heads/feat/invoice-status

# Recover by jumping the current branch back:
$ git reset --hard 3d8e4c7

# Or, safer — park the lost work on a new branch first:
$ git branch recover-work 3d8e4c7

The blunt recovery: move your current branch’s pointer straight back to that commit. It’s fast, but it discards anything after it, so only do this when you’re sure.

$ git reflog
9f2c1ab HEAD@{0}: reset: moving to HEAD~2
3d8e4c7 HEAD@{1}: commit: Add status filter dropdown
a1b9f02 HEAD@{2}: commit: Wire filter to the query
7c4d2e9 HEAD@{3}: rebase (finish): returning to refs/heads/feat/invoice-status

# Recover by jumping the current branch back:
$ git reset --hard 3d8e4c7

# Or, safer — park the lost work on a new branch first:
$ git branch recover-work 3d8e4c7

The careful recovery, and the better default: create a new branch at the lost commit without moving where you are. Now the work is safely parked and you can inspect it before deciding what to keep.

1 / 1

Reach for git branch recover-<something> <hash> over git reset --hard <hash> by default. Parking the recovered work on a fresh branch is non-destructive, so it can’t make a bad situation worse, and you can always merge or cherry-pick from it once you’ve confirmed it’s what you wanted.

The next sequence makes the underlying mechanism concrete. Scrub through it and watch the steps: HEAD starts at your latest commit with all your work, a reset --hard HEAD~2 slides the pointer backward so two commits become unreferenced, those same commits still sit in the reflog by hash, and a final reset to that hash brings the pointer, and the work, right back. Nothing is ever deleted; the pointer just moved, and the reflog remembered where.

feat/invoice-status HEAD

A7c4d2e9

Ba1b9f02

C3d8e4c7

You're at commit C, on branch feat/invoice-status — B and C hold your latest work.

$ git reset --hard HEAD~2

feat/invoice-status HEAD

A7c4d2e9

Ba1b9f02

C3d8e4c7

The pointers slid back to A. B and C lost their label — but they're still on disk, just dimmed and unreferenced.

feat/invoice-status HEAD

A7c4d2e9

Ba1b9f02

C3d8e4c7

git reflog

7c4d2e9 HEAD@{0} reset: moving to HEAD~2

3d8e4c7 HEAD@{1} commit: C

The reflog still lists C by its hash 3d8e4c7. The snapshot was never deleted — only unreferenced.

$ git reset --hard 3d8e4c7

feat/invoice-status HEAD

A7c4d2e9

Ba1b9f02

C3d8e4c7

Reset to that hash and both pointers return to C. Nothing was ever deleted — the pointer just moved, and the reflog remembered where. Your work is back.

Two practical limits keep the reflog honest. First, it is local: it lives in your clone and nowhere else. It can’t recover something only a teammate ever had, and a freshly cloned repository starts with an empty reflog, because no movements have happened on that machine yet. Second, it isn’t permanent: reachable entries survive roughly 90 days and unreferenced ones about 30 before garbage collection is allowed to prune them. The reflog is a net for recent mistakes, not an archive. If you find lost work, recover it now, not next quarter.

git stash parks unfinished work when the branch has to change

The reflog gets work back after you’ve lost it. git stash is the tool for not losing it in the first place when you’re forced to drop what you’re doing. The trigger is specific: you’re mid-change, the working tree is a half-finished mess that isn’t ready to be a commit, and an interruption arrives that needs a clean tree, such as an urgent review to check out, a hotfix to start, or a teammate asking you to reproduce something on main.

You can’t switch branches when a dirty working tree would conflict, and you don’t want to immortalize half a feature as a commit. Stash is the scratchpad in between: it saves your uncommitted changes onto a stack and resets the working tree to clean, so you’re free to move. When you come back, you pop them off and pick up exactly where you left off.

$ git stash push -m "wip: invoice status filter"
Saved working directory and index state On feat/invoice-status: wip: invoice status filter

$ git switch main          # go deal with the interruption

# ...later, back on the feature branch...
$ git switch feat/invoice-status
$ git stash list
stash@{0}: On feat/invoice-status: wip: invoice status filter

$ git stash pop            # restore the changes and drop the stash entry

Always give a stash a message with -m. An unlabeled stash on a stack of three is a guessing game a day later. And note that you’ve already been using stash without knowing it: the rebase.autoStash=true config line from the previous lesson auto-stashes your working tree around git pull --rebase and pops it back when the rebase finishes. Stash isn’t an exotic trick you’ll rarely touch; it’s already running quietly in your everyday loop.

git bisect finds the commit that broke it by binary search

Some bugs you can read your way to. This section is about the bug you can’t: a test that passed on a known-good version weeks ago and fails now, with a sizeable pile of commits in between and no obvious culprit. This isn’t “I just wrote a bug and I know roughly where”; it’s “a regression is hiding somewhere in the last forty commits and I have no idea which one.” Searching that by hand, commit by commit, is exactly the kind of tedious work you should never do, because Git can do it for you with binary search.

The idea is the one from any algorithms course. You know a commit far back was good and the current commit is bad, so the breaking change is somewhere between them. Instead of testing every commit, you test the one in the middle. If it’s good, the bug is in the newer half; if it’s bad, it’s in the older half. Either way you’ve eliminated half the suspects in one test. Repeat, and the window halves every time, so a thousand commits collapse to about ten tests, because that’s log₂(1000). The sequence below walks that search visually. It’s the core idea of the section, so step through it and watch the suspect window shrink.

known good known bad untested testing now

oldest

newest