Review staged changes before a Git commit

git diff --cached, also spelled git diff --staged, shows the difference between the index and HEAD. For an ordinary commit without path or -a options, this is the change you are about to record.

Understand the three comparisons

git diff
git diff --cached
git diff HEAD

Plain git diff compares the working tree with the index: edits made since staging appear here. --cached compares the index with the last commit. git diff HEAD compares the working-tree result with the last commit for paths Git knows about; it does not include arbitrary untracked files.

A file can have both staged and unstaged changes. Editing it again after git add does not update the index automatically.

Adjust the view

git diff --cached --stat
git diff --cached --name-only
git diff --cached -- src/app.js
git diff --cached -U10
git diff --cached --color-words

These provide a summary, a path list, a single-file patch, wider context, or word-level coloring. Check that no credentials, debug code, or unrelated edits are staged.

Inspect, unstage, and commit

git status
git diff --cached
git diff --cached --check
git commit -m "Clarify request validation"

--check helps detect whitespace errors and conflict markers; it does not prove the code is correct. Run the relevant tests as well.

To remove one path from the next commit while preserving its working copy:

git restore --staged -- src/app.js

This restores the index version from HEAD. It requires a valid source commit; in an unborn repository, a newly staged file can instead be removed from the index with git rm --cached -- path after checking that the working copy is safe.

Investigate apparently missing output

In a new repository with no HEAD commit, git diff --cached still displays staged content against an empty starting point. You do not need to make a first commit to inspect it. Use git diff --cached --summary for rename and mode-change summaries.

If status and diff appear inconsistent, confirm the repository, selected paths, staged versus unstaged status columns, and external diff configuration. Review binary-file summaries separately from text patches.

The --cached and --staged options are aliases. In VS Code, the Staged Changes section provides a graphical view of indexed changes; other clients may use different labels or commit-selection models. Confirm what the client will actually commit.

See git-diff and git-restore.

Related reading

• Run setup once across pytest tests
• Choose an SSH key for Git commands