Troubleshooting and Recovery

Why this matters

The single biggest difference between someone who's nervous about Git and someone who's fluent is this: the fluent person knows that almost nothing in Git is truly unrecoverable, and knows the handful of commands that get them out of trouble. A "lost" commit after a bad reset --hard, a merge or rebase that went sideways, a bad commit pushed to a shared branch, a secret committed by accident, the alarming "detached HEAD" message — every one of these has a calm, standard fix. This module turns the fear off. Because the CI/CD and GitOps tracks make Git the source of truth for real infrastructure, being able to recover confidently isn't optional polish — it's an operational skill.

Concepts

The reflog is the master key

Recall from module 03: every time HEAD (or any branch) moves, Git appends to the reflog — a local journal of every position your refs have held, kept ~90 days. Because commits Git "removed" from a branch are still in the object database and still named in the reflog, git reflog is the first thing to reach for whenever something seems lost. The recovery pattern is almost always the same two steps: run git reflog to find the hash of the good state, then point a branch back at it (git reset --hard <hash>, or git branch rescue <hash> to be extra safe). Internalize this and most "I destroyed my work" moments become 30-second fixes.

Undoing changes: reset vs. revert vs. restore

Three commands "undo," and confusing them causes half of all Git accidents:

• git restore operates on files in the working tree/index — discard unstaged edits (git restore file) or unstage (git restore --staged file). It doesn't touch commits.
• git reset moves the current branch pointer to another commit (--soft keeps changes staged, --mixed/default unstages them, --hard also discards working-tree changes). It rewrites where the branch points — great locally, dangerous on shared history.
• git revert creates a new commit that undoes a previous commit's changes, leaving history intact. Because it adds rather than rewrites, it is the safe way to undo something that's already been pushed/shared — no golden-rule violation.

The rule of thumb: to undo unshared local work, reset; to undo shared (pushed) work, revert.

Undoing a bad merge or rebase

• A bad merge you haven't pushed: git reset --hard <pre-merge-commit> (find it in the reflog, or use ORIG_HEAD, which Git sets to the pre-merge position). A merge you have pushed: git revert -m 1 <merge-commit> — the -m 1 tells revert which parent is the "mainline" to keep.
• A bad rebase: because a rebase moved your branch, the pre-rebase tip is in the reflog (and ORIG_HEAD). git reset --hard ORIG_HEAD (or the reflog hash) puts the branch back exactly as it was before the rebase started. If you're still mid-rebase, git rebase --abort is even simpler.

The theme: reset-to-a-reflog-hash for unshared mistakes, revert for shared ones. ORIG_HEAD is a convenient shortcut Git sets before any "dangerous" operation (merge, rebase, reset) so you can jump back one step.

Fixing a bad push

You pushed something wrong to a remote. Two very different situations:

• The branch is yours alone (a feature/PR branch): fix locally (reset, amend, rebase) and git push --force-with-lease. Safe, because no one else builds on it.
• The branch is shared (main, develop): do not force-push and rewrite it — that's the golden-rule violation that wrecks everyone's clone (modules 03, 06). Instead, git revert the bad commit(s) and push the revert as a new commit. History stays intact and everyone just pulls a normal new commit that undoes the mistake.

Choosing correctly here is the mark of someone who understands shared vs. unshared history; the wrong choice on a shared branch turns a small mistake into a team-wide incident.

Un-committing a file (including a committed secret)

Two sub-cases, both common:

