Pages

GIT: Chapter 12 — Troubleshooting and Recovery in Git

Chapter 12 — Troubleshooting and Recovery in Git

12.1 Introduction

Despite Git’s robustness, developers frequently encounter operational issues such as lost commits, merge conflicts, detached HEAD states, corrupted histories, and accidental deletions.

Git’s internal design ensures that most mistakes are recoverable if appropriate diagnostic techniques are applied.

This chapter focuses on:

  • Common Git problems

  • Diagnostic strategies

  • Recovery mechanisms

  • Preventive practices

12.2 Troubleshooting Philosophy in Git

Before attempting recovery:

  1. Stop destructive operations

  2. Inspect repository state

  3. Identify reference pointers

  4. Use reflog as historical audit

  5. Perform recovery conservatively

Key principle: Git rarely deletes data immediately.

12.3 Checking Repository State

Primary diagnostic command:

git status

Provides:

  • Current branch

  • Staged changes

  • Untracked files

  • Merge state

Used as first troubleshooting step.

12.4 Viewing Commit History

git log --oneline --graph --all

Displays:

  • Commit structure

  • Branch relationships

  • Integration history

Helps identify missing or misplaced commits.

12.5 Understanding Reflog

Reflog records reference movement.

git reflog

Tracks:

  • Checkouts

  • Resets

  • Rebases

  • Branch movements

Reflog is primary recovery tool.

12.6 Recovering Lost Commits

Scenario: Hard reset performed accidentally.

Recovery steps

  1. View reflog:

git reflog

  1. Identify lost commit hash

  2. Restore:

git reset --hard commit-hash

Commit restored.

12.7 Recovering Deleted Branch

git reflog
git checkout -b branch-name commit-hash

Branch recreated from historical pointer.

12.8 Detached HEAD Recovery

Symptoms:

  • HEAD points to commit

  • Not on branch

Check state:

git status

Recovery:

git checkout -b new-branch

Preserves commits.

12.9 Undoing Last Commit

Keep changes

git reset --soft HEAD~1

Unstage changes

git reset HEAD~1

Discard changes

git reset --hard HEAD~1

12.10 Fixing Wrong Commit Message

git commit --amend

Updates latest commit metadata.

12.11 Recovering Stashed Changes

List stashes:

git stash list

Apply:

git stash apply

If stash dropped accidentally:

git fsck --lost-found

May recover objects.

12.12 Resolving Merge Conflicts

Conflict markers:

<<<<<<< HEAD
=======
>>>>>>> branch

Resolution process:

  1. Edit file

  2. Remove markers

  3. Stage file

  4. Commit

git add file
git commit

12.13 Aborting Merge

git merge --abort

Restores pre-merge state.

12.14 Aborting Rebase

git rebase --abort

Returns repository to initial state.

12.15 Skipping Rebase Commit

git rebase --skip

Continues rebase ignoring problematic commit.

12.16 Fixing Push Rejection

Cause:

  • Remote ahead of local

Solution:

git pull --rebase
git push

Maintains linear history.

12.17 Handling Non-Fast-Forward Errors

Avoid force push unless necessary.

Safe method:

git pull
git push

Force push (last resort):

git push --force-with-lease

12.18 Removing File from Repository but Keeping Locally

git rm --cached file

Update .gitignore afterward.

12.19 Removing Sensitive Data

git filter-branch

Or modern tools (recommended):

  • History rewrite utilities

Requires force push.

12.20 Recovering Untracked File Deletion

Git cannot restore untracked files.

Preventive measures:

  • Use backups

  • Avoid aggressive clean

12.21 Diagnosing Large Repository Issues

Check size contributors:

git rev-list --objects --all

Identify large blobs.

12.22 Repairing Corrupted Repository

Check integrity:

git fsck

Reports:

  • Dangling objects

  • Missing objects

Often recoverable via reclone.

12.23 Cleaning Repository

git gc

Performs:

  • Garbage collection

  • Pack optimization

  • Object pruning

12.24 Recovering After Force Push

If overwritten:

  • Use collaborator clone

  • Fetch remote reflog (if available)

  • Restore commit

12.25 Debugging Hooks Failures

Symptoms:

  • Commit blocked

  • Push rejected

Check:

.git/hooks/

Review script output.

12.26 Troubleshooting Permission Issues

Common in cross-platform repos.

Fix:

git config core.filemode false

12.27 Preventive Practices

  • Frequent commits

  • Avoid long-lived branches

  • Use descriptive commit messages

  • Backup critical repositories

  • Protect main branch

  • Use CI gates

12.28 Emergency Recovery Checklist

  1. Stop operations

  2. Inspect status

  3. Review reflog

  4. Identify commit

  5. Create recovery branch

  6. Validate state

12.29 Mental Model for Recovery

Git recovery relies on:

Reflog + Objects + References

If object exists → recovery possible.

12.30 Summary

This chapter covered:

  • Diagnostic methodology

  • Reflog-based recovery

  • Branch and commit restoration

  • Merge and rebase troubleshooting

  • Push conflict resolution

  • Repository integrity checks

  • Preventive operational practices

Git’s architecture ensures high recoverability, provided developers understand reference tracking and object persistence.

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)