Module 11 Project C: Troubleshooting a 'Broken' Repository

Even the best developers get stuck. Sometimes Git gives you a cryptic error message like "You are in a detached HEAD state" or "index.lock exists."

In this project, we learn the "First Aid" techniques for fixing the most common Git disasters.

Case 1: The Detached HEAD

The Symptom: You checked out a specific commit ID and now Git says: "You are in 'detached HEAD' state." Any commits you make now will be lost if you switch branches.

The Fix:

# Don't panic. Just create a new branch from this point!
git switch -c recovered-work

Now you are back on a safe, named branch.

Case 2: The "Broken" Rebase

The Symptom: You started a rebase, got 20 conflicts, and now your terminal prompt looks weird (e.g., (main|REBASE 1/5)).

The Fix:

Option A (Escape): If it’s too messy, just undo the whole thing: git rebase --abort.
Option B (The nuclear option): If you are really stuck, use the reflog (Module 10) to reset your branch back to exactly where it was before the rebase started.

Case 3: Accidental Large File Commit

The Symptom: You accidentally committed a 500MB video file. Even if you delete it in a new commit, Git still "remembers" it in history, making your repo huge and slow to push.

The Fix: You must rewrite history to "Pretend the file never existed."

# Use a tool like BFG Repo-Cleaner or the modern 'git filter-repo'
# (Nuclear method - use with caution!)
git filter-branch --tree-filter 'rm -f path/to/giant-video.mp4' HEAD

Case 4: "Index.lock" Error

The Symptom: error: another git process seems to be running in this repository...

The Fix: Sometimes Git crashes and leaves a "Lock" file behind. If you are sure no other Git command is running:

rm .git/index.lock

graph TD
    Error["Git Error Message"] --> ID["Identify Symptom"]
    ID -- "Detached HEAD" --> B1["git switch -c new-branch"]
    ID -- "Stuck Rebase" --> B2["git rebase --abort"]
    ID -- "Huge Files" --> B3["git filter-branch / BFG"]
    ID -- "Locked Repo" --> B4["rm .git/index.lock"]

Project Exercise (Hands-on Troubleshooting)

Goal: Break and Fix.

Create a "Broken" state: git checkout <some-old-commit-id>. Use git status to see the "Detached HEAD" warning.
Fix it: create a branch called stable-point.
Try to git add a file while manually creating a blank file at .git/index.lock. See the error.
Fix it: delete the lock file.
Use git reflog to find the exact point before you "Broke" the repo and jump back to it.

Observation: You'll find that "Broken" is a relative term in Git. Almost everything can be undone or recovered as long as you understand how Git stores its data.

Summary

In this project, we established:

Most "Broken" states have simple, standard fixes.
git rebase --abort and git switch -c are your most powerful escape tools.
Large files must be removed from history, not just the current commit.
The reflog remains the ultimate backup for all troubleshooting.

Module Complete! You are now the person your teammates will come to when their Git is broken.

Final Module: It's time to prove everything you've learned. Welcome to Module 12: Capstone Project.