We have been putting this lesson off for six modules. In 03-02 we said that the reflog explains how Git remembers where HEAD has been. In 03-06 we promised that deleting a branch with -D is almost never irreversible, and pointed here. In 05-01 we said a disastrous rebase can be undone, and pointed here. In 05-04, that an accidental stash drop is recoverable. In 09-02, that the commits a reset --hard leaves behind are still there. And in 09-03, that origin/main@{1} keeps where the server was before the rewrite.

All those promises rest on the same piece, and it is time to develop it in full.

The reflog is probably the Git feature with the best ratio between what it saves and how little it is known. Plenty of people have been using Git for years without ever having run it, and it is exactly the command that turns "I have lost three days' work" into "it took me two minutes to get it back".

Let us start with the most important thing: if you have arrived here in a panic, you have lost nothing, provided that what you are looking for made it as far as being a commit. Read on calmly.

1. What the reflog is and where it lives
2. Local and temporary: the two limits you need to know
3. Reading git reflog
4. HEAD@{n} versus HEAD@{time}
5. The universal recovery pattern
6. Recipe book: reset --hard, deleted branch, rebase, merge, --amend
7. When the reflog is not enough: git fsck --lost-found
8. Recovering a deleted stash
9. The real limits: what cannot be recovered
10. Hygiene: do not destroy your own safety net

The reflog is the local record of every movement of every reference.

Every time a reference — HEAD, a branch, a remote tracking branch — changes value, Git writes a line in a text file noting where it came from, where it is going, who did it and why.

Look at it directly:

Each line has: previous hash, new hash, identity, timestamp, and a description of the operation. It is plain text, with no magic.

The directory structure:

And here is the key to the whole module. Recall the idea from lesson 09-01:

A commit survives as long as something reaches it. Reflog entries count as references.

That is why git gc does not remove a commit that appears in the reflog, even if no branch points at it. The reflog is not just a record: it is what keeps orphaned objects alive. That is the technical reason recovery works.

Before the recipe book, the two limitations. Not understanding them is what leads people to trust the reflog when they should not.

The reflog does not travel. It is not published with push, it is not downloaded with fetch, and a git clone does not bring it.

A single entry. All the movement history Ana had on her machine stays on her machine.

Three practical consequences:

1. Ana's reflog cannot rescue Bruno's disaster. Everybody has their own.
2. The reflog is not a backup. If the disk dies, it dies with it. The real backups are git bundle and the team's own clones (lesson 09-05).
3. A freshly made clone has no safety net. The first unfortunate reset --hard in a new clone really can leave you with nothing to recover, because there are no earlier entries.

And a positive consequence, the one from section 9 of lesson 09-03: if a colleague forces and destroys a branch on the server, your reflog for origin/branch keeps where it was, and with it you can restore it.

Entries expire. Two parameters govern this:

The second is the one that matters: genuinely orphaned commits have 30 days. After that, a git gc purges them for good.

The expiry does not happen on its own: it is carried out by git gc (lesson 08-06), which Git launches automatically when loose objects pile up. In practice, you have weeks, not months, and certainly not years.

You can extend the deadline:

It costs a few megabytes and buys a great deal of peace of mind.

And the opposite, which you should never run unless you know exactly what you are doing (lesson 08-06):

How to read it:

• HEAD@{0} is always the last thing that happened. The order runs from the present into the past.
• The hash on each line is where HEAD ended up AFTER that operation. This detail is crucial and produces the most frequent mistake: if you want the state prior to the HEAD@{0} operation, you need the hash from HEAD@{1}.
• The description says which command caused it.

The vocabulary of the descriptions:

Far cleaner than the HEAD one when you know which branch you are interested in, because it does not include the branch switches.

--date=relative is the one that helps most in a recovery: "I had it just before lunch" translates directly into an entry.

And git log -g (or --walk-reflogs), which walks the reflog showing each entry as a complete commit:

Useful when you do not recognise a commit by its message and need to see which files it touched.

Two syntaxes that look alike and mean different things.

The critical distinction, and it deserves an example:

HEAD~3 walks the graph: it follows the chain of parents. HEAD@{3} walks your personal history: it may be on another branch, on an orphaned commit, anywhere you have been.

When you have done a reset, HEAD~1 takes you to the current commit's parent (which is no longer what you were after) and HEAD@{1} takes you to where you were before the reset (which is).

The time forms accept very natural expressions:

And the warning Git gives you when you go beyond the deadline:

It is not an error: it is telling you that it has used the oldest entry available. If the date you asked for is earlier than that, the result is not what you think it is.

All the recipes in the next section are the same procedure. Learn it once.

