`git diff --cached` Is the Command That Shows What You Are Actually About to Commit, Not What You Think

Why this command prevents so many avoidable mistakes: staged state and working tree state are not the same thing, and developers who forget that often commit a different patch from the one they meant to send.

What git diff --cached shows

Git’s diff documentation explains that:

1. git diff shows changes in the working tree not yet staged
2. git diff --cached shows changes between the index and your last commit

That second view is the important one before a commit. It is the answer to a precise question: if I committed right now, what patch would I actually create?

The command:

git diff --cached

gives you that answer directly.

Why this matters more than git status

git status is great for summaries. It tells you which files are staged or modified. It does not show the exact patch shape. And the exact patch shape is often where the real mistake lives.

You may think you staged:

1. one focused fix
2. no debug logging
3. no accidental whitespace churn

But until you inspect the staged diff, that belief is still only a belief.

The most common failure mode

Developers stage part of a file, keep editing, and then mentally merge those two states together. Later they are surprised that the commit contains:

1. an incomplete fix
2. a debug print they forgot
3. the wrong hunk
4. a missing related change

git diff --cached prevents that by showing the index, not your memory.

A practical workflow

Before commit:

git diff --cached
git commit

That extra inspection step is small, but it dramatically improves commit quality, especially when you use partial staging, amend flows, or multiple small fixes in one file.

Why this is especially helpful with patch staging

If you use git add -p or selectively stage hunks in an editor, git diff --cached becomes almost mandatory. Partial staging is powerful precisely because it lets the index diverge from the worktree. Once that happens, only the staged diff tells the truth about the next commit.

This is not complexity for its own sake. It is the price of control, and the inspection command is how you make that control safe.

Why this improves code review too

Better commits produce better reviews. If you regularly inspect the staged patch before committing, reviewers are more likely to receive focused diffs with fewer accidental extras. That lowers review friction across the whole team.

Clean staging habits are not private virtue. They affect everyone who reads your history later.

They also make your own future archaeology easier, because focused commits are much easier to understand when you return to them weeks later.

That alone makes a pre-commit staged diff review worth the few extra seconds it takes.

Precision is almost always cheaper than cleanup later.

The more often you work in partial commits, the more valuable that becomes.

Final recommendation

If you ever stage work in pieces or edit after staging, make git diff --cached part of your default pre-commit habit. It shows the patch you are actually about to record, which is much more useful than the patch you vaguely assume is there.

Sources

• Git diff documentation