如何使用Git的Diff-Staged功能对比已暂存代码与上一次本地提交的差异？

本文共计818个文字，预计阅读时间需要4分钟。

直接运行以下命令（或等价命令）：

确认方式很简单：

• 执行 git status，看是否有 “Changes to be committed” 区块；
• 执行 git ls-files --staged，能列出文件才说明暂存区非空；
• 如果刚改完文件但忘了 git add，那改动还在工作区，此时该用 git diff（不带参数）。

为什么 git diff --staged 和 git diff 结果不同？搞清三棵树位置

Git 里有三份快照：工作目录（你看到的文件）、暂存区（index/staging）、HEAD（上一次 commit）。git diff --staged 对比的是后两者——也就是你 git add 进去的那些改动，和上一次提交之间差了什么。

典型场景：

• 你改了 main.py，又只 git add main.py，没动 utils.py；
• git diff --staged 只显示 main.py 的变更；
• git diff 则显示 main.py（未暂存部分）+ utils.py（完全未 add）；
• 想预览即将提交的内容？必须用 --staged，否则会漏掉已暂存、未修改的部分。

加参数让 diff 更实用：--name-only、-p、--word-diff

纯文本 diff 容易淹没在大文件里，几个高频参数能快速定位关键信息：

• git diff --staged --name-only：只列出哪些文件被暂存了，适合快速核对范围；
• git diff --staged -p：强制显示 patch 格式（默认行为，但显式加上更明确）；
• git diff --staged --word-diff：按单词粒度高亮改动，对文档类或字符串微调特别有用；
• 注意：--staged 不支持 -w（忽略空白）与 --ignore-space-change 同时生效，某些 Git 版本会静默忽略后者。

误用 git commit -a 导致 --staged 失效？它绕过了暂存区

git commit -a 会自动把所有已跟踪文件的修改（包括删除）加入暂存区再提交，相当于隐式执行了一次 git add -u。这意味着：

• 你运行 git commit -a 前没手动 git add，那 git diff --staged 就永远看不到东西——因为暂存动作发生在 commit 过程中，不是你控制的；
• 想精确控制提交内容，别依赖 -a，老老实实 git add <file> + git diff --staged + git commit；
• 如果已经 commit -a 完了，想回溯“当时暂存了什么”，只能靠 git show HEAD 或 git log -p -1。

真正容易被忽略的是：--staged 不是“上次 commit 以来所有改动”，而是“你亲手放进暂存区的那部分”。哪怕改了 10 个文件，只 add 了其中 1 个，--staged 就只告诉你这 1 个。