git-troubleshooting

SKILL.md

Git Troubleshooting Skill

This skill provides comprehensive guidance on diagnosing and resolving git issues, recovering from mistakes, fixing corrupted repositories, and handling common error scenarios.

When to Use

Activate this skill when:

Encountering git error messages

Recovering lost commits or branches

Fixing corrupted repositories

Resolving detached HEAD state

Handling botched merges or rebases

Diagnosing repository issues

Recovering from force push

Fixing authentication problems

Recovering Lost Commits

Using Reflog
# View reflog (local history of HEAD)
git reflog

# View reflog for specific branch
git reflog show branch-name

# Output example:
# abc123 HEAD@{0}: commit: feat: add authentication
# def456 HEAD@{1}: commit: fix: resolve bug
# ghi789 HEAD@{2}: reset: moving to HEAD~1

# Recover lost commit
git cherry-pick abc123

# Or create branch from lost commit
git branch recovered-branch abc123

# Or reset to lost commit
git reset --hard abc123

Finding Dangling Commits

# Find all unreachable objects
git fsck --lost-found

# Output:
# dangling commit abc123
# dangling blob def456

# View dangling commit
git show abc123

# Recover dangling commit
git branch recovered abc123

# Or merge it
git merge abc123

Recovering Deleted Branch

# Find branch commit in reflog
git reflog

# Look for branch deletion:
# abc123 HEAD@{5}: checkout: moving from feature-branch to main

# Recreate branch
git branch feature-branch abc123

# Or if branch was merged before deletion
git log --all --oneline | grep "feature"
git branch feature-branch def456

Recovering After Reset

# After accidental reset --hard
git reflog

# Find commit before reset:
# abc123 HEAD@{0}: reset: moving to HEAD~5
# def456 HEAD@{1}: commit: last good commit

# Restore to previous state
git reset --hard def456

# Or create recovery branch
git branch recovery def456

Resolving Detached HEAD

Understanding Detached HEAD

# Detached HEAD state occurs when:
git checkout abc123
git checkout v1.0.0
git checkout origin/main

# HEAD is not attached to any branch

Recovering from Detached HEAD

# Check current state
git status
# HEAD detached at abc123

# Option 1: Create new branch
git checkout -b new-branch-name

# Option 2: Return to previous branch
git checkout main

# Option 3: Reattach HEAD to branch
git checkout -b temp-branch
git checkout main
git merge temp-branch

# If you made commits in detached HEAD:
git reflog
# Find the commits
git branch recovery-branch abc123

Preventing Detached HEAD

# Instead of checking out tag directly
git checkout -b release-v1.0 v1.0.0

# Instead of checking out remote branch
git checkout -b local-feature origin/feature-branch

# Check if HEAD is detached
git symbolic-ref -q HEAD && echo "attached" || echo "detached"

Fixing Merge Conflicts

Understanding Conflict Markers

<<<<<<< HEAD (Current Change)
int result = add(a, b);
||||||| merged common ancestors (Base)
int result = sum(a, b);
=======
int sum = calculate(a, b);
>>>>>>> feature-branch (Incoming Change)

Basic Conflict Resolution

# When merge conflict occurs
git status
# both modified: file.go

# View conflict
cat file.go

# Option 1: Keep ours (current branch)
git checkout --ours file.go
git add file.go

# Option 2: Keep theirs (incoming branch)
git checkout --theirs file.go
git add file.go

# Option 3: Manual resolution
# Edit file.go to resolve conflicts
git add file.go

# Complete merge
git commit

Aborting Operations

# Abort merge
git merge --abort

# Abort rebase
git rebase --abort

# Abort cherry-pick
git cherry-pick --abort

# Abort revert
git revert --abort

# Abort am (apply mailbox)
git am --abort

Complex Conflict Resolution

# Use merge tool
git mergetool

# View three-way diff
git diff --ours
git diff --theirs
git diff --base

# Show conflicts with context
git diff --check

# List conflicted files
git diff --name-only --diff-filter=U

# After resolving all conflicts
git add .
git commit

Fixing Botched Rebase

Recovering from Failed Rebase

# Abort current rebase
git rebase --abort

# Find state before rebase
git reflog
# abc123 HEAD@{1}: rebase: checkout main

# Return to pre-rebase state
git reset --hard HEAD@{1}

# Alternative: use ORIG_HEAD
git reset --hard ORIG_HEAD

Rebase Conflicts

# During rebase conflict
git status
# both modified: file.go

# Resolve conflicts
# Edit file.go
git add file.go
git rebase --continue