Step 4 is the one to internalise, and it is the difference between a calm recovery and a second scare:

git branch is purely additive. If the hash was the wrong one, you delete the branch and try another. Nothing has moved. With reset --hard each failed attempt adds another layer of confusion.

And step 3, verifying, prevents the mistake of recovering the wrong commit:

And to inspect without committing to anything:

The situation. Ana wanted to remove one commit and typed HEAD~3.

You have lost nothing (apart from anything uncommitted, lesson 09-02).

HEAD@{1} (9c4e7b2) is the tip that existed just before the reset.

Recovered. Now, if you want GT-241 to be that again:

The shortcut, if you have just done it and have done nothing else since (lesson 09-02):

Or directly with the reflog syntax:

This closes the promise from lesson 03-06.

First gift: Git prints the hash when it deletes. If you still have it in the terminal buffer, recovery is immediate:

If you have closed the terminal, there are two routes.

A. The HEAD reflog (works if you were on that branch):

B. Searching by message among all the orphaned commits (always works):

Or directly against the object database:

And the important detail that gets forgotten: a branch's own reflog is deleted along with it.

.git/logs/refs/heads/GT-247 no longer exists. That is why you have to search in the HEAD reflog, which does survive.

-D is almost never irreversible. The commits are still in .git/objects, reachable from the HEAD reflog, for at least 30 days. The promise from lesson 03-06 is duly kept.

And the exception, to be honest about it: if the branch was created, committed to and deleted without HEAD ever passing through it (for example, with git branch X <hash> and then git branch -D X), the HEAD reflog does not record it. In that case, the git fsck from section 7.

This closes the promise from lesson 05-01.

Bruno did a rebase -i of ten commits, squashed the ones he should not have and finished with --continue.

The key entry is rebase (start): the one before it is the exact state prior to the rebase. Here, HEAD@{5} → 9c4e7b2.

The ten original commits, intact.

A shortcut hardly anybody knows about: during a rebase, Git saves the initial position in ORIG_HEAD, and also in a special reference:

And if the rebase has not finished yet, the way out is far simpler:

It returns everything exactly to the previous state. Use it whenever you can: it is cleaner than recovering afterwards.

To compare the result with the original and decide what to do, git range-diff (lesson 07-02):

If you have just done it and there is nothing on top:

merge always writes ORIG_HEAD before merging. It is the canonical way out.

If you have already done more things on top:

HEAD@{2} is the state prior to the merge. But careful: if you go back there, you also lose the commit c7e2a91 you made afterwards. The right thing to do is to rescue it separately:

And if the merge is already published, forget the reflog: the answer is git revert -m 1 (lesson 05-06).

A frequent and disconcerting case: git merge --abort does not work because the merge finished successfully; it was merely a bad idea. --abort is for while there are unresolved conflicts, not afterwards.

Carla ran git commit --amend and realised she has lost part of the original message — or worse, that the previous commit had changes the new one does not.

You have lost nothing. --amend does not modify the commit: it creates a new one and moves the branch (lesson 09-01). The original is still in the database.

HEAD@{1} (8f4c2a9) is the original commit, before the --amend.

And the ways of recovering, depending on what you need:

Picking up section 5.7 of lesson 09-01: you made commits in detached HEAD and moved away.

The line checkout: moving from 9c4e7b2 to main gives you the hash of where you came from.

The reflog records the movements of references. There are objects that reach the database without any reference moving, and for those you need the other tool.

And it also creates a directory of links:

dangling is normal and harmless. It is not a symptom of corruption. It is what you would expect in any active repository. The distinction between that and the real errors (missing, broken link) is lesson 09-05.

An fsck can return dozens of lines. The work is identifying which one is yours.

That turns a list of hashes into usable information. Save it as an alias:

Individual inspection, with the plumbing tools from lesson 01-04:

This is the case that saves more work than people expect. If you staged a file with git add and then lost it, the content is in the database (lesson 09-01, table in section 1).

Searching for a string you remember is far more effective than reviewing the blobs one by one.

This closes the promise from lesson 05-04.

First gift, once again: drop prints the hash. With it:

And if it was git stash clear, which wipes the whole stack without printing anything, there are two routes.

A. The stash reflog, if it still exists:

stash clear deletes the reference, but the log file sometimes survives until the next gc. It is worth looking at that first.

B. Searching for the stash commits among the unreachable ones:

Stashes are recognisable by their message: WIP on <branch>: (the automatic ones) or On <branch>: <message> (the ones you created with -m).

Internally a stash is a merge commit with two or three parents, and it is worth seeing because it explains how it works:

