| name | git-sync-checker-enhanced |
| description | Git 仓库同步状态检查工具。检查本地与远程仓库的同步状态、预测潜在冲突、检测敏感文件和大文件。当用户提到"检查同步状态"、"检查冲突"、"批量检查仓库"、"检查 gitignore"或类似的 Git 状态分析需求时使用此技能。 |
| allowed-tools | Bash, Read, Grep |
Instructions
核心职责
提供 Git 仓库状态检查和冲突预测功能。
核心功能：
- ✅ 检查本地与远程的同步状态
- ✅ 预测合并或拉取时的潜在冲突
- ✅ 批量检查多个仓库
- ✅ 检测敏感文件和大文件
- ❌ 不自动执行任何 Git 操作（只检查不修改）
可用脚本
项目包含三个 Shell 脚本：
-
conflict-predictor.sh - 冲突预测
- 检测本地和远程是否修改了相同的文件
- 根据共同修改文件数量判断风险级别
- 提供合并建议
-
batch-checker.sh - 批量检查
- 扫描目录下的所有 Git 仓库
- 显示每个仓库的同步状态
- 支持 JSON 输出
-
gitignore-checker.sh - 配置检查
- 检测已提交的敏感文件（.env、密钥等）
- 检测大文件（>5MB）
- 检查常见问题文件（node_modules等）
使用场景
场景 1: 合并前检查冲突
用户可能说：
- "我要合并最新代码，会有冲突吗？"
- "检查一下合并风险"
- "pull 代码会有问题吗？"
执行步骤：
- 确认当前在 Git 仓库中
- 运行冲突预测脚本：
bash conflict-predictor.sh
-
解释输出结果：
- 低风险：本地和远程没有修改相同文件，可以安全合并
- 中等风险：有1-3个文件被双方修改，可能需要手动解决冲突
- 高风险：有多个文件被双方修改，很可能遇到冲突
-
如果有冲突文件，列出具体的文件名
-
提供建议的操作步骤（脚本会自动输出）
注意事项：
- 这是基于文件级别的检测，即使修改了同一文件也可能不冲突（如果修改的代码行不重叠）
- 这是一个有用的参考，但不是100%准确的预测
场景 2: 检查当前仓库状态
用户可能说：
- "检查同步状态"
- "查看 Git 状态"
- "准备下班，检查一下代码"
执行步骤：
- 使用 Bash 工具运行标准 Git 命令：
git status
git fetch --all
git rev-list --left-right --count HEAD...@{u}
-
解释输出：
- 工作区是否干净
- 有多少未推送的提交
- 有多少未拉取的提交
-
如果用户关心冲突，运行 conflict-predictor.sh
场景 3: 批量检查多个仓库
用户可能说：
- "检查 ~/projects 下所有仓库"
- "批量检查项目状态"
- "看看所有项目的同步情况"
执行步骤：
- 确认目录路径
- 运行批量检查脚本：
bash batch-checker.sh ~/projects
-
解释输出：
- 总共找到多少个仓库
- 每个仓库的状态（✅已同步、⚠️需要同步、🔴需要处理）
- 图标含义：
- ↑N = N个未推送的提交
- ↓N = N个未拉取的提交
- +N = N个未提交的文件
-
如果有问题，建议用户优先处理标记为🔴的仓库
可选参数：
bash batch-checker.sh ~/projects 2
bash batch-checker.sh ~/projects 3 json
场景 4: 检查 .gitignore 配置
用户可能说：
- "检查 gitignore"
- "有没有不该提交的文件"
- "检查敏感文件"
执行步骤：
- 运行 gitignore 检查脚本：
bash gitignore-checker.sh
-
解释输出：
- 敏感文件：.env、密钥文件等
- 大文件：超过5MB的文件
- 常见问题：node_modules、__pycache__等
-
如果发现问题，提供清理步骤：
- 从 Git 移除但保留本地文件：
git rm --cached <文件>
- 添加到 .gitignore
- 提交修改
-
提醒用户：文件仍在 Git 历史中，如需彻底清除需要使用 git filter-branch 或 BFG Repo-Cleaner
执行原则
安全限制
- ❌ 永不执行任何修改 Git 仓库的命令
- ❌ 永不自动推送或拉取代码
- ❌ 永不删除分支或重置提交
- ✅ 只执行只读的检查命令
- ✅ 所有建议的操作都需要用户手动执行
输出原则
- 简洁明了：直接告诉用户状态和风险
- 提供上下文：解释为什么有风险
- 具体建议：提供可执行的命令
- 诚实透明：说明检测的局限性
错误处理
如果脚本执行失败：
- 检查是否在 Git 仓库中：
git rev-parse --git-dir
- 检查脚本是否有执行权限：
chmod +x *.sh
- 检查 Git 是否已安装：
git --version
- 向用户报告具体的错误信息
输出示例
冲突检测输出
🔍 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: 批量检查很慢？
对于大量仓库，可以：
- 减少搜索深度
- 缩小搜索范围
- 每个仓库有30秒超时保护
技术说明
冲突预测算法
- 找共同祖先：
git merge-base HEAD REMOTE/BRANCH
- 列出本地修改：
git diff --name-only BASE HEAD
- 列出远程修改：
git diff --name-only BASE REMOTE
- 找交集：
comm -12 <(local_files) <(remote_files)
- 判断风险：0个=低，1-3个=中，>3个=高
局限性：
- 只检测文件级别，不检测行级别
- 不考虑文件类型和重要性
- 不考虑开发者经验
批量检查流程
- 使用
find 搜索 .git 目录
- 对每个仓库执行：
git status --porcelain 检查工作区git fetch 获取远程更新git rev-list --count 计算提交差异
- 汇总结果并输出
敏感文件检测
使用正则表达式匹配常见模式：
- 环境变量：
\.env$、\.env\.local$
- 密钥文件：
.*\.key$、.*\.pem$
- SSH密钥：
id_rsa、id_dsa
- 配置文件：
database\.yml、secrets\.yml
参考文档
