Git故障排除指南：解决错误、恢复提交、修复仓库的完整教程

git-troubleshooting by geoffjay/claude-plugins

237 周安装量

7 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/geoffjay/claude-plugins --skill git-troubleshooting

开发代码质量命令行工具

🇨🇳中文介绍

Git 故障排除技能

本技能提供全面的指导，帮助诊断和解决 Git 问题、从错误中恢复、修复损坏的仓库以及处理常见的错误场景。

使用时机

在以下情况时激活此技能：

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

恢复丢失的提交

使用 Reflog

# 查看 reflog（HEAD 的本地历史记录）
git reflog

# 查看特定分支的 reflog
git reflog show branch-name

# 输出示例：
# abc123 HEAD@{0}: commit: feat: add authentication
# def456 HEAD@{1}: commit: fix: resolve bug
# ghi789 HEAD@{2}: reset: moving to HEAD~1

# 恢复丢失的提交
git cherry-pick abc123

# 或者从丢失的提交创建分支
git branch recovered-branch abc123

# 或者重置到丢失的提交
git reset --hard abc123

查找悬空提交

# 查找所有不可达的对象
git fsck --lost-found

# 输出：
# dangling commit abc123
# dangling blob def456

# 查看悬空提交
git show abc123

# 恢复悬空提交
git branch recovered abc123

# 或者合并它
git merge abc123

恢复已删除的分支

# 在 reflog 中查找分支提交
git reflog

# 查找分支删除记录：
# abc123 HEAD@{5}: checkout: moving from feature-branch to main

# 重新创建分支
git branch feature-branch abc123

# 或者如果分支在删除前已被合并
git log --all --oneline | grep "feature"
git branch feature-branch def456

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

解决分离的 HEAD 状态

理解分离的 HEAD

# 分离的 HEAD 状态发生在以下情况：
git checkout abc123
git checkout v1.0.0
git checkout origin/main

# HEAD 未附加到任何分支

从分离的 HEAD 状态恢复

# 检查当前状态
git status
# HEAD detached at abc123

# 选项 1：创建新分支
git checkout -b new-branch-name

# 选项 2：返回之前的分支
git checkout main

# 选项 3：将 HEAD 重新附加到分支
git checkout -b temp-branch
git checkout main
git merge temp-branch

# 如果在分离的 HEAD 状态下进行了提交：
git reflog
# 查找提交记录
git branch recovery-branch abc123

防止分离的 HEAD

# 不要直接检出标签
git checkout -b release-v1.0 v1.0.0

# 不要直接检出远程分支
git checkout -b local-feature origin/feature-branch

# 检查 HEAD 是否分离
git symbolic-ref -q HEAD && echo "attached" || echo "detached"

<<<<<<< HEAD (当前更改)
int result = add(a, b);
||||||| merged common ancestors (基础版本)
int result = sum(a, b);
=======
int sum = calculate(a, b);
>>>>>>> feature-branch (传入更改)

# 当发生合并冲突时
git status
# both modified: file.go

# 查看冲突
cat file.go

# 选项 1：保留我们的版本（当前分支）
git checkout --ours file.go
git add file.go

# 选项 2：保留他们的版本（传入分支）
git checkout --theirs file.go
git add file.go

# 选项 3：手动解决
# 编辑 file.go 解决冲突
git add file.go

# 完成合并
git commit

# 中止合并
git merge --abort

# 中止变基
git rebase --abort

# 中止拣选
git cherry-pick --abort

# 中止还原
git revert --abort

# 中止应用邮箱补丁
git am --abort

# 使用合并工具
git mergetool

# 查看三方差异
git diff --ours
git diff --theirs
git diff --base

# 显示带上下文的冲突
git diff --check

# 列出冲突文件
git diff --name-only --diff-filter=U

# 解决所有冲突后
git add .
git commit

修复失败的变基操作

从失败的变基中恢复

# 中止当前变基
git rebase --abort

# 查找变基前的状态
git reflog
# abc123 HEAD@{1}: rebase: checkout main

# 返回变基前的状态
git reset --hard HEAD@{1}

# 替代方案：使用 ORIG_HEAD
git reset --hard ORIG_HEAD

# 变基冲突期间
git status
# both modified: file.go

# 解决冲突
# 编辑 file.go
git add file.go
git rebase --continue

# 跳过有问题的提交
git rebase --skip

# 在变基期间编辑提交
git commit --amend
git rebase --continue

变基到错误的分支

# 查找原始分支点
git reflog

# 重置到变基前
git reset --hard HEAD@{5}

# 变基到正确的分支
git rebase correct-branch

# 检查仓库完整性
git fsck --full

# 检查连接性
git fsck --connectivity-only

