Instructions

核心职责

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

核心功能：

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

可用脚本

项目包含三个 Shell 脚本：

•
conflict-predictor.sh - 冲突预测
- •检测本地和远程是否修改了相同的文件
- •根据共同修改文件数量判断风险级别
- •提供合并建议
•
batch-checker.sh - 批量检查
- •扫描目录下的所有 Git 仓库
- •显示每个仓库的同步状态
- •支持 JSON 输出
•
gitignore-checker.sh - 配置检查
- •检测已提交的敏感文件（.env、密钥等）
- •检测大文件（>5MB）
- •检查常见问题文件（node_modules等）

使用场景

场景 1: 合并前检查冲突

用户可能说：

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

执行步骤：

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

bash

bash conflict-predictor.sh

•
解释输出结果：
- •低风险：本地和远程没有修改相同文件，可以安全合并
- •中等风险：有1-3个文件被双方修改，可能需要手动解决冲突
- •高风险：有多个文件被双方修改，很可能遇到冲突
•
如果有冲突文件，列出具体的文件名
•
提供建议的操作步骤（脚本会自动输出）

注意事项：

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

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

用户可能说：

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

执行步骤：

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

bash

# 检查工作区状态
git status

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

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

•
解释输出：
- •工作区是否干净
- •有多少未推送的提交
- •有多少未拉取的提交
•
如果用户关心冲突，运行 conflict-predictor.sh

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

用户可能说：

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

执行步骤：

•确认目录路径
•运行批量检查脚本：

bash

bash batch-checker.sh ~/projects

•
解释输出：
- •总共找到多少个仓库
- •每个仓库的状态（✅已同步、⚠️需要同步、🔴需要处理）
- •
  图标含义：
  - •↑N = N个未推送的提交
  - •↓N = N个未拉取的提交
  - •+N = N个未提交的文件
•
如果有问题，建议用户优先处理标记为🔴的仓库

可选参数：

bash

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

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

场景 4: 检查 .gitignore 配置

用户可能说：

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

执行步骤：

•运行 gitignore 检查脚本：

bash

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
•向用户报告具体的错误信息

输出示例

冲突检测输出

code

🔍 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

批量检查输出

code

🔍 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: 脚本找不到或无法执行？

检查脚本路径和权限：

bash

# 查找脚本位置
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: 脚本显示"未找到远程仓库"？

检查远程配置：

bash

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

参考文档

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