Git Sync Checker Enhanced

Instructions

核心职责

提供 Git 仓库状态检查和冲突预测功能。

核心功能：

• ✅ 检查本地与远程的同步状态
• ✅ 预测合并或拉取时的潜在冲突
• ✅ 批量检查多个仓库
• ✅ 检测敏感文件和大文件
• ❌ 不自动执行任何 Git 操作（只检查不修改）

可用脚本

项目包含三个 Shell 脚本：

1. conflict-predictor.sh - 冲突预测

   • 检测本地和远程是否修改了相同的文件
   • 根据共同修改文件数量判断风险级别
   • 提供合并建议

2. batch-checker.sh - 批量检查

   • 扫描目录下的所有 Git 仓库
   • 显示每个仓库的同步状态
   • 支持 JSON 输出

3. gitignore-checker.sh - 配置检查

   • 检测已提交的敏感文件（.env、密钥等）
   • 检测大文件（>5MB）
   • 检查常见问题文件（node_modules等）

使用场景

场景 1: 合并前检查冲突

用户可能说：

• "我要合并最新代码，会有冲突吗？"
• "检查一下合并风险"
• "pull 代码会有问题吗？"

执行步骤：

1. 确认当前在 Git 仓库中
2. 运行冲突预测脚本：

bash conflict-predictor.sh

1. 解释输出结果：

   • 低风险：本地和远程没有修改相同文件，可以安全合并
   • 中等风险：有1-3个文件被双方修改，可能需要手动解决冲突
   • 高风险：有多个文件被双方修改，很可能遇到冲突

2. 如果有冲突文件，列出具体的文件名

3. 提供建议的操作步骤（脚本会自动输出）

注意事项：

• 这是基于文件级别的检测，即使修改了同一文件也可能不冲突（如果修改的代码行不重叠）
• 这是一个有用的参考，但不是100%准确的预测

场景 2: 检查当前仓库状态

用户可能说：

• "检查同步状态"
• "查看 Git 状态"
• "准备下班，检查一下代码"

执行步骤：

1. 使用 Bash 工具运行标准 Git 命令：

# 检查工作区状态
git status

# 获取远程更新（不拉取）
git fetch --all

# 检查本地领先/落后的提交数
git rev-list --left-right --count HEAD...@{u}

1. 解释输出：

   • 工作区是否干净
   • 有多少未推送的提交
   • 有多少未拉取的提交

2. 如果用户关心冲突，运行 conflict-predictor.sh

场景 3: 批量检查多个仓库

用户可能说：

• "检查 ~/​projects 下所有仓库"
• "批量检查项目状态"
• "看看所有项目的同步情况"

执行步骤：

1. 确认目录路径
2. 运行批量检查脚本：

bash batch-checker.sh ~/​projects

1. 解释输出：

   • 总共找到多少个仓库
   • 每个仓库的状态（✅已同步、⚠️需要同步、🔴需要处理）
   • 图标含义：
     • ↑N = N个未推送的提交
     • ↓N = N个未拉取的提交
     • +N = N个未提交的文件

2. 如果有问题，建议用户优先处理标记为🔴的仓库

可选参数：

# 指定搜索深度（默认3）
bash batch-checker.sh ~/​projects 2

# JSON 输出（供脚本使用）
bash batch-checker.sh ~/​projects 3 json

场景 4: 检查 .gitignore 配置

用户可能说：

• "检查 gitignore"
• "有没有不该提交的文件"
• "检查敏感文件"

执行步骤：

1. 运行 gitignore 检查脚本：

bash gitignore-checker.sh

1. 解释输出：

   • 敏感文件：.env、密钥文件等
   • 大文件：超过5MB的文件
   • 常见问题：node_modules、__pycache__等

2. 如果发现问题，提供清理步骤：

   • 从 Git 移除但保留本地文件：git rm --cached <文件>
   • 添加到 .gitignore
   • 提交修改