# Skip problematic commit
git rebase --skip

# Edit commit during rebase
git commit --amend
git rebase --continue

Rebase onto Wrong Branch

# Find original branch point
git reflog

# Reset to before rebase
git reset --hard HEAD@{5}

# Rebase onto correct branch
git rebase correct-branch

Repository Corruption

Detecting Corruption

# Check repository integrity
git fsck --full

# Check connectivity
git fsck --connectivity-only

# Verify pack files
git verify-pack -v .git/objects/pack/*.idx

Fixing Corrupted Objects

# Remove corrupted object
rm .git/objects/ab/cd1234...

# Try to recover from remote
git fetch origin

# Rebuild object database
git gc --prune=now

# Aggressive cleanup
git gc --aggressive --prune=now

Fixing Index Corruption

# Remove corrupted index
rm .git/index

# Rebuild index
git reset

# Or reset to HEAD
git reset --hard HEAD

Recovering from Bad Pack File

# Unpack corrupted pack
git unpack-objects < .git/objects/pack/pack-*.pack

# Remove corrupted pack
rm .git/objects/pack/pack-*

# Repack repository
git repack -a -d

# Verify integrity
git fsck --full

Fixing References

Corrupted Branch References

# View all references
git show-ref

# Manual reference fix
echo "abc123def456" > .git/refs/heads/branch-name

# Or use update-ref
git update-ref refs/heads/branch-name abc123

# Delete corrupted reference
git update-ref -d refs/heads/bad-branch

Fixing HEAD Reference

# HEAD is corrupted or missing
echo "ref: refs/heads/main" > .git/HEAD

# Or point to specific commit
echo "abc123def456" > .git/HEAD

# Verify HEAD
git symbolic-ref HEAD

Pruning Stale References

# Remove stale remote references
git remote prune origin

# Remove all stale references
git fetch --prune

# Remove all remote branches that no longer exist
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -D

Undoing Changes

Undo Last Commit (Keep Changes)

# Soft reset (changes staged)
git reset --soft HEAD~1

# Mixed reset (changes unstaged)
git reset HEAD~1

Undo Last Commit (Discard Changes)

# Hard reset
git reset --hard HEAD~1

# Can still recover via reflog
git reflog
git reset --hard HEAD@{1}

Undo Multiple Commits

# Reset to specific commit
git reset --hard abc123

# Revert multiple commits (creates new commits)
git revert HEAD~3..HEAD

# Interactive rebase to remove commits
git rebase -i HEAD~5
# Mark commits with 'drop' or delete lines

Undo Changes to File

# Discard uncommitted changes
git checkout -- file.go

# Or in Git 2.23+
git restore file.go

# Discard staged changes
git reset HEAD file.go
git restore file.go

# Or in Git 2.23+
git restore --staged file.go
git restore file.go

# Restore file from specific commit
git checkout abc123 -- file.go

Undo Public Commits

# Never use reset on public commits
# Use revert instead
git revert HEAD
git revert abc123
git revert abc123..def456

# Revert merge commit
git revert -m 1 merge-commit-hash

Handling Force Push Issues

Recovering After Force Push

# If you were force pushed over
git reflog
# abc123 HEAD@{1}: pull: Fast-forward

# Recover your commits
git reset --hard HEAD@{1}

# Create backup branch
git branch backup-branch

# Merge with force-pushed branch
git pull origin main
git merge backup-branch

Preventing Force Push Damage

# Always fetch before force push
git fetch origin

# View what would be lost
git log origin/main..HEAD

# Force push with lease (safer)
git push --force-with-lease origin main

# Configure push protection
git config --global push.default simple

Large File Issues

Finding Large Files

# Find large files in history
git rev-list --objects --all | \
  git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
  awk '/^blob/ {print substr($0,6)}' | \
  sort --numeric-sort --key=2 | \
  tail -10

# Verify current large files
git ls-files | xargs ls -lh | sort -k 5 -h -r | head -20

Removing Large Files

# Using git-filter-repo (recommended)
git filter-repo --path large-file.bin --invert-paths

# Using BFG
bfg --strip-blobs-bigger-than 100M

# After removal
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force origin main

Preventing Large Files

# Configure pre-commit hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
if git diff --cached --name-only | xargs du -h | awk '$1 ~ /M$|G$/' | grep .; then
    echo "Error: Large file detected"
    exit 1
fi
EOF

chmod +x .git/hooks/pre-commit

Authentication Issues

SSH Key Problems

# Test SSH connection
ssh -T git@github.com

# Check SSH key
ls -la ~/.ssh

# Generate new SSH key
ssh-keygen -t ed25519 -C "email@example.com"

# Add key to ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# Configure SSH
cat > ~/.ssh/config << EOF
Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519
EOF

HTTPS Authentication

# Cache credentials
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

# Or use store (less secure)
git config --global credential.helper store

# Update remote URL
git remote set-url origin https://github.com/user/repo.git

# Use personal access token
git clone https://TOKEN@github.com/user/repo.git

Permission Denied

# Check remote URL
git remote -v

# Change to SSH
git remote set-url origin git@github.com:user/repo.git

# Change to HTTPS
git remote set-url origin https://github.com/user/repo.git

# Verify permissions
ls -la .git/
chmod -R u+rw .git/

Submodule Issues

Submodule Not Initialized

# Initialize submodules
git submodule init
git submodule update

# Or in one command
git submodule update --init --recursive

Detached HEAD in Submodule

# Enter submodule
cd submodule-dir

# Create branch
git checkout -b main

# Or attach to existing branch
git checkout main
git pull origin main

# Update parent repo
cd ..
git add submodule-dir
git commit -m "chore: update submodule"

Submodule Conflicts

# Check submodule status
git submodule status

# Reset submodule
git submodule update --init --force

# Remove and re-add submodule
git submodule deinit -f path/to/submodule
git rm -f path/to/submodule
git submodule add <url> path/to/submodule

Performance Issues

Slow Operations

# Optimize repository
git gc --aggressive

# Repack efficiently
git repack -a -d --depth=250 --window=250

# Prune old objects
git prune --expire now

# Clean up unnecessary files
git clean -fdx

Large Repository

# Shallow clone
git clone --depth 1 <url>

# Fetch only one branch
git clone --single-branch --branch main <url>

# Partial clone
git clone --filter=blob:none <url>

# Sparse checkout
git sparse-checkout init --cone
git sparse-checkout set folder1 folder2

Memory Issues

# Increase memory limits
git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"

# Disable delta compression temporarily
git config --global pack.compression 0

Common Error Messages

"fatal: refusing to merge unrelated histories"

# Allow merging unrelated histories
git pull origin main --allow-unrelated-histories

"fatal: not a git repository"

# Reinitialize repository
git init

# Or check if .git directory exists
ls -la .git

# Restore from backup if corrupted

"error: Your local changes would be overwritten"

# Stash changes
git stash
git pull
git stash pop

# Or discard changes
git reset --hard HEAD
git pull

"error: failed to push some refs"

# Fetch and merge first
git pull origin main

# Or rebase
git pull --rebase origin main

# Force push (dangerous)
git push --force origin main

# Safer force push
git push --force-with-lease origin main

"fatal: unable to access: SSL certificate problem"

# Disable SSL verification (not recommended)
git config --global http.sslVerify false

# Or update SSL certificates
git config --global http.sslCAInfo /path/to/cacert.pem

Diagnostic Commands

Repository Health Check

# Full integrity check
git fsck --full --strict

# Check connectivity
git fsck --connectivity-only

# Verify objects
git verify-pack -v .git/objects/pack/*.idx

# Check reflog
git reflog expire --dry-run --all

# Analyze repository
git count-objects -vH

Debug Information

# Enable verbose logging
GIT_TRACE=1 git status
GIT_TRACE=1 git pull

# Debug specific operations
GIT_TRACE_PACKET=1 git fetch
GIT_TRACE_PERFORMANCE=1 git diff
GIT_CURL_VERBOSE=1 git push

# Configuration debugging
git config --list --show-origin
git config --list --show-scope

Prevention Strategies

Regular Backups: Create backup branches before risky operations

Use Reflog: Reflog is your safety net, keep it clean

Enable Rerere: Reuse recorded conflict resolutions

Protect Branches: Use branch protection rules

Pre-commit Hooks: Validate commits before they're made

Regular Maintenance: Run git gc periodically

Test Before Force Push: Always verify with --dry-run

Communication: Inform team about disruptive operations

Learn Git Internals: Understanding how git works prevents issues

Keep Git Updated: Use latest stable version

Resources

Additional troubleshooting guides are available in the assets/ directory:

troubleshooting/ - Step-by-step recovery procedures

scripts/ - Diagnostic and recovery scripts

checklists/ - Problem diagnosis workflows

See references/ directory for:

Git error message database

Recovery procedure documentation

Git internal structure guides

Common pitfall documentation