git diff --staged 是什么
git diff --staged 比较暂存区与最近一次提交（HEAD），回答的问题是「如果现在提交，会带上哪些改动」。它是提交前的最后一道人工复核，也是排查「明明 add 了却没进提交」这类问题的关键视角。
和 git diff 的关系
两个命令看的是同一套三区模型的不同切面：git diff 比较工作区与暂存区，看还没 add 的内容；git diff --staged 比较暂存区与 HEAD，看这次会提交什么。一起使用时，两次输出的并集就是相对上次提交的全部变化，交叉比对还能定位改动停在哪一层。
基本信息
| 适用平台 | Linux / macOS / Windows（Git 2.x） |
|---|---|
| 语法 | git diff --staged [选项] [--] [路径] |
| 别名 | --cached 完全等价 |
| 比较对象 | 暂存区 vs HEAD |
| 常用搭配 | --stat 摘要；--name-only 只列文件名 |
| 典型用途 | 提交前复核、脚本校验提交内容 |
典型使用场景
- 提交前通读：确认即将提交的每一处改动都是有意为之
- 审查范围：用 --name-only 或 --stat 快速看清单与规模
- 排查遗漏：新文件没出现在输出里，说明它还没被 add
- 脚本校验：在钩子里检查是否夹带了生成物或大文件
- 拆分提交：配合 add -p 逐块确认，让每条提交只含一类改动
常用示例
常用示例
git diff --staged # 通读这次会提交的内容
git diff --staged --stat # 只看每个文件的增删规模
git diff --cached --name-only # 只列文件名，便于脚本处理
git add -p && git diff --staged # 组好暂存内容后立刻复核
git diff --staged -- '*.py' # 只看某类文件的暂存改动两个视角的分工
| 命令 | 比较对象 | 回答的问题 |
|---|---|---|
| git diff | 工作区 vs 暂存区 | 还没 add 的改动是什么 |
| git diff --staged | 暂存区 vs HEAD | 这次提交会带上什么 |
| git diff HEAD | 工作区 vs HEAD | 相对上次提交一共改了什么 |
| git status --short | 各层状态摘要 | 改动分别停在哪一层 |
配合 git add -p 的节奏：先按补丁块组好暂存内容，再用 --staged 通读一遍，提交质量会明显提升。
新文件必须先用 git add 才会出现在 --staged 输出里。看到输出里少了文件，先检查它是否还处于未跟踪状态。