3. 提醒用户：文件仍在 Git 历史中，如需彻底清除需要使用 git filter-branch 或 BFG Repo-Cleaner

执行原则

安全限制

• ❌ 永不执行任何修改 Git 仓库的命令
• ❌ 永不自动推送或拉取代码
• ❌ 永不删除分支或重置提交
• ✅ 只执行只读的检查命令
• ✅ 所有建议的操作都需要用户手动执行

输出原则

1. 简洁明了：直接告诉用户状态和风险
2. 提供上下文：解释为什么有风险
3. 具体建议：提供可执行的命令
4. 诚实透明：说明检测的局限性

错误处理

如果脚本执行失败：

1. 检查是否在 Git 仓库中：git rev-parse --git-dir
2. 检查脚本是否有执行权限：chmod +x *.sh
3. 检查 Git 是否已安装：git --version
4. 向用户报告具体的错误信息

输出示例

冲突检测输出

🔍 Git 冲突检查
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
分支: feature/​new-ui
远程: origin

📊 状态概览
本地修改文件: 5 个
远程修改文件: 3 个
共同修改文件: 2 个

⚠️  中等风险
本地和远程修改了相同的文件，可能需要手动解决冲突。

⚠️  可能冲突的文件：
  • src/​components/​Header.tsx
  • package.json

建议操作：
# 1. 备份当前分支
git branch backup-20251125-1430

# 2. 拉取并合并
git pull origin feature/​new-ui

# 3. 如遇冲突，手动解决后：
git add <已解决的文件>
git commit

批量检查输出

🔍 Git 仓库批量检查
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
搜索目录: /​Users/​you/​projects
最大深度: 3

找到 5 个仓库

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅  project-a                  (main)
⚠️  project-b                  (dev)                 ↑2
🔴  project-c                  (feature/​auth)        +3
✅  project-d                  (main)
⚠️  project-e                  (main)                ↓1

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 检查完成

总计: 5 个仓库
✅ 已同步: 2
⚠️  需要同步: 2
🔴 需要立即处理: 1

常见问题

Q: 脚本找不到或无法执行？

检查脚本路径和权限：

# 查找脚本位置
find ~/​.claude/​skills -name "*.sh"

# 添加执行权限
chmod +x ~/​.claude/​skills/​git-sync-checker-enhanced/​*.sh

# 测试执行
bash ~/​.claude/​skills/​git-sync-checker-enhanced/​conflict-predictor.sh

Q: 脚本显示"未找到远程仓库"？

检查远程配置：

git remote -v

如果没有远程仓库，脚本会提示用户添加。

Q: 批量检查很慢？

对于大量仓库，可以：

1. 减少搜索深度
2. 缩小搜索范围
3. 每个仓库有30秒超时保护

技术说明

冲突预测算法

1. 找共同祖先：git merge-base HEAD REMOTE/​BRANCH
2. 列出本地修改：git diff --name-only BASE HEAD
3. 列出远程修改：git diff --name-only BASE REMOTE
4. 找交集：comm -12 <(local_files) <(remote_files)
5. 判断风险：0个=低，1-3个=中，>3个=高

局限性：

• 只检测文件级别，不检测行级别
• 不考虑文件类型和重要性
• 不考虑开发者经验

批量检查流程

1. 使用 find 搜索 .git 目录
2. 对每个仓库执行：
   • git status --porcelain 检查工作区
   • git fetch 获取远程更新
   • git rev-list --count 计算提交差异
3. 汇总结果并输出

敏感文件检测

使用正则表达式匹配常见模式：

• 环境变量：\.env$、\.env\.local$
• 密钥文件：.*\.key$、.*\.pem$
• SSH密钥：id_rsa、id_dsa
• 配置文件：database\.yml、secrets\.yml

参考文档

• 完整使用说明：README.md
• 改进提案：IMPROVEMENT_PROPOSAL.md