Ignore Whitespace in Git Diff: When It Hides Bugs

A diff that reindents a whole file is useless for review — every line lights up red and green even though the logic never changed. Telling the tool to ignore whitespace collapses that noise so you see only the real edits. But the same flag that hides a harmless reindent can also hide the one space-versus-tab change that broke your build. This guide covers how ignore-whitespace works, the exact flags, and the files where you should never use it.

#TL;DR

• -w ignores all whitespace; -b ignores only changes in the amount of whitespace.
• Ignore whitespace to review logic changes hidden under a reformat or reindent.
• Never ignore whitespace in Python, Makefiles, YAML, or tab-separated data.
• On GitHub, use the gear menu's "Hide whitespace changes" or add ?w=1.
• The flags only change the view — they never edit files or alter commits.

#What does "ignore whitespace" actually do?

Whitespace means spaces, tabs, and the run of blank characters at the end of a line. By default a diff treats every one of those characters as content, so changing four spaces to a tab, or trimming trailing spaces, registers as a changed line. Ignore-whitespace options relax that comparison. Git exposes several, and they sit on a spectrum from gentle to aggressive.

#-w / --ignore-all-space

The most aggressive option. Per the official git diff-options documentation, --ignore-all-space (short flag -w) ignores whitespace when comparing lines, and ignores differences even if one line has whitespace where the other has none. In practice, foo(a,b) and foo( a, b ) are treated as the same line. Use it when an auto-formatter has rewritten spacing everywhere and you only care whether any token actually changed.

#-b / --ignore-space-change

The middle setting. --ignore-space-change (short flag -b) ignores changes in the amount of whitespace: it skips trailing whitespace and treats any run of spaces or tabs as equivalent to any other run. The key difference from -w is that -b still cares about the presence versus absence of whitespace — a b and ab are different to -b, but identical to -w.

#--ignore-space-at-eol and --ignore-blank-lines

Two narrower tools. --ignore-space-at-eol ignores only trailing whitespace, which is handy when an editor strips line-end spaces on save. --ignore-blank-lines ignores changes whose lines are all blank, so adding or removing empty lines between functions stops cluttering the diff. The git docs note the options nest: -b is a superset of --ignore-space-at-eol, and -w is in turn a superset of -b. Vertical whitespace — actual line breaks — always stays significant.

Here is the same change viewed three ways:

# Default: every reindented line shows
git diff app.js

# Ignore amount of whitespace (reindents vanish)
git diff -b app.js

# Ignore all whitespace + blank-line shuffles
git diff -w --ignore-blank-lines app.js

#How to ignore whitespace in git diff

The flags work the same across git diff, git show, git log -p, and git blame -w. You can pass them ad hoc, wire them into review tools, or — carefully — make them a default.

#Command-line flags

Combine flags for the cleanest review pass:

# Common review combo: skip indent + blank-line noise
git diff -w --ignore-blank-lines

# Works on staged changes too
git diff --staged -b

# Blame, ignoring whitespace-only commits
git blame -w app.py

#Hide whitespace changes on GitHub

In a pull request's Files changed tab, open the gear menu and tick Hide whitespace changes, or append ?w=1 to the diff URL. GitHub introduced the ?w=1 parameter back in 2011, as described on the GitHub blog post on ignoring whitespace in code review, and the preference is now remembered per pull request. One caveat: GitHub may not apply the setting on very large or not-yet-expanded files, so expand the file or fall back to the URL parameter.

#Set it as a default safely

You can default git diff to a whitespace-aware mode without an alias:

# Make pager-driven diffs ignore whitespace amount
git config --global diff.wsErrorHighlight all
git config --global core.pager 'less -R'
git config --global alias.dw 'diff -w'

Prefer a dedicated git dw alias over globally forcing -w everywhere — a permanent global ignore is exactly how the bugs in the next section slip through.

#When ignoring whitespace hides a real bug

Ignore-whitespace assumes whitespace is cosmetic. In several common file types it is syntax, and hiding it hides the defect itself.

#Python indentation and tabs vs spaces

Python uses indentation to define blocks, so an indentation change is a logic change. The Python reference treats indentation as part of the grammar, and Python 3 refuses to run a file that mixes tabs and spaces inconsistently, raising a TabError — a subclass of IndentationError. PEP 8 settles the convention: spaces are the preferred indentation method. Consider this regression:

def charge(order):
    total = subtotal(order)
    if order.coupon:
        total = apply(total)
    return total   # inside if? or after it?

If a refactor dedents that return by one level, the function changes meaning — but git diff -w shows nothing, because to -w the leading whitespace is invisible. Review Python with plain git diff, never -w.

#Makefiles require real tabs

GNU Make is strict: each command line in a recipe must begin with a literal tab character. Convert that tab to spaces and Make fails with the classic *** missing separator error. A whitespace-ignoring diff erases the exact distinction that matters, so a contributor whose editor expanded tabs to spaces will produce a diff that looks empty under -w while the build is broken.

#YAML, Go struct tags, and string literals

YAML nests by indentation, so a two-space shift can silently move a key into the wrong block. Whitespace inside quoted string literals is real data in every language — "a b" is not "a b". And gofmt-style alignment uses tabs meaningfully in some contexts. When the content of a line includes whitespace that matters, reach for a plain diff and read the highlighted characters.

• Whitespace-significant: Python, Makefiles, YAML, TSV, .editorconfig-driven layouts.
• String/data whitespace: any quoted literal, CSV/TSV fields, Markdown code fences.
• Safe to ignore: most C-family code, JSON, HTML, CSS after a formatter run.

#How to compare two files ignoring whitespace without losing the real changes

The fix is not to pick one mode forever — it is to use the right mode for the right pass.

#A two-pass review workflow

Run the diff twice. First with -w to confirm the logic change is what you expect; then once more with a plain git diff to scan the whitespace-only lines for anything in a sensitive file. The first pass tells you what changed; the second tells you whether the formatting change is itself the bug. For ad-hoc text — config snippets, logs, two pasted versions of a function — a browser diff checker lets you toggle between both views without staging anything in git.

#Reformat first, then diff

A cleaner long-term move is to stop generating whitespace noise in the first place. Run a formatter (or minify and re-expand) so both sides share one canonical layout, then diff. If you are comparing machine-generated JSON, pretty-print both files with a JSON decoder before the diff so the only differences left are real value changes. Prose drafts behave the same way once normalized in a Markdown editor.

#Whitespace-only commits

When you do need to reformat a whole file, commit the reformat on its own, with a message like style: reformat, no logic change. Reviewers can then diff around it with -w and trust that the commit contains nothing but whitespace. This keeps git blame useful and stops a formatting sweep from burying a real fix on the same line.

#References

• git diff-options — official documentation — exact wording and nesting of -w, -b, --ignore-space-at-eol, and --ignore-blank-lines.
• Ignore white space in code review — The GitHub Blog — origin and behavior of the ?w=1 parameter and the Hide whitespace changes toggle.
• PEP 8 — Style Guide for Python Code — spaces-over-tabs convention and indentation rules cited for the Python example.
• The Python Language Reference: Lexical analysis — indentation as grammar and the TabError condition.
• GNU Make Manual: Recipe Syntax — the tab-prefix requirement behind the "missing separator" failure.

#Related on iKit

• Compare any two texts in seconds with a browser diff checker — the foundations of how a diff aligns two versions, and why a client-side checker keeps your text private.
• Side-by-side vs unified diff: how to read each format — once you've hidden whitespace noise, this explains the two layouts and what the @@ hunk header means.