Git diff --check: Catch Whitespace Errors Before a Commit

A change can look ready to commit while a line ends in accidental spaces or a conflict marker is still in the patch. From your repository, run git diff --cached --check to check the changes currently staged for an ordinary commit. If Git reports a problem, inspect the named file and line, fix it, stage the correction and run the check again.

The important word is staged. A fix saved in your editor is not necessarily the version Git will commit. This guide shows how to check the right snapshot, interpret a report and understand what a clean result leaves unchecked.

Choose which changes to check

Git holds the proposed next commit in the index, also called the staging area. Your working tree is the set of files you edit. These commands check different comparisons:

git diff --check
git diff --cached --check

The first checks changes in tracked working files against the index: edits you have not staged. The second checks the index against HEAD, normally the current commit: the changes an ordinary git commit would record. --staged is a synonym for --cached. In a repository with no commits yet, the staged comparison treats all staged changes as additions.

Run git status first to see which files are staged, unstaged or untracked. An untracked file is not part of either ordinary diff until it is staged. A clean check can therefore mean there was no relevant diff to check. Use git diff --cached to inspect the proposed patch itself, too. Git's version 2.50 diff documentation describes these comparisons.

Read and fix a report

Suppose a staged text file contains a newly added line ending in spaces. Git may report something like:

notes.txt:12: trailing whitespace.
+An example line  

The filename and line number identify where to look; the + marks an added line in the patch. Open the file, inspect that line in context and remove accidental trailing spaces. Some formats deliberately use trailing spaces, so understand the file's conventions before changing them. Do not blindly strip whitespace from an entire project.

Save the file, stage the intended correction, and recheck:

git add -- notes.txt
git diff --cached --check
git diff --cached

git add -- notes.txt stages the current contents of the whole file. If you deliberately staged only part of it, review what else is in the file first; git add -p -- notes.txt lets you choose hunks instead. Always inspect the staged diff afterwards.

Why does the warning remain after I fixed the file?

Imagine the bad line is already staged. You remove its trailing spaces in the editor but do not stage that correction. git diff --check now checks the difference between your fixed working file and the still-bad index. It may produce no warning, while git diff --cached --check still reports the staged error. Stage the intended fix, then rerun the cached check. If both staged and unstaged changes matter to your review, run both checks.

What Git flags, and what it cannot prove

The Git 2.50 diff options say --check warns about introduced conflict markers and whitespace errors and returns a non-zero status when it finds problems. Default whitespace checks include trailing whitespace and a space immediately followed by a tab in initial indentation. Project configuration can change those rules: core.whitespace applies generally, and a whitespace attribute can apply rules to particular paths.

If you see a leftover conflict marker, open the file and resolve the underlying competing changes before staging it. Simply deleting marker lines can leave the wrong code behind. If Git still reports unmerged paths in git status, finish the merge or rebase's conflict-resolution process; this check is not a substitute for that process.

A silent, successful check means Git found no configured whitespace errors or recognised conflict markers in that comparison. It does not prove that the code works, that all files were included, that old issues outside the patch are absent, or that the changes are safe. Run the project's tests and review the actual diff as well. Conversely, a non-zero exit without a clear report can also indicate a command or repository problem; read the error instead of assuming it is whitespace.

Check an existing range before sharing

To inspect changes already committed on a branch relative to a chosen base, specify both endpoints:

git diff --check BASE...HEAD

Replace BASE with the branch or commit you intend to compare, such as a verified local remote-tracking branch. Three dots compare the merge base of the two endpoints with HEAD; they do not simply compare the tips. This is useful for reviewing the branch's combined patch, but it does not check separate unstaged or staged working changes. Confirm the base is the one your team expects and update your local reference through your normal workflow first.

Before the commit, run git diff --cached --check and git diff --cached once more. The first catches the defined patch problems; the second lets you decide whether the actual staged changes belong together.