Git Troubleshooting Skill

Git 故障排查技巧

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

本技巧提供关于诊断和解决Git问题、从操作失误中恢复、修复损坏的仓库以及处理常见错误场景的全面指南。

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

在以下场景中激活本技巧：

遇到Git错误提示
恢复丢失的提交或分支
修复损坏的代码仓库
解决分离HEAD状态
处理失败的合并或变基操作
诊断仓库问题
从强制推送操作中恢复
修复身份验证问题

Recovering Lost Commits

恢复丢失的提交

Using Reflog

使用Reflog

bash

undefined

bash

undefined

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

undefined

git reset --hard abc123

undefined

Finding Dangling Commits

查找悬挂提交

bash

undefined

bash

undefined

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

undefined

git merge abc123

undefined

Recovering Deleted Branch

恢复已删除的分支

bash

undefined

bash

undefined

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

undefined

git log --all --oneline | grep "feature" git branch feature-branch def456

undefined

Recovering After Reset

重置操作后的恢复

bash

undefined

bash

undefined

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

undefined

git branch recovery def456

undefined

Resolving Detached HEAD

解决分离HEAD问题

Understanding Detached HEAD

理解分离HEAD

bash

undefined

bash

undefined

Detached HEAD state occurs when:

git checkout abc123 git checkout v1.0.0 git checkout origin/main

HEAD is not attached to any branch

undefined

undefined

Recovering from Detached HEAD

从分离HEAD状态恢复

bash

undefined

bash

undefined

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

undefined

git branch recovery-branch abc123

undefined

Preventing Detached HEAD

预防分离HEAD问题

bash

undefined

bash

undefined

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"

undefined

git symbolic-ref -q HEAD && echo "attached" || echo "detached"

undefined

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)

<<<<<<< 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

基础冲突解决

bash

undefined

bash

undefined

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

undefined

git commit

undefined

Aborting Operations

中止操作

bash

undefined

bash

undefined

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

undefined

git am --abort

undefined

Complex Conflict Resolution

复杂冲突解决

bash

undefined

bash

undefined

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

undefined

git add . git commit

undefined

Fixing Botched Rebase

修复失败的变基操作

Recovering from Failed Rebase

从失败的变基中恢复

bash

undefined

bash

undefined

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

undefined

git reset --hard ORIG_HEAD

undefined

Rebase Conflicts

变基冲突

bash

undefined

bash

undefined

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

undefined

git commit --amend git rebase --continue

undefined

Rebase onto Wrong Branch

变基到错误分支

bash

undefined

bash

undefined

Find original branch point

git reflog

Reset to before rebase

git reset --hard HEAD@{5}

Rebase onto correct branch

git rebase correct-branch

undefined

git rebase correct-branch

undefined

Repository Corruption

仓库损坏问题

Detecting Corruption

检测损坏

bash

undefined

bash

undefined

Check repository integrity

git fsck --full

Check connectivity

git fsck --connectivity-only

Verify pack files

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

undefined

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

undefined

Fixing Corrupted Objects

修复损坏的对象

bash

undefined

bash

undefined

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

undefined

git gc --aggressive --prune=now

undefined

Fixing Index Corruption

修复索引损坏

bash

undefined

bash

undefined

Remove corrupted index

rm .git/index

Rebuild index

git reset

Or reset to HEAD

git reset --hard HEAD

undefined

git reset --hard HEAD

undefined

Recovering from Bad Pack File

从损坏的Pack文件中恢复

bash

undefined

bash

undefined

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

undefined

git fsck --full

undefined

Fixing References

修复引用问题

Corrupted Branch References

损坏的分支引用

bash

undefined

bash

undefined

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

undefined

git update-ref -d refs/heads/bad-branch

undefined

Fixing HEAD Reference

修复HEAD引用

bash

undefined

bash

undefined

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

undefined

git symbolic-ref HEAD

undefined

Pruning Stale References

清理过时引用

bash

undefined

bash

undefined

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

undefined

git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -D

undefined

Undoing Changes

