| name | diff |
| description | 当用户要求查看、显示或分析改动，使用 git diff、对比版本、做提交前自查、查看变更统计/日志，
或说“看看改了什么”“审查改动”时使用；只查看内容而不评估质量时尤其使用。
|
| metadata | {"openclaw":{"emoji":"🔍"}} |
diff — 查看与分析代码改动
执行前置
遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。
核心原则
- 先定范围，再执行：查看前先确认比较对象（工作区/暂存区/指定 commit、tag、branch），
不臆断目标；范围不明确时先向用户提问（所有问题一次全部列出，用户一次回答，不逐次追问）。
- 只读不改：diff 是纯只读操作，不修改文件、不暂存、不提交、不 checkout、不 stash。
- 先概览，后详情：先
--stat 看规模与分布，再按文件展开详情，避免输出淹没关键信息。
- 证据驱动：一切结论来自实际 diff 输出，不凭印象描述改动；统计数字必须实测。
- 视图分清：工作区/暂存区/版本间三视图命令不同，混用会得出错误结论。
- 边界校验：同时关注未跟踪文件、空 diff、二进制文件、重命名、权限位、冲突标记等易漏项。
触发时机
- 用户要求查看改动："查看改动"、"显示改动"、"看看改了什么"、"diff"、"git diff"、
"审查代码"、"提交前检查"、"有哪些变化"、"改了什么"
- 用户要求版本对比："对比版本"、"对比两个版本"、"tag 之间有什么区别"、"A 和 B 的差异"、
"这个 commit 改了啥"、"变更日志"
- 与其他技能配合：打 tag 前（tag 技能）先看基线以来改动；debug 时查看引入问题的变更；
optim 后确认改动范围；提交前自查
工作流程
Step 1. 明确查看范围
先确认比较对象，按场景选命令：
| 场景 | 命令 |
|---|
| 工作区未暂存改动（默认） | git diff |
| 已暂存改动 | git diff --cached |
| 全部未提交（含暂存+未跟踪） | git status + 上述两者 |
| 某文件/目录的改动 | git diff -- <path> |
| 与上次提交对比 | git diff HEAD（含暂存）或 git diff HEAD~1 |
| 指定版本之间 | git diff <A> <B>（commit/tag/branch 均可） |
| 分支合并视角（两分支共同祖先起） | git diff <base>...<topic> |
| 某 commit 引入的改动 | git show <commit> --stat |
范围不明确时先提问（"要看工作区改动还是某两个版本之间的差异？"——全部候选一次列出），不臆断。
Step 2. 概览（规模与分布）
git status --short
git diff --stat
git diff --cached --stat
git diff <A> <B> --stat
git diff --numstat
- 记录文件数与增减行数，判断改动集中点（先看主导文件）；
- 输出大时优先
--stat，不一次性倾倒完整 diff。
Step 3. 详情（逐文件）
git diff
git diff -- <file>
git diff -U5 -- <file>
git diff --word-diff
git diff --check
git diff --summary
git diff -M
- 改动多时按
--numstat 从大到小逐文件看；
- 关注注释与文档变化之外的实际逻辑改动。
Step 4. 特殊检查（易漏项）
- 冲突标记：
git diff --check 或搜索 ^<<<<<<<|^=======|^>>>>>>>；
- 调试残留：
print/console.log/echo 调试行、临时文件、.bak、硬编码路径；
- 未跟踪文件：
git status 中 ?? 项（diff 不含未跟踪内容，需单独提示）；
- 二进制/大文件：
--stat 显示 Bin 或不显示行数者；
- 权限位变化：
--summary 中的 mode 变化；
- 意外删除：
--stat 中 deleted 项逐一确认是否有意。
Step 5. 结构化总结
按「改动内容 → 推理依据 → 验证结果 → 后续步骤」输出：
✓ 改动概览
范围: <工作区/暂存区/版本间，比较对象>
统计: <N 个文件, +X/-Y 行>
分组: <新增/修改/删除/重命名/未跟踪各多少>
主导: <改动最大的文件与核心变化>
关注: <冲突标记/调试残留/意外删除/大文件/权限变化，无则省略>
Step 6. 复查
- 关键结论回看原始输出核实（统计数字、重点改动处）；
- 视图切换（stat → 详情）后确认数据一致，无张冠李戴。
错误处理
| 场景 | 处理 |
|---|
| 非 git 仓库 | git rev-parse --is-inside-work-tree 校验，向用户报告 |
| 版本不存在 | git cat-file -t <ref> 校验；用 git tag / git log --oneline 列候选 |
| 空 diff | 区分"确实无改动"与"比较对象错误"（如 A=B、HEAD 未变） |
| diff 输出过大 | 用 --stat/--numstat 概览，按文件逐个展开，不一次性倾倒 |
| 二进制文件 | --stat 显示 Bin，说明无法文本对比；需要时用 --binary 或单独处理 |
| 含未跟踪文件 | git status 单独展示，明确 diff 不包含未跟踪内容 |
| 合并冲突中 | 提示先处理冲突：git diff --check 定位冲突标记，git status 看冲突文件 |
| 换行符/空白差异 | 用 --ignore-space-at-eol/--ignore-all-space 按需忽略；报告时说明 |
| 权限位变化 | --summary 查看 mode 变化，确认是否有意 |
| 重命名误判 | git diff -M 检测重命名，避免误报"删除+新增" |
| 范围表述含糊 | 先提问（工作区/暂存区/哪个版本区间——全部候选一次列出），不臆断 |
注意事项
- diff 是只读操作：不修改、不暂存、不提交、不 checkout、不 stash；
- diff 本身不产生文件改动；若同一任务另有改动，按上级公共 Git 契约收尾；
- 不确定比较对象时一次性列出全部候选提问，不逐次追问，不臆断；
- 输出必须来自实际命令结果，不编造改动内容与统计数字；
