A developer reviews git diff, sees the expected edits, and commits. Later, the commit turns out to contain something different. The likely misunderstanding is the relationship between the working tree and Git’s staging area.
Git does not automatically commit every modification currently visible in an editor. The staging area records the content selected for the next commit. Reviewing a commit therefore requires knowing which comparison a command displays.
Start with status
Run:
git statusGit’s status output distinguishes changes staged for the next commit, changes that remain unstaged, and untracked files that are not ignored.
This makes it a useful starting point. It shows the categories of work present before you begin examining individual lines.
Treat status as an inventory. A familiar filename can appear in more than one category if its staged content differs from its latest working-tree content.
That situation is normal and deserves a closer look rather than an immediate attempt to “clean up” the display.
Know which comparison you requested
Plain git diff compares the working tree with the staging area. It shows tracked changes that have not yet been staged.
By contrast:
git diff --stagedshows the staged changes relative to the current commit. –cached is another spelling for this comparison.
Git also supports git diff HEAD for comparing the working tree against the current commit, bringing staged and unstaged tracked changes into that comparison. These views answer different questions.
An empty plain diff does not establish that the next commit will be empty. It may mean that the tracked changes are already staged.
Walk through an edit-stage-edit sequence
Imagine changing a configuration file’s timeout from 10 to 20, then staging the file. After further thought, you change the working copy from 20 to 30.
At this point, the staged version contains 20, while the editor shows 30.
The staged diff describes the change from the committed version to 20. The plain diff describes the remaining change from 20 to 30. A commit made without updating the staging area records the staged content.
This example is why “I checked the file in my editor” and “I reviewed the next commit” are different statements.
When a staged file receives additional edits, decide deliberately whether those edits belong in the same commit.
Review new files separately
Untracked files need attention because the ordinary tracked-file diff does not provide their full review automatically.
Use status to identify them, then open and inspect their contents. A new configuration file, generated report, or temporary note may be easy to overlook when attention is focused on modifications to existing code.
Before committing, check the staged diff again and compare it with the purpose of the change. Does every included file contribute to that purpose? Is a necessary new file missing? Are unrelated edits still better left outside this commit?
The goal is a commit whose contents match its explanation. Understanding the two diff views makes that match much easier to verify.
