diff

name	diff
description	当用户要求查看、显示或分析改动，使用 git diff、对比版本、做提交前自查、查看变更统计/日志， 或说“看看改了什么”“审查改动”时使用；只查看内容而不评估质量时尤其使用。
metadata	{"openclaw":{"emoji":"🔍"}}

diff — 查看与分析代码改动

执行前置

遵循当前目录 AGENTS.md「技能执行公共契约」；仅按需读取技能正文与 reference。

核心原则

1. 先定范围，再执行：查看前先确认比较对象（工作区/暂存区/指定 commit、tag、branch）， 不臆断目标；范围不明确时先向用户提问（所有问题一次全部列出，用户一次回答，不逐次追问）。
2. 只读不改：diff 是纯只读操作，不修改文件、不暂存、不提交、不 checkout、不 stash。
3. 先概览，后详情：先 --stat 看规模与分布，再按文件展开详情，避免输出淹没关键信息。
4. 证据驱动：一切结论来自实际 diff 输出，不凭印象描述改动；统计数字必须实测。
5. 视图分清：工作区/暂存区/版本间三视图命令不同，混用会得出错误结论。
6. 边界校验：同时关注未跟踪文件、空 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              # 逐文件 +N/-N

• 记录文件数与增减行数，判断改动集中点（先看主导文件）；
• 输出大时优先 --stat，不一次性倾倒完整 diff。

Step 3. 详情（逐文件）

git diff                          # 完整差异
git diff -- <file>                # 单文件
git diff -U5 -- <file>            # 加大上下文（shell/配置改动适用）
git diff --word-diff              # 单词级差异（长行/文本改动）
git diff --check                  # 空白错误与冲突标记
git diff --summary                # 重命名/权限位/删除概览
git diff -M                       # 检测重命名（防误判为删+增）

• 改动多时按 --numstat 从大到小逐文件看；
• 关注注释与文档变化之外的实际逻辑改动。

Step 4. 特殊检查（易漏项）

1. 冲突标记：git diff --check 或搜索 ^<<<<<<<|^=======|^>>>>>>>；
2. 调试残留：print/console.log/echo 调试行、临时文件、.bak、硬编码路径；
3. 未跟踪文件：git status 中 ?? 项（diff 不含未跟踪内容，需单独提示）；
4. 二进制/大文件：--stat 显示 Bin 或不显示行数者；
5. 权限位变化：--summary 中的 mode 变化；
6. 意外删除：--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 契约收尾；
• 不确定比较对象时一次性列出全部候选提问，不逐次追问，不臆断；
• 输出必须来自实际命令结果，不编造改动内容与统计数字；