Introduction

Before committing, you should review what is staged, not only what is changed in the working tree. Many commit mistakes happen because developers check git diff and forget staged-only edits. This guide shows precise commands for viewing staged changes on a single file and related review workflows.

Understand Working Tree Versus Staging Area

Git tracks at least three states:

• 'HEAD as last committed snapshot.'
• Index as staging area.
• Working tree as current files on disk.

git diff compares working tree against index. git diff --staged compares index against HEAD.

That distinction matters because your commit is created from index, not from all current file contents.

Show Staged Diff for One File

Use the path separator -- and specify file path.

git diff --staged -- src/service/user_service.py

Equivalent command:

git diff --cached -- src/service/user_service.py

Both commands show exactly what this file contributes to the next commit.

If path has spaces, quote it:

git diff --staged -- "docs/API Changes.md"

Compare Staged and Unstaged Changes in Same File

One file can contain both staged and unstaged edits. Review both views to avoid accidental partial commits.

1# unstaged for file
2git diff -- src/service/user_service.py
3
4# staged for file
5git diff --staged -- src/service/user_service.py

This is especially important after using git add -p.

Practical Pre-Commit Review Flow

A reliable short workflow:

1. Check status.
2. Review staged patch for each critical file.
3. Correct staging mistakes.
4. Commit.

git status
git diff --staged -- src/service/user_service.py

If wrong hunks are staged:

git restore --staged src/service/user_service.py
git add -p src/service/user_service.py

This keeps commits focused and reviewable.

Useful Diff Formatting Options

For readability and structural checks, combine staged diff with formatting flags.

1# word-level output for text-heavy files
2git diff --staged --word-diff -- README.md
3
4# include function context for many languages
5git diff --staged -W -- src/main.c
6
7# detect moved code blocks
8git diff --staged --color-moved -- src/module.js

Choose one style and use it consistently in code review habits.

Structural Change Checks

Patch output alone can hide rename and mode changes in large commits. Add structural views.

git diff --staged --name-status
git diff --staged --summary
git diff --staged --stat

These commands help catch unintended deletes, renames, or permission changes before commit.

Compare Staged File Against Another Branch

Sometimes you need staged diff against a branch baseline rather than current HEAD.

git diff main --cached -- src/config/app.yaml

This is useful in long-lived branches where local HEAD context can be misleading.

Binary File and Large Patch Cases

For binary assets, line diffs are limited. Use names and stats for sanity checks:

git diff --staged --name-only
git diff --staged --stat

For very large text patches, split commit into smaller logical units before review.

Team Review Automation

In teams with strict review workflows, pair staged diffs with lightweight hooks that validate commit scope and file patterns. Even with automation, developers should still inspect staged patches manually because tools cannot detect intent mistakes, such as staging debug code in the correct file.

Common Pitfalls

• Using only git diff and assuming it reflects commit content.
• Forgetting -- separator and triggering revision-path ambiguity.
• Staging a file early, editing more, and committing stale staged content.
• Ignoring structural changes such as file mode updates.
• Committing mixed formatting and logic changes together, making review harder.

Summary

• Use git diff --staged -- <file> to review commit-ready changes for a file.
• Review both staged and unstaged views when partial staging is possible.
• Use restore-staged and patch-add to fix index content precisely.
• Add structural diff views to catch renames and mode changes.
• Make staged file review a mandatory pre-commit habit for cleaner commits.