git diff 用来比较「两份内容差在哪」。默认比较工作区与暂存区,加参数后可以比暂存区与 HEAD、两个提交、两个分支,甚至两个还没纳入 Git 的文件。

本文列出 git diff 支持的常用参数并逐个解说,把「我到底在看谁和谁的差别」这件事讲清楚。

ℹ️
关于本系列
本文是《Git 使用教程》按命令拆分的第 7 / 28 篇,全部收录在 Git 栏目。参数表列的是日常高频项,并非穷举;想看某个命令的完整参数,用 git diff -h 看精简列表、git help diff 看完整手册。示例以 Git 2.56.0 为准。

一、命令语法

先看语法骨架,再对照下一节的参数表。<占位> 表示必填值,实际输入时不要带尖括号;[...] 表示可选项,-- 用来分隔选项与路径。

bash语法
git diff [<options>] [<commit>] [--] [<path>...]

二、参数逐项详解

下表按用途列出 git diff 的常用参数,每项都注明了「它到底改变了什么」。

参数作用
(无参数)比较工作区与暂存区,看还没 add 的改动
--cached / --staged比较暂存区与 HEAD,看即将提交什么
HEAD / <commit>比较工作区与指定提交
<A>..<B>比较两个提交之间的差别
<path>只看指定路径,路径前建议加 --
--stat / --shortstat只看文件级改动统计 / 只要一行汇总
--name-only / --name-status只列文件名 / 文件名加 A M D 状态
--check检查空白错误(行尾空格、残留冲突标记),提交前常用
--color-words / --word-diff按词而不是按行显示差异,改长段落时更清楚
-w / --ignore-all-space忽略空白变化
--no-index比较工作区里两个尚未纳入 Git 的文件
--no-renames / --find-renames关闭 / 开启重命名检测

三组最常用比较对象

命令比较的是
git diff工作区 ↔ 暂存区
git diff --cached暂存区 ↔ HEAD(下一次提交的内容)
git diff HEAD工作区 ↔ HEAD(全部未提交改动)

三、常用示例

提交前的标准检查

bash提交前的标准检查
git add -A
git diff --cached --check        # 空白错误检查
git diff --cached --stat         # 改了哪些文件、多少行
git diff --cached                # 逐行确认

按范围与路径查看

bash按范围与路径查看
git diff main..feature/login -- src/
git diff --name-only HEAD~3 HEAD
git diff --word-diff README.md

比较两个普通文件

bash比较两个普通文件
git diff --no-index old.json new.json

四、注意事项

记不住就记这一句: 不带参数看「还没 add 的」,带 --cached 看「已经 add 的」。提交前把这两条各跑一遍,就不会出现「以为提交了其实没暂存」。
ℹ️
输出被分页器挡住了?
git diff 默认走 pager,按 q 退出;想一次性打印用 git --no-pager diff 或 GIT_PAGER=cat git diff。

五、小结

git diff 的参数分两类:一类选比较对象(--cached、HEAD、两个提交),一类选输出形态(--stat、--name-only、--word-diff、--check)。先定对象再挑形态,就不会看错内容。

本系列共 28 篇,一个命令一篇,完整目录见 Git 栏目。下一篇:git log 命令参数详解。