And the recovery:

Time to be honest. There are two boundaries no technique in this lesson crosses.

We saw it in lesson 09-01, and it is the fundamental limitation:

When you are in one of the last three cases, Git can no longer help you. What is left is outside Git:

1. Your editor's local history. It is the route that works most often and the one that is tried least.

• VS Code: command palette → "Local History: Find Entry to Restore". It keeps versions of every file you have edited, independently of Git.
• IntelliJ / WebStorm / Eclipse: the file's context menu → Local History → Show History. It keeps weeks of it.
• Vim: if you have set undofile, the undo history persists between sessions (:earlier 1h).

2. System backups: Time Machine on macOS, Btrfs/ZFS snapshots, previous versions on Windows, cloud copies.

3. Looking in /tmp and in the editor's swap files (Vim's .swp, other editors' ~).

If git gc --prune=now was run after the commit became orphaned, the object has physically disappeared. And if git reflog expire --expire=now --all was run too, there is not even a record.

Check whether it is still there before giving up:

That message means the object no longer exists. But before writing it off, look outside your machine:

That is the safety net of the distributed model, and it is the central theme of lesson 09-05.

The fifth is the most underrated. A published branch is on two machines. No local accident can beat that.

The lesson closes with what not to do.

1. git reflog expire --expire=now --all. It empties the record. Everything orphaned is left unprotected.

2. git gc --prune=now. It immediately removes unreachable objects. It has its legitimate use (after a filter-repo from lesson 08-05, where deleting is precisely the aim), and none on a normal day.

3. Trusting the reflog as a backup. It is local, temporary and dies with the disk. It is not a backup.

4. Recovering with reset --hard instead of git branch. Each failed attempt adds confusion. branch moves nothing.

5. Working for months without publishing a branch. A new clone has an empty reflog; an unpublished branch exists on a single disk.

And a thirty-second health check, to know whether your safety net is where you think it is:

Mistake 1: not trying git reflog. It is the first command for any "I have lost commits", and most people never run it.

Mistake 2: confusing HEAD@{1} with HEAD~1. The first is where you were one operation ago; the second is the parent commit. After a reset, they are completely different things.

Mistake 3: taking the hash from the wrong entry. A line's hash is where HEAD ended up after that operation. For the state prior to HEAD@{0}, you need HEAD@{1}.

Mistake 4: recovering with reset --hard instead of git branch. If the hash was the wrong one, with branch you delete the branch and try another; with reset each attempt makes the state more complicated.

Mistake 5: believing that the reflog travels in a clone. It does not. The new clone has a single entry and no safety net.

Mistake 6: trusting the reflog forever. 90 days for the reachable, 30 for the orphaned, and gc enforces them. In practice, weeks.

Mistake 7: being alarmed by git fsck's dangling entries. They are normal in any active repository. What is serious is missing and broken link (lesson 09-05).

Mistake 8: writing off a stash. stash drop prints the hash, stash clear leaves the commits orphaned, and both are recovered with git fsck --unreachable looking for WIP on.

Mistake 9: giving up without looking outside Git. The editor's local history recovers what Git cannot, and hardly anybody tries it.

Tip 1: the pattern is always the same. Reflog → verify with git show → git branch rescue <hash>.

Tip 2: git reflog --date=relative. "I had it before lunch" translates directly into an entry.

Tip 3: define the git lost alias. On the day you need it you will not remember the fsck and awk pipeline.

Tip 4: git rebase --abort while you still can. Far cleaner than recovering afterwards.

Tip 5: extend the reflog to a year. Two lines of global configuration and a few megabytes.

Tip 6: publish your branches. A branch on two machines is immune to the accidents of one.

On a test repository with app.js, styles.css and index.html:

1. Create six commits on main and a branch GT-241 with three commits of its own.
2. Provoke four disasters in a row, without recovering in between: a. git reset --hard HEAD~2 on GT-241. b. git switch main && git branch -D GT-241. c. A git commit --amend on main that deletes part of the message. d. A git merge of an experimental branch you did not want.
3. Run git reflog --date=relative and note down, for each disaster, which entry you would use.
4. Recover all four things using always git branch, never reset.
5. Verify each recovery with git show --stat and git diff.

1. In a new repository, create three situations: a commit, a file staged with git add, and a file modified on disk only.
2. Run git reset --hard HEAD~1.
3. Recover the commit with the reflog and the staged file with git fsck --lost-found + git cat-file -p.
4. Document why the third is unrecoverable, checking it with git fsck and git reflog.
5. Create a stash with -u, delete it with git stash clear and recover it with git fsck --unreachable.
6. Check with git show --format='%p' -s that the stash has three parents and inspect each of them.