撤销变更

Undo Last Commit (Keep Changes)

撤销最近一次提交（保留变更）

bash

undefined

bash

undefined

Soft reset (changes staged)

git reset --soft HEAD~1

Mixed reset (changes unstaged)

git reset HEAD~1

undefined

git reset HEAD~1

undefined

Undo Last Commit (Discard Changes)

撤销最近一次提交（丢弃变更）

bash

undefined

bash

undefined

Hard reset

git reset --hard HEAD~1

Can still recover via reflog

git reflog git reset --hard HEAD@{1}

undefined

git reflog git reset --hard HEAD@{1}

undefined

Undo Multiple Commits

撤销多次提交

bash

undefined

bash

undefined

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

undefined

undefined

Undo Changes to File

撤销文件的变更

bash

undefined

bash

undefined

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

undefined

git checkout abc123 -- file.go

undefined

Undo Public Commits

撤销已公开的提交

bash

undefined

bash

undefined

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

undefined

git revert -m 1 merge-commit-hash

undefined

Handling Force Push Issues

处理强制推送问题

Recovering After Force Push

强制推送后的恢复

bash

undefined

bash

undefined

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

undefined

git pull origin main git merge backup-branch

undefined

Preventing Force Push Damage

预防强制推送造成的损失

bash

undefined

bash

undefined

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

undefined

git config --global push.default simple

undefined

Large File Issues

大文件问题

Finding Large Files

查找大文件

bash

undefined

bash

undefined

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

undefined

git ls-files | xargs ls -lh | sort -k 5 -h -r | head -20

undefined

Removing Large Files

移除大文件

bash

undefined

bash

undefined

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

undefined

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

undefined

Preventing Large Files

预防大文件提交

bash

undefined

bash

undefined

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

undefined

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

undefined

Authentication Issues

身份验证问题

SSH Key Problems

SSH密钥问题

bash

undefined

bash

undefined

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

undefined

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

undefined

HTTPS Authentication

HTTPS身份验证

bash

undefined

bash

undefined

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

undefined

git clone https://TOKEN@github.com/user/repo.git

undefined

Permission Denied

权限被拒绝

bash

undefined

bash

undefined

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/

undefined

ls -la .git/ chmod -R u+rw .git/

undefined

Submodule Issues

子模块问题

Submodule Not Initialized

子模块未初始化

bash

undefined

bash

undefined

Initialize submodules

git submodule init git submodule update

Or in one command

git submodule update --init --recursive

undefined

git submodule update --init --recursive

undefined

Detached HEAD in Submodule

子模块出现分离HEAD

bash

undefined

bash

undefined

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"

undefined

cd .. git add submodule-dir git commit -m "chore: update submodule"

undefined

Submodule Conflicts

子模块冲突

bash

undefined

bash

undefined

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

undefined

git submodule deinit -f path/to/submodule git rm -f path/to/submodule git submodule add <url> path/to/submodule

undefined

Performance Issues

性能问题

Slow Operations

操作缓慢

bash

undefined

bash

undefined

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

undefined

git clean -fdx

undefined

Large Repository

大型仓库处理

bash

undefined

bash

undefined

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

undefined

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

undefined

Memory Issues

内存问题

bash

undefined

bash

undefined

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

undefined

git config --global pack.compression 0

undefined

Common Error Messages

常见错误提示

"fatal: refusing to merge unrelated histories"

bash

undefined

bash

undefined

Allow merging unrelated histories

git pull origin main --allow-unrelated-histories

undefined

git pull origin main --allow-unrelated-histories

undefined

"fatal: not a git repository"

bash

undefined

bash

undefined

Reinitialize repository

git init

Or check if .git directory exists

ls -la .git

Restore from backup if corrupted

undefined

undefined

"error: Your local changes would be overwritten"

bash

undefined

bash

undefined

Stash changes

git stash git pull git stash pop

Or discard changes

git reset --hard HEAD git pull

undefined

git reset --hard HEAD git pull

undefined

"error: failed to push some refs"

bash

undefined

bash

undefined

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

undefined

git push --force-with-lease origin main

undefined

"fatal: unable to access: SSL certificate problem"

bash

undefined

bash

undefined

Disable SSL verification (not recommended)

git config --global http.sslVerify false

Or update SSL certificates

git config --global http.sslCAInfo /path/to/cacert.pem

undefined

git config --global http.sslCAInfo /path/to/cacert.pem

undefined

Diagnostic Commands

诊断命令

Repository Health Check

仓库健康检查

bash

undefined

bash

undefined

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

undefined

git count-objects -vH

undefined

Debug Information

调试信息

bash

undefined

bash

undefined

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

undefined

git config --list --show-origin git config --list --show-scope

undefined

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

定期备份： 在执行风险操作前创建备份分支
使用Reflog： Reflog是你的安全网，注意保持其整洁
启用Rerere： 复用已记录的冲突解决结果
分支保护： 使用分支保护规则
Pre-commit钩子： 在提交完成前进行校验
定期维护： 定期执行
```
git gc
```
进行仓库优化
强制推送前测试： 始终使用
```
--dry-run
```
验证操作
团队沟通： 告知团队成员可能造成影响的操作
学习Git内部原理： 理解Git的运行机制可以避免很多问题
保持Git版本更新： 使用最新的稳定版本

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

assets/

目录下提供了更多故障排查指南：

```
troubleshooting/
```
- 分步恢复流程
```
scripts/
```
- 诊断和恢复脚本
```
checklists/
```
- 问题诊断工作流

请查看

references/

目录获取：

Git错误提示数据库
恢复流程文档
Git内部结构指南
常见陷阱文档

git-troubleshooting

Original

Translation

Git Troubleshooting Skill

Git 故障排查技巧

When to Use

适用场景

Recovering Lost Commits

恢复丢失的提交

Using Reflog

使用Reflog

View reflog (local history of HEAD)

View reflog (local history of HEAD)

View reflog for specific branch

View reflog for specific branch

Output example:

Output example:

abc123 HEAD@{0}: commit: feat: add authentication

abc123 HEAD@{0}: commit: feat: add authentication

def456 HEAD@{1}: commit: fix: resolve bug

def456 HEAD@{1}: commit: fix: resolve bug

ghi789 HEAD@{2}: reset: moving to HEAD~1

ghi789 HEAD@{2}: reset: moving to HEAD~1

Recover lost commit

Recover lost commit

Or create branch from lost commit

Or create branch from lost commit

Or reset to lost commit

Or reset to lost commit

Finding Dangling Commits

查找悬挂提交

Find all unreachable objects

Find all unreachable objects

Output:

Output:

dangling commit abc123

dangling commit abc123

dangling blob def456

dangling blob def456

View dangling commit

View dangling commit

Recover dangling commit

Recover dangling commit

Or merge it

Or merge it

Recovering Deleted Branch

恢复已删除的分支

Find branch commit in reflog

Find branch commit in reflog

Look for branch deletion:

Look for branch deletion:

abc123 HEAD@{5}: checkout: moving from feature-branch to main

abc123 HEAD@{5}: checkout: moving from feature-branch to main

Recreate branch

Recreate branch

Or if branch was merged before deletion

Or if branch was merged before deletion

Recovering After Reset

重置操作后的恢复

After accidental reset --hard

After accidental reset --hard

Find commit before reset:

Find commit before reset:

abc123 HEAD@{0}: reset: moving to HEAD~5

abc123 HEAD@{0}: reset: moving to HEAD~5

def456 HEAD@{1}: commit: last good commit

def456 HEAD@{1}: commit: last good commit

Restore to previous state

Restore to previous state

Or create recovery branch

Or create recovery branch

Resolving Detached HEAD

解决分离HEAD问题

Understanding Detached HEAD

理解分离HEAD

Detached HEAD state occurs when:

Detached HEAD state occurs when:

HEAD is not attached to any branch

HEAD is not attached to any branch

Recovering from Detached HEAD