• Wrong file in the last commit, not yet pushed: git restore --staged it and git commit --amend, or git reset --soft HEAD~1 to redo the commit without it.
• A secret committed and pushed: removing it in a new commit stops it going forward but it remains in history — anyone can check out the old commit and read it. For a real leaked credential the first, non-negotiable step is to rotate the secret (assume it's compromised). To actually scrub it from all history you must rewrite every commit that contained it (git filter-repo, or the older BFG tool) and force-push — a heavy, coordinate-with-everyone operation. The lesson from module 01 stands: prevention (.gitignore before the first commit) beats cure enormously.

Detached HEAD: not broken, just unusual

When you git checkout <commit-hash> (or a tag), HEAD points directly at a commit instead of at a branch — "detached HEAD." This isn't an error; you're just viewing/working at a specific commit with no branch tracking your new commits. The danger is only this: any commits you make in detached HEAD are reachable only by the (moving) HEAD, so when you switch away, they become unreferenced and eventually garbage-collected. The fixes are simple:

• If you only wanted to look: git switch main (or any branch) to re-attach. Nothing lost, since you made no commits.
• If you made commits you want to keep: create a branch to anchor them before switching — git switch -c my-work (or git branch my-work) — which turns the detached commits into a normal branch.

And if you already switched away and lost detached commits — reflog, as always, has them.

Cleaning up: untracked files, stash, and a general recovery order

Two more everyday tools: git clean removes untracked files (use -n to preview first — it's destructive to files Git isn't tracking, and those aren't in any commit, so they're genuinely gone). git stash shelves your uncommitted changes so you can switch context, restoring them later with git stash pop. When something's wrong, a good general order is: stop and read the error and git status (Git usually tells you the fix), git reflog if commits seem lost, git reset/git revert/git restore as appropriate to the shared/unshared distinction, and --abort if you're mid-merge/rebase. Panic-typing more commands is what turns a recoverable mess into a worse one.

Command reference

Flag breakdown for git revert -m 1 abc1234:

• revert — create a new commit that reverses a prior commit's changes, without rewriting history.
• -m 1 — for a merge commit (which has two parents), specify which parent is the "mainline" to keep. -m 1 means "keep the first parent's line (usually main) and undo what the merge brought in from the second." Merge commits require -m because Git can't otherwise know which side to revert to.
• abc1234 — the merge commit to revert.

Flag breakdown for git reset --soft HEAD~1:

• reset — move the current branch pointer.
• --soft — move only the pointer; leave the index and working tree untouched, so the undone commit's changes stay staged, ready to recommit.
• HEAD~1 — one commit back; so this "un-commits" the latest commit while preserving its content.

Flag breakdown for git clean -fd (and why -n first):

• clean — remove untracked files (files Git isn't tracking, hence not in any commit — deletion is permanent).
• -n (--dry-run) — preview what would be deleted without deleting. Always run this first.
• -f (--force) — actually delete (Git requires -f as a safety confirmation).
• -d — also remove untracked directories, not just files.

Hands-on exercises

Run these in your WSL2 Ubuntu terminal. Each is a self-contained recovery drill — do them slowly and read the output.

1. Set up a repo with a few commits to break and fix:

   mkdir -p ~/learn-git/recovery && cd ~/learn-git/recovery
   git init
   for n in 1 2 3 4; do echo "line $n" >> file.txt; git add file.txt; git commit -m "Add line $n"; done
   git log --oneline
   

   Expect four commits.

2. Recover from a bad reset --hard (the core drill). Destroy two commits, then bring them back:

   git reset --hard HEAD~2
   git log --oneline
   

   Expect only two commits left — the last two look gone. Recover:

   git reflog
   git reset --hard HEAD@{1}
   git log --oneline
   cat file.txt
   

   Expect all four commits back and file.txt whole. HEAD@{1} was the position just before the reset (Concept 1). This is the pattern you'll reuse for almost every "lost work" situation.

3. Undo the last commit but keep its changes (redo it differently):

   git reset --soft HEAD~1
   git status
   

   Expect the fourth commit undone but its change still staged (Concept 2). Recommit it with a better message and confirm:

   git commit -m "Add line 4 (reworded)"
   git log --oneline
   

4. Undo a pushed commit the safe way with revert. Simulate a bad commit that's "already shared," then revert instead of resetting:

   echo "OOPS bad change" >> file.txt
   git commit -am "Bad change that shipped"
   git revert HEAD --no-edit
   git log --oneline
   cat file.txt
   

   Expect two new entries in the log — the bad commit and a "Revert..." commit — and file.txt no longer containing the OOPS line. History was preserved, not rewritten (Concept 2), which is exactly why this is safe on shared branches.

5. Undo a bad merge you haven't pushed, using ORIG_HEAD:

   git switch -c sidebranch
   echo "side work" > side.txt && git add side.txt && git commit -m "Side work"
   git switch main
   git merge sidebranch --no-ff -m "Merge sidebranch"
   git log --oneline
   

   Now pretend the merge was a mistake and rewind it:

   git reset --hard ORIG_HEAD
   git log --oneline
   ls
   

   Expect the merge undone and side.txt gone from main (Concept 3). Git set ORIG_HEAD to the pre-merge tip automatically.

6. Undo a bad rebase with the reflog. Create commits, rebase them, then restore the pre-rebase state:

   git switch -c rebase-victim
   echo "r1" >> r.txt && git add r.txt && git commit -m "r1"
   echo "r2" >> r.txt && git commit -am "r2"
   git rebase -i HEAD~2   # in the editor, squash the second into the first, save
   git log --oneline
   git reset --hard ORIG_HEAD
   git log --oneline
   

   Expect the squashed history after the rebase, then the original two commits restored after reset --hard ORIG_HEAD (Concept 3). The reflog would show the same pre-rebase hash if you preferred HEAD@{n}.

7. Diagnose and fix: detached HEAD. Enter it deliberately, make a commit, and rescue it:

   git switch main
   git checkout HEAD~2
   

   Expect Git's "You are in 'detached HEAD' state" message (Concept 5). Make a commit here:

   echo "work done while detached" > detached.txt
   git add detached.txt && git commit -m "Detached work"
   git log --oneline
   

   This commit is anchored only by HEAD. Before switching away, rescue it into a branch:

   git switch -c rescued-work
   git log --oneline
   

   Expect rescued-work now containing the detached commit — safe. Confirm re-attaching to a branch is what "fixes" detached HEAD:

   git switch main
   git status
   

   Expect a normal "On branch main" — no longer detached.

8. Recover a detached commit you forgot to rescue (reflog to the rescue). Re-enter detached HEAD, commit, then switch away without making a branch:

   git checkout HEAD~1
   echo "orphan" > orphan.txt && git add orphan.txt && git commit -m "Orphaned commit"
   git switch main    # Git warns you're leaving a commit behind
   git log --oneline   # the orphan is not here
   

   The orphaned commit isn't on any branch. Find and rescue it:

   git reflog
   git branch recovered-orphan HEAD@{1}
   git log --oneline recovered-orphan
   

   Expect the orphaned commit recovered onto a branch (Concept 1). Even "leaving behind" a detached commit is recoverable while it's in the reflog.

9. Un-commit a file that shouldn't have been committed. Commit a stray file, then remove it from the last commit without losing the others:

   git switch main
   echo "temp junk" > junk.tmp
   echo "real change" >> file.txt
   git add junk.tmp file.txt
   git commit -m "Add real change (and junk by mistake)"
   

   Now surgically drop junk.tmp from that commit:

   git rm --cached junk.tmp
   git commit --amend --no-edit
   git show --stat HEAD
   git status
   

   Expect the amended commit to include only file.txt, junk.tmp still on disk but untracked (Concept 4). (If it were a real secret and already pushed, you'd additionally rotate it and consider history scrubbing.)

10. Preview-then-clean untracked files safely:

    echo "junk1" > a.tmp && echo "junk2" > b.tmp && mkdir tmpdir && echo x > tmpdir/c.tmp
    git clean -n -d
    

    Expect a preview list of what would be removed — nothing deleted yet (Concept 6). Now actually remove them:

    git clean -fd
    git status
    ls
    

    Expect the .tmp files and tmpdir gone. Note these were never committed, so unlike everything else in this module they're not recoverable — which is exactly why you preview with -n first.

11. Use stash to escape "I need to switch branches but have uncommitted work":

    echo "half-done edit" >> file.txt
    git stash
    git status
    git switch rescued-work
    git switch main
    git stash pop
    git status
    

    Expect git stash to give you a clean tree (letting you switch freely), and git stash pop to restore your half-done edit afterward (Concept 6).

Independent challenge

No commands given — this challenge deliberately draws on the reflog and reset from module 03, the shared-vs-unshared golden rule from modules 03/04/06, and the recovery tools here.

Task: Stage and then fully recover from a realistic "bad day" without losing any wanted work. On a repo with several commits, do all of the following and recover cleanly from each: (1) blow away several commits with a reset --hard to the wrong place and restore them via the reflog; (2) create a commit in detached HEAD, switch away so it looks lost, and rescue it onto a branch; (3) simulate a bad commit that has "already been pushed to a shared main" and undo it without rewriting history, then explain why you chose that method over reset and what would have gone wrong for teammates if you'd reset-and-force-pushed instead. Finish by producing a clean git log and being able to state, for each of the three recoveries, which command class (reflog+reset vs. revert vs. branch-from-hash) you used and why it was the right one for that situation.

Common mistakes & troubleshooting

• Force-pushing to "fix" a bad commit on a shared branch. This rewrites history everyone else has and turns a small mistake into a team incident. On shared branches, git revert (add an undo commit) instead of resetting and force-pushing.
• Panicking and typing more commands after a scary message. Stop. Read the error and git status — Git usually names the exact fix. Then git reflog if commits seem lost. Frantic extra commands are what actually cause data loss.
• Assuming reset --hard destroyed committed work. It almost never does — the old commits sit in the object database and the reflog. Look in git reflog before assuming anything is gone.
• Treating a committed secret as "removed" once you delete/.gitignore it. It's still in history. Rotate the credential immediately; scrubbing history (git filter-repo) is a heavy, coordinate-with-everyone operation and still doesn't un-leak what may already be cloned.
• Fearing detached HEAD as "broken." It's just HEAD pointing at a commit instead of a branch. To keep commits made there, git switch -c <name> before switching away; to just look around, git switch <branch> to re-attach.
• Running git clean -f without -n first. Untracked files aren't in any commit, so clean deletes them for good. Always git clean -n (or -nd) to preview, then commit to the real removal.
• Confusing reset, revert, and restore. restore = files, no commit change. reset = move the branch pointer (rewrites, local). revert = new undo commit (safe, shared). Pick by whether the target is a file vs. a commit, and shared vs. unshared.

Checkpoint quiz

Write down your answer to each question before expanding it — checking without attempting first is the single easiest way to fool yourself into thinking you've learned this.

Next

Continue to 08-capstone-project to put the entire track together — simulate a realistic multi-week collaboration with branches, a real conflict, an interactive-rebase cleanup, and a reflog recovery, ending in a clean, readable history.