1. Create a repository with ten commits and produce five orphaned commits with reset.
2. Check that they appear in git fsck --lost-found.
3. Run git reflog expire --expire=now --all and look at git reflog and git fsck again. Explain the difference between the two outputs.
4. Run git gc --prune=now and check with git cat-file -t <hash> that the objects really have disappeared.
5. Repeat the experiment having first configured gc.reflogExpireUnreachable "1 year" and explain what changes.
6. Write the health check from section 10 into a script and interpret its output on a real repository of your own.

Solution 1:

Note the nuance in (b): after the reset --hard, GT-241 pointed at 6e2b9c7, and that is what -D deleted (8a1f6c3 in the message's example). But what Ana wants is the state prior to the reset, 9c4e7b2. The reflog keeps both.

None of those operations has moved main. Everything that was there is still where it was, and now there are also three points of access to what has been recovered.

The three commits, including the two the reset --hard had left behind.

The original message, before the --amend reduced it to chore.

The only thing the unwanted merge contributed. To undo it:

And to restore GT-241 properly:

Solution 2:

A single dangling object (the one from the add), no reflog entry, and not one byte anywhere in .git. The line ON DISK ONLY never became an object: its SHA was never calculated, it was never compressed, it was never written. Git cannot give back what it never received. The only routes would be the editor's local history or a filesystem copy.

Recovered in full, including the untracked file.

Three parents exactly as section 8 said: HEAD, the index and the untracked files. A stash is a commit, and that is why it survives stash clear.

Solution 3:

The key difference: the reflog is empty, but the objects are still there. reflog expire deletes the record, not the objects. They can still be recovered with fsck... but you no longer know which one was the tip or what order they were in, because that information lived in the reflog. Recoverable, yes; convenient, no.

Now it really has gone. The object no longer exists in .git/objects. No technique in this lesson recovers it; only somebody else's clone or a backup.

The gc --prune=now has not been able to purge anything, because the reflog entries are still valid and the reflog counts as a reference. That is the exact mechanism that keeps orphaned objects alive, and it is why extending the expiry genuinely protects you.

The last line is the one that gives most information in a real repository: every branch with no upstream exists on a single disk.

The reflog is the reason almost nothing is lost in Git, and knowing it completely changes your relationship with the destructive commands.

• The reflog records every movement of every reference, in plain text under .git/logs/. And it is not merely a record: its entries count as references, and that is why they keep alive the commits no branch reaches.
• It is local: it does not travel in a clone, it is not published, and it dies with the disk. It is not a backup. And it is temporary: 90 days for the reachable, 30 for the orphaned, which gc enforces.
• HEAD@{n} is not HEAD~n. The first walks your personal history of movements; the second walks the graph. After a reset, they are different things, and confusing them is the commonest mistake.
• The recovery pattern is always the same: git reflog → verify with git show --stat → git branch rescue <hash>. Creating a branch is additive and moves nothing; reset --hard complicates every failed attempt.
• The recipe book covers everything this course had been promising: undoing a reset --hard (the entry before the reset:), recovering a branch deleted with -D (the hash it prints, or the HEAD reflog, because the branch's own is deleted with it), rescuing a rebase (the entry before rebase (start), or --abort if it is still under way), undoing a merge (ORIG_HEAD) and recovering what an --amend swept away (the previous commit: entry).
• When the reflog is not enough, git fsck --lost-found: dangling objects are normal, and among them are the orphaned commits and the blobs of a git add that was never committed. git cat-file -p and git show inspect them.
• A stash is a commit with two or three parents (HEAD, index, untracked), and that is why it survives drop and clear: you look for WIP on among the unreachable ones and put it back with git stash store.
• The limits are real: what never became an object (modifications with no add, files deleted by clean) and what has already been through gc --prune. There, only the editor's local history, a system copy or a colleague's clone can save you.
• And the prevention that makes the whole lesson unnecessary: commit often, plant a git branch before anything risky, stash push -u before cleaning up, extend the reflog to a year and publish your branches.

Up to here, everything has rested on one premise: that the object database was healthy. The objects existed, the hashes added up and Git could read them.

And when it is not? When git status replies error: object file .git/objects/4f/8a2e6... is empty, when a reference points at an object that does not exist, when the index is corrupt and Git refuses to do anything at all. That is no longer a problem of badly placed references: it is a problem of integrity, and it has its own diagnosis, its own repairs and — most importantly — a clear criterion for knowing when to stop trying to fix it and clone again.

Continue in lesson 09-05: Dealing with Corrupted Repositories.