recover-git-state

name	recover-git-state
description	Recovers lost or broken git state — restores dropped commits/branches/stashes via reflog and fsck, pins a regression with git bisect, and safely undoes a bad reset/rebase/merge with revert or reset --soft/--mixed/--hard — without destroying still-recoverable objects.
when_to_use	Work appears gone after a reset --hard, bad rebase, deleted branch, dropped stash, or detached HEAD, or you need to pin which commit introduced a bug. NOT intentional history editing (rewrite-git-history), conflict-marker resolution (resolve-merge-rebase-conflict), or diagnosing a non-git code failure (debug-root-cause).

When to Use

Reach for this when work appears gone or HEAD landed somewhere wrong — the commits almost always still exist as unreachable objects:

• "I lost my commits" / "my branch is empty" after a reset --hard, bad rebase, or force-fetch
• "I deleted the wrong branch" (git branch -D feature)
• "I'm in detached HEAD and made commits — did I lose them?"
• "I git stash drop'd / stash pop'd into a conflict and lost a stash"
• "Which commit broke this?" — a regression to pin across a known-good..bad range
• A merge/rebase/reset made things worse and you want it back exactly as it was

NOT this skill:

• Intentionally rewriting history (squash, reword, rebase to clean up, strip a secret) → rewrite-git-history
• Resolving the conflict markers from an in-progress merge/rebase/cherry-pick → resolve-merge-rebase-conflict
• The code itself is failing (test/crash/wrong output) and git history is fine → debug-root-cause
• The file was never committed and isn't in any stash → git can't recover it; check editor local history / backups

Steps

1. STOP and snapshot before touching anything. Recovery commands can themselves overwrite refs. Freeze current state so you can't make it worse:

   git stash list; git status; git log --oneline -5   # what do we actually have?
   git branch _backup_$(date +%s)                       # pin current HEAD as a named ref
   

   Never run reset --hard, checkout, rebase, or gc until you've located the SHA you want back.

2. Find the lost SHA — reflog is the safety net. Every move of HEAD (and of each branch) is logged for ~90 days, even after reset --hard or branch deletion:

   git reflog                       # every HEAD move: HEAD@{0}, HEAD@{1}, ...
   git reflog show feature          # moves of one branch ref specifically
   git reflog --date=relative | grep -iE 'commit|reset|rebase|checkout'
   

   The entry just before the bad operation is your target (e.g. HEAD@{2} = "before the reset"). Copy its SHA.

3. Recover by creating a ref — never checkout a loose SHA bare. Pick the action by what you lost:

   Lost	Command	Note
   A deleted branch	git branch feature <sha>	<sha> from git reflog show feature or fsck
   Commits after a reset --hard	git reset --hard HEAD@{1}	moves current branch back; discards anything since
   Commits, but keep current work	git branch rescue <sha>	safe — inspect/cherry-pick from rescue, then delete it
   Detached-HEAD commits	git branch keep <sha> before you checkout away

Common Errors

• checkouting a loose SHA, making commits, then leaving — they're orphaned again. Always git branch <name> <sha> first; commit onto a real ref.
• reset --hard HEAD@{1} to "go back," wiping current uncommitted work. --hard discards the working tree. Stash or git branch _backup first (step 1); use git branch rescue instead when unsure.
• reflog is empty / "ambiguous argument". You're in a fresh clone or a different repo — reflog is per-local-clone and not pushed. Use git fsck --lost-found to find unreachable commits by content instead.
• reverting a merge commit fails or reverts the wrong side. Pass the parent: git revert -m 1 <merge-sha> (mainline = parent 1). Reverting a merge has its own re-merge gotcha; for shared history that's still safer than rewriting.
• stash pop hit a conflict and you assumed the stash was lost. A conflicted pop does not drop the stash — it's still in git stash list. Resolve, then git stash drop.
• Ran git gc / git reflog expire --expire=now --all and now the SHA is gone. Pruning deleted the unreachable objects. Recover the ref before any gc; check .git/lost-found/ and cloned mirrors.
• bisect mislabels because the build is broken at some midpoints. Have the script exit 125 (skip) for uncompilable commits so bisect routes around them instead of falsely marking bad.
• Forgot git bisect reset. You're left in detached HEAD on a midpoint commit, confusing later work. Reset returns you to the pre-bisect branch.
• Using reset to undo pushed commits, then force-pushing. Rewrites shared history and breaks teammates. On published commits use git revert; rewriting is rewrite-git-history's job, not a recovery.

Verify

Recovery is complete and correct when:

1. The recovered ref points at the right tree. git diff <known-good-sha> <recovered-ref> is empty (or shows exactly the intended delta) — confirms you grabbed the right SHA, not a neighbor.
2. The expected commits are reachable. git log --oneline <recovered-ref> shows the commits that were "lost," and git status is clean (no surprise staged/modified files).
3. A recovered stash applied cleanly. git stash show -p <sha> matches the work you expected; after apply the files contain the WIP changes.
4. An undo did what its audience requires. After revert: a new inverse commit exists and git log history is intact (nothing rewritten). After reset: git status shows the changes in the intended state (staged for --soft, unstaged for --mixed, gone for --hard).
5. Bisect named one culprit and cleaned up. Output ended with <sha> is the first bad commit, git show <sha> plausibly explains the regression, and git bisect reset returned HEAD to the starting branch (git status confirms the original branch, not detached).
6. Nothing was pruned mid-recovery. No git gc/reflog expire ran before the ref was secured; the _backup branch from step 1 still exists as a fallback.

Done = the recovered commits/branch/stash are on a named ref whose tree matches the known-good SHA (git diff empty), any undo matched its published-vs-local audience (revert vs reset mode), and bisect (if used) named the first bad commit with git bisect reset leaving HEAD on the original branch.