The reflog, short for “reference log,” is a chronological, local record of every point HEAD and your branch references have pointed to over time. Every time you commit, checkout, merge, rebase, reset, or otherwise move a ref, Git silently appends an entry to the reflog describing exactly what moved, from where, to where, and why.

Picture a concrete scenario: a developer named Wei is cleaning up a messy branch history using an interactive rebase. Midway through, something goes wrong, and the branch ends up in a state that looks nothing like what he intended — commits seem to have vanished entirely. Rather than panicking, Wei opens the reflog, finds the exact entry showing where his branch pointed immediately before the rebase began, and resets back to it — recovering his original state in seconds, even though nothing in his ordinary commit history ever showed that “before rebase” moment directly.

Git gives users enormous power to rewrite, discard, and restructure history — resets, rebases, amends, force-deletions. That power is genuinely useful, but it comes with an obvious risk: what happens when you rewrite away something you actually needed? Without some kind of safety net, an accidental hard reset or a botched rebase could mean real, permanent data loss with no recourse at all.

The reflog exists specifically to soften that risk, without getting in the way of Git’s flexibility. Rather than preventing destructive operations outright (which would undermine the very power that makes Git useful), Git quietly keeps its own private trail of where things have recently been — giving users a practical way back from most accidents, without needing to sacrifice the freedom to rewrite history when that’s genuinely what’s wanted.

The reflog isn’t one single global list — it’s actually a small collection of separate logs, each tied to a specific reference.

This per-reference structure matters: HEAD’s reflog and a specific branch’s reflog can tell different stories, since HEAD moves in situations (like a plain checkout to another branch) that don’t necessarily move any particular branch’s own pointer at all.

Here’s the sequence Git follows internally whenever an operation moves a reference.

flowchart TD
    A["Operation moves HEAD\nor a branch ref"] --> B["Old commit hash\ncaptured"]
    B --> C["New commit hash\ncaptured"]
    C --> D["Descriptive entry\nappended to reflog"]
    D --> E["Entry stored locally\nin .git directory"]
    E --> F{"Something goes\nwrong later?"}
    F -->|"Yes"| G["Reflog consulted to find\nthe commit before the mistake"]
    G --> H["Branch reset back\nto that recovered commit"]
    F -->|"No"| I["Entry eventually expires\nafter retention window"]
    

The branching path at the bottom captures the reflog’s entire practical purpose: most entries are simply written and quietly age out, unused, forming an invisible safety net that most developers never consciously interact with — until the rare moment they genuinely need it, at which point it becomes indispensable.

A wide range of everyday and advanced Git operations generate reflog entries, each tagged with a description of the specific action.

Notice that a single high-level command like an interactive rebase can generate many individual reflog entries under the hood — one for each internal step it performs — which is precisely why the reflog can often help recover from a rebase gone wrong at a very specific, granular point, not just from before the whole operation started.

These two are easy to conflate, but they answer fundamentally different questions, and understanding the distinction clearly is essential to using the reflog correctly.

This is the reflog’s signature use case, and understanding the recovery pattern in detail is what makes it genuinely useful under pressure rather than merely theoretical.

The reflog is not designed as a permanent, indefinite archive — entries are deliberately allowed to expire over time, and understanding this expiration model is important for anyone relying on it for recovery.

• Reachable entries typically expire after around 90 days by default. Reflog entries for commits still reachable from some branch or tag are generally kept for a fairly generous window before becoming eligible for cleanup.
• Unreachable entries expire much sooner, often around 30 days by default. Once a commit is no longer reachable from any branch or tag at all, its reflog entry — and eventually the commit object itself — becomes eligible for garbage collection considerably faster.
• Expiration happens as part of routine repository maintenance. Git’s periodic garbage collection process is what actually prunes expired reflog entries and any commit objects that have become fully unreachable and unreferenced.
• These windows are configurable. Teams with specific recovery needs can adjust the default retention periods, trading some extra local disk usage for a longer recovery window.

Because the reflog is a detailed, local record of activity, it carries some worthwhile security and privacy considerations, particularly on shared or less-trusted machines.

• The reflog can reveal history that was deliberately rewritten away. If sensitive content was committed and later removed via a history rewrite specifically to eliminate it, the original commit may still be recoverable through the reflog until it fully expires and is garbage collected.
• It never leaves the local machine on its own. Because it’s purely local and never pushed to a remote, the reflog doesn’t expose activity to collaborators or expand the audience with access to it beyond whoever already has access to that specific local clone.
• Fully removing sensitive committed content requires more than a simple history rewrite. A thorough removal typically needs to address the reflog entries and force garbage collection as well, not just amend or rebase the visible branch history.
• Shared or multi-user machines warrant extra caution. On a computer accessed by multiple people, a detailed local reflog is one more place where sensitive project activity could potentially be inspected by someone with access to that machine’s filesystem.

Git provides direct ways to view and work with reflog data, useful both for routine recovery and for genuinely understanding how a repository’s local state evolved.

Understanding what the reflog genuinely cannot do is just as important as understanding what it can, especially in a moment of real panic where false confidence could lead to worse decisions.

• It cannot recover uncommitted work. If changes were never staged and committed, no ref ever pointed to them, and the reflog has no record to offer.
• It cannot help with a fresh clone. A newly cloned repository has no accumulated reflog history at all — it only builds up over time as operations are actually performed locally in that specific clone.
• It cannot recover a teammate’s separate local mistakes. Since it’s entirely local, one person’s reflog has no knowledge whatsoever of another person’s independent local repository or its history.
• It eventually runs out. Once an entry expires and the underlying commit is garbage collected, that specific recovery path is genuinely gone — the reflog is a safety net with real limits, not an infinite undo history.

• Learn to read the reflog before you actually need it. Familiarizing yourself with its output in a calm moment makes it far easier to use effectively under real pressure.
• Commit early and often, especially before risky operations. This maximizes what the reflog is actually able to help you recover, since it only ever restores previously committed states.
• Don’t rely on the reflog as a substitute for genuine backups. Its local-only nature and finite retention window make it a safety net for accidents, not a durable, long-term recovery system.
• Remember its scope is local when debugging “missing” commits on shared branches. If a teammate’s push seems to be missing something, their own reflog — not yours — is what would hold any relevant local history.
• Treat sensitive-data removal from history as an operation that must also account for the reflog. A genuinely thorough removal needs to expire the relevant entries and force garbage collection, not just rewrite the visible branch.

A subtler mistake worth calling out: assuming that because the reflog exists, destructive commands like a hard reset or force push are essentially “safe” to use casually. The reflog meaningfully reduces the consequences of a mistake — it doesn’t eliminate the value of care and deliberate intent when using genuinely history-altering operations in the first place, particularly ones that affect shared, already-pushed branches other people depend on.