Check whitespace errors in Git: staged and unstaged changes

Trailing spaces are easy to miss when reviewing a diff before a commit. Git can report them with git diff --check, but the area it checks changes depending on whether you have staged your edits. An empty result can be misleading if the version you plan to commit still contains the problem.

These examples use PowerShell on Windows with Git for Windows available. Open PowerShell in the repository you want to check. You will check unstaged edits, inspect the staged version, and check again after fixing a file.

Check unstaged changes

For edits you have not yet staged with git add, run:

git diff --check
$LASTEXITCODE

For example, if line 2 of sample.txt contains second followed by two spaces, Git reports:

sample.txt:2: trailing whitespace.
+second  
2

sample.txt:2 identifies the file and line number. The message says there is whitespace at the end of the line; the line beginning with + is the added line in the diff. Showing whitespace in your editor makes those otherwise invisible spaces easier to find.

In PowerShell, $LASTEXITCODE holds the exit code of the preceding native command. This example returned 2. In a script, treat a nonzero exit code as a reason to inspect the output instead of assuming that only 2 indicates a problem. When the check finds no problems, it prints nothing and returns 0.

Check staged changes

After using git add, add --cached to inspect what is in the staging area. This compares the staged contents for the next commit with the last commit.

git diff --cached --check
$LASTEXITCODE

Immediately after staging a file, its working-tree contents may be identical to the staged version. A plain git diff --check can therefore produce no output while git diff --cached --check still reports trailing whitespace. Use the cached form when reviewing the changes that are already staged for your commit.

Stage the corrected file again

Removing the spaces in your editor and saving the file does not replace the version already in the staging area. Stage the corrected file and run the check again. Here, sample.txt is the example filename.

git add -- sample.txt
git diff --cached --check
$LASTEXITCODE

0

git add stages the file’s current contents. If you had staged only part of a file, this command also stages its other saved changes. To keep a partial selection, select the intended changes again using your editor’s partial-staging feature.

Check the scope when there is no output

A new, untracked file is not inspected by a plain git diff --check. Start by checking the repository’s short status:

git status --short

A line starting with ?? indicates an untracked file. Stage only the files you intend to commit, then inspect them with git diff --cached --check. There is no need to stage unrelated files just to run this check.

The core.whitespace setting controls which whitespace problems Git detects. Defaults include whitespace at the end of a line and a space immediately followed by a tab in the initial indentation. --check also reports introduced conflict markers, but it does not validate syntax or program behavior. An exit code of 0 still leaves code tests and a review of the actual changes to do.

--exit-code is a separate option that reports whether there are differences, and it cannot be combined with --check. It can return 1 for a perfectly valid edit simply because a diff exists. For whitespace problems, use --check and read its output.

References: Git documentation: git diff; Git documentation: core.whitespace.