Problem troubleshooting method

In Git usage, encountering issues is common. From code conflicts to branch management anomalies, from messy commit histories to remote repository synchronization failures, efficient troubleshooting skills directly impact development efficiency. Below is a systematic troubleshooting approach for common Git problems, explained with specific scenarios and operational examples.

Basic Local Repository Troubleshooting

Abnormal Working Directory File Status
When git status shows a large number of untracked or modified files:

# Verify if ignore rules are effective
git check-ignore -v path/to/file

# Clean up untracked files (risky operation)
git clean -nfd  # Preview first
git clean -fd   # Execute

Abnormal Commit History
Use git log with the following parameters to pinpoint issues:

# Display a graphical branch topology
git log --graph --oneline --all

# Search for commits containing a specific string
git log -S "missing_function()" --patch

Branch and Merge Conflict Handling

Failed Branch Switching
When encountering error: Your local changes to the following files would be overwritten by checkout:

# Option 1: Stash current changes
git stash
git checkout target-branch
git stash pop

# Option 2: Create a temporary branch
git checkout -b temp-branch

Merge Conflict Resolution Process

1. Use git status to locate conflicting files.
2. Resolve conflict markers (<<<<<<<, =======, >>>>>>>) in the editor.
3. For each resolved file, execute:

git add resolved-file.js

4. Complete the merge:

git commit  # Do not modify the auto-generated commit message

Remote Repository Synchronization Issues

Push Rejected
When git push returns rejected - non-fast-forward error:

# First pull remote changes (creates a merge commit)
git pull origin branch-name

# Or use rebase (recommended)
git pull --rebase origin branch-name
git push

Authentication Failure Handling
For SSH connection failures, check:

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

# Check remote URL type
git remote -v
# Switch URL type if necessary
git remote set-url origin git@github.com:user/repo.git

Advanced Diagnostic Tools

Binary Search to Locate Faulty Commits

git bisect start
git bisect bad          # Mark current as bad
git bisect good v1.0    # Mark known good version
# Continue marking good/bad based on test results
git bisect reset        # Reset after completion

Rewriting History
Amend the most recent commit:

git commit --amend -m "New commit message"

Interactive rebase (modify multiple commits):

git rebase -i HEAD~3   # Edit the last 3 commits

Repository Corruption Repair

Filesystem-Level Checks

# Check repository integrity
git fsck --full

# Recover lost objects
git cat-file -p lost-hash > recovered-file.txt

Resetting Repository State
When .git directory has issues:

# Re-clone from remote (last resort)
git clone --mirror git@github.com:user/repo.git temp-clone
cd original-repo
git remote update
git reset --hard origin/main

Performance Optimization

Cleaning Up Large Historical Files
Use BFG tool or native commands:

# Find top 10 largest files
git verify-pack -v .git/objects/pack/*.idx | sort -k 3 -n | tail -10

# Rewrite history (permanently delete large files)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch path/to/large-file" \
  --prune-empty --tag-name-filter cat -- --all

Repository Compression

git gc --aggressive --prune=now
git repack -a -d --depth=250 --window=250

Hook Script Debugging

Troubleshooting pre-commit Failures
Temporarily bypass hooks:

git commit --no-verify -m "Emergency commit"

Check hook execution environment:

# Add at the beginning of the hook script
env > /tmp/git-hook-env.log
echo "$@" >> /tmp/git-hook-args.log

Cross-Platform Compatibility Issues

Line Ending Issues

# Standardize line ending handling
git config --global core.autocrlf input  # Linux/Mac
git config --global core.autocrlf true   # Windows

# Fix existing repository
git rm --cached -r .
git reset --hard

Filename Case Sensitivity Issues

# Clear cache after renaming files
git mv File.js file.js  # Actually a combination of two commands
git config core.ignorecase false