Keeping reformatting commits out of git blame: -w and ignore-revs files

What it is

git blame annotates each line with the commit that last changed it. A formatter run, an indentation change or a line-ending normalisation "changes" every line, and from then on blame points at the cleanup commit instead of the change that introduced the logic. The documentation offers three tools against this:

• -w ignores whitespace when comparing the parent's and the child's version to decide where lines came from.
• --ignore-rev <rev> treats a commit as if it never happened; lines it touched are blamed on the earlier commit that changed them. --ignore-revs-file <file> reads such commits from a file, and blame.ignoreRevsFile in the config applies a file automatically. With blame.markIgnoredLines the re-attributed lines are marked with ?; with blame.markUnblamableLines, lines that cannot be attributed to any other commit are marked with *.
• -M detects lines moved or copied within a file, and -C additionally lines moved or copied from other files modified in the same commit, so a refactor that relocates code keeps the original author.

The GitHub documentation states that a file named .git-blame-ignore-revs in the repository root is applied to its blame view automatically.

Why it matters

Blame is how reviewers, on-call engineers and agents find the reasoning behind a line: the commit message, the pull request, the ticket. A history where every line points at "apply black" or "prettier 3.0" loses that trail at exactly the moments it is needed.

How to apply

• Keep large mechanical changes in their own commits, with nothing else in them, so they can be ignored wholesale.
• Add the full commit hash of each such commit to .git-blame-ignore-revs with a comment line explaining it, and commit the file.
• Set git config blame.ignoreRevsFile .git-blame-ignore-revs in every clone (a setup script or documented one-liner); the file is not applied by the command line without it.
• Use git blame -w -M -C as the default when investigating, and -L <start>,<end> to limit the range.
• Editors and code hosts read the same file; check which ones do before relying on it.

Pitfalls

Ignoring a commit that also contained real changes hides those changes from blame. Hashes must be unabbreviated (the configuration documentation asks for one unabbreviated object name per line), and after a history rewrite the listed IDs match nothing, so the file must be regenerated. git log -S and git bisect are not affected and still find the commit if needed.