# 验证包文件
git verify-pack -v .git/objects/pack/*.idx

修复损坏的对象

# 移除损坏的对象
rm .git/objects/ab/cd1234...

# 尝试从远程恢复
git fetch origin

# 重建对象数据库
git gc --prune=now

# 积极清理
git gc --aggressive --prune=now

# 移除损坏的索引
rm .git/index

# 重建索引
git reset

# 或者重置到 HEAD
git reset --hard HEAD

从损坏的包文件中恢复

# 解压损坏的包
git unpack-objects < .git/objects/pack/pack-*.pack

# 移除损坏的包
rm .git/objects/pack/pack-*

# 重新打包仓库
git repack -a -d

# 验证完整性
git fsck --full

损坏的分支引用

# 查看所有引用
git show-ref

# 手动修复引用
echo "abc123def456" > .git/refs/heads/branch-name

# 或者使用 update-ref
git update-ref refs/heads/branch-name abc123

# 删除损坏的引用
git update-ref -d refs/heads/bad-branch

# HEAD 损坏或丢失
echo "ref: refs/heads/main" > .git/HEAD

# 或者指向特定提交
echo "abc123def456" > .git/HEAD

# 验证 HEAD
git symbolic-ref HEAD

清理过时的引用

# 移除过时的远程引用
git remote prune origin

# 移除所有过时的引用
git fetch --prune

# 移除所有已不存在的远程分支
git branch -vv | grep ': gone]' | awk '{print $1}' | xargs git branch -D

撤销最后一次提交（保留更改）

# 软重置（更改被暂存）
git reset --soft HEAD~1

# 混合重置（更改未被暂存）
git reset HEAD~1

撤销最后一次提交（丢弃更改）

# 硬重置
git reset --hard HEAD~1

# 仍可通过 reflog 恢复
git reflog
git reset --hard HEAD@{1}

# 重置到特定提交
git reset --hard abc123

# 还原多个提交（创建新提交）
git revert HEAD~3..HEAD

# 交互式变基以移除提交
git rebase -i HEAD~5
# 用 'drop' 标记提交或删除行

# 丢弃未提交的更改
git checkout -- file.go

# 或者在 Git 2.23+ 中
git restore file.go

# 丢弃已暂存的更改
git reset HEAD file.go
git restore file.go

# 或者在 Git 2.23+ 中
git restore --staged file.go
git restore file.go

# 从特定提交恢复文件
git checkout abc123 -- file.go

# 切勿对公共提交使用 reset
# 改用 revert
git revert HEAD
git revert abc123
git revert abc123..def456

# 还原合并提交
git revert -m 1 merge-commit-hash

处理强制推送问题

强制推送后恢复

# 如果你的提交被强制推送覆盖
git reflog
# abc123 HEAD@{1}: pull: Fast-forward

# 恢复你的提交
git reset --hard HEAD@{1}

# 创建备份分支
git branch backup-branch

# 与强制推送后的分支合并
git pull origin main
git merge backup-branch

防止强制推送损坏

# 强制推送前始终先拉取
git fetch origin

# 查看将丢失的内容
git log origin/main..HEAD

# 使用租约进行强制推送（更安全）
git push --force-with-lease origin main

# 配置推送保护
git config --global push.default simple

# 在历史记录中查找大文件
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

# 验证当前大文件
git ls-files | xargs ls -lh | sort -k 5 -h -r | head -20

# 使用 git-filter-repo（推荐）
git filter-repo --path large-file.bin --invert-paths

# 使用 BFG
bfg --strip-blobs-bigger-than 100M

# 移除后
git reflog expire --expire=now --all
git gc --prune=now --aggressive
git push --force origin main

# 配置预提交钩子
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

# 测试 SSH 连接
ssh -T git@github.com

# 检查 SSH 密钥
ls -la ~/.ssh

# 生成新的 SSH 密钥
ssh-keygen -t ed25519 -C "email@example.com"

# 将密钥添加到 ssh-agent
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

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

# 缓存凭据
git config --global credential.helper cache
git config --global credential.helper 'cache --timeout=3600'

# 或者使用存储（安全性较低）
git config --global credential.helper store

# 更新远程 URL
git remote set-url origin https://github.com/user/repo.git

# 使用个人访问令牌
git clone https://TOKEN@github.com/user/repo.git

# 检查远程 URL
git remote -v

# 更改为 SSH
git remote set-url origin git@github.com:user/repo.git

# 更改为 HTTPS
git remote set-url origin https://github.com/user/repo.git

# 验证权限
ls -la .git/
chmod -R u+rw .git/

子模块未初始化

# 初始化子模块
git submodule init
git submodule update

# 或者使用单个命令
git submodule update --init --recursive

子模块中的分离 HEAD

# 进入子模块
cd submodule-dir

# 创建分支
git checkout -b main

# 或者附加到现有分支
git checkout main
git pull origin main

# 更新父仓库
cd ..
git add submodule-dir
git commit -m "chore: update submodule"

# 检查子模块状态
git submodule status

# 重置子模块
git submodule update --init --force

# 移除并重新添加子模块
git submodule deinit -f path/to/submodule
git rm -f path/to/submodule
git submodule add <url> path/to/submodule

# 优化仓库
git gc --aggressive

# 高效重新打包
git repack -a -d --depth=250 --window=250

# 清理旧对象
git prune --expire now

# 清理不必要的文件
git clean -fdx

# 浅克隆
git clone --depth 1 <url>

# 仅获取一个分支
git clone --single-branch --branch main <url>

# 部分克隆
git clone --filter=blob:none <url>

# 稀疏检出
git sparse-checkout init --cone
git sparse-checkout set folder1 folder2

# 增加内存限制
git config --global pack.windowMemory "100m"
git config --global pack.packSizeLimit "100m"
git config --global pack.threads "1"

# 临时禁用增量压缩
git config --global pack.compression 0

"fatal: refusing to merge unrelated histories"

# 允许合并不相关的历史记录
git pull origin main --allow-unrelated-histories

"fatal: not a git repository"

# 重新初始化仓库
git init

# 或者检查 .git 目录是否存在
ls -la .git

# 如果损坏，从备份恢复

"error: Your local changes would be overwritten"

# 暂存更改
git stash
git pull
git stash pop

# 或者丢弃更改
git reset --hard HEAD
git pull

"error: failed to push some refs"

# 先拉取并合并
git pull origin main

# 或者变基
git pull --rebase origin main

# 强制推送（危险）
git push --force origin main

# 更安全的强制推送
git push --force-with-lease origin main

"fatal: unable to access: SSL certificate problem"

# 禁用 SSL 验证（不推荐）
git config --global http.sslVerify false

# 或者更新 SSL 证书
git config --global http.sslCAInfo /path/to/cacert.pem

# 完整完整性检查
git fsck --full --strict

# 检查连接性
git fsck --connectivity-only

# 验证对象
git verify-pack -v .git/objects/pack/*.idx

# 检查 reflog
git reflog expire --dry-run --all

# 分析仓库
git count-objects -vH

# 启用详细日志记录
GIT_TRACE=1 git status
GIT_TRACE=1 git pull

# 调试特定操作
GIT_TRACE_PACKET=1 git fetch
GIT_TRACE_PERFORMANCE=1 git diff
GIT_CURL_VERBOSE=1 git push

# 配置调试
git config --list --show-origin
git config --list --show-scope

定期备份： 在执行风险操作前创建备份分支
使用 Reflog： Reflog 是你的安全网，保持其清洁
启用 Rerere： 重用已记录的冲突解决方案
保护分支： 使用分支保护规则
预提交钩子： 在提交前验证提交内容
定期维护： 定期运行 git gc
强制推送前测试： 始终使用 --dry-run 验证
沟通： 通知团队有关破坏性操作
学习 Git 内部原理： 理解 Git 工作原理可防止问题
保持 Git 更新： 使用最新的稳定版本

其他故障排除指南可在 assets/ 目录中找到：

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

查看 references/ 目录获取：

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

🇺🇸English

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

Weekly Installs

237

Repository

geoffjay/claude-plugins

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

gemini-cli232

codex230

opencode230

cursor230

github-copilot229

kimi-cli227

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

Git故障排除指南：解决错误、恢复提交、修复仓库的完整教程

🇨🇳中文介绍

Git 故障排除技能

使用时机

恢复丢失的提交

使用 Reflog

查找悬空提交

恢复已删除的分支

相关 Skills

重置后恢复

解决分离的 HEAD 状态

理解分离的 HEAD

从分离的 HEAD 状态恢复

防止分离的 HEAD

修复合并冲突

理解冲突标记

基本冲突解决

中止操作

复杂冲突解决

修复失败的变基操作

从失败的变基中恢复

变基冲突

变基到错误的分支

仓库损坏

检测损坏

修复损坏的对象

修复索引损坏

从损坏的包文件中恢复

修复引用

损坏的分支引用

修复 HEAD 引用

清理过时的引用

撤销更改

撤销最后一次提交（保留更改）

撤销最后一次提交（丢弃更改）

撤销多次提交

撤销文件更改

撤销公共提交

处理强制推送问题

强制推送后恢复

防止强制推送损坏

大文件问题

查找大文件

移除大文件

防止大文件

身份验证问题

SSH 密钥问题

HTTPS 身份验证

权限被拒绝

子模块问题

子模块未初始化

子模块中的分离 HEAD

子模块冲突

性能问题

操作缓慢

大型仓库

内存问题

常见错误信息

"fatal: refusing to merge unrelated histories"

"fatal: not a git repository"

"error: Your local changes would be overwritten"

"error: failed to push some refs"

"fatal: unable to access: SSL certificate problem"

诊断命令

仓库健康检查

调试信息

预防策略

资源

🇺🇸English

Git Troubleshooting Skill

When to Use

Recovering Lost Commits

Using Reflog

Finding Dangling Commits

Recovering Deleted Branch

Recovering After Reset

Resolving Detached HEAD

Understanding Detached HEAD

Recovering from Detached HEAD

Preventing Detached HEAD