When auditing a codebase to find out when and why a line of code was introduced, git blame is a developer’s best friend. However, large styling updates, code formatter adoptions (like Prettier), or global linter autofixes can clutter this history. A single bulk reformatting commit can rewrite code authorship labels for the entire repository, hiding the original developers and commits that introduced the actual business logic.
To solve this problem, Git (since version 2.23) introduced a native feature that allows developers to ignore specific commits during blame evaluations: the .git-blame-ignore-revs file.
In this guide, we will explore how to configure this ignore list to keep your git blame clean and relevant.
1. How .git-blame-ignore-revs Works
The .git-blame-ignore-revs file is a plain text file placed at the root of your repository. It contains a list of commit hashes. When Git executes git blame, it ignores these specified commits and traces the authorship back to the previous commit that actually modified the line’s logic.
2. Implementation Guide
Step 1: Identify the Commits to Ignore
Find the SHA-1 hashes of the formatting-only or large refactoring commits (e.g., a1b2c3d4e5f6g7h8i9j0) that are cluttering your file histories.
Step 2: Create the .git-blame-ignore-revs File
Create a new file named .git-blame-ignore-revs in your repository’s root directory, listing the targets:
# Run prettier code formatting on entire codebase
a1b2c3d4e5f6g7h8i9j0a1b2c3d4e5f6g7h8i9j0
# Global eslint automatic fixes
e5f6g7h8i9j0a1b2c3d4e5f6g7h8i9j0a1b2c3d4
Step 3: Tell Git to Use the Ignore File
Run the following command to instruct Git to automatically reference this file for your local environment:
git config blame.ignoreRevsFile .git-blame-ignore-revs
Now, any time you run git blame locally, the specified formatting revisions will be bypassed.
3. Sharing Configurations and GitHub Support
Configuring git config blame.ignoreRevsFile is a local configuration. To ensure your entire team benefits from it, commit the .git-blame-ignore-revs file to your repository.
Additionally, major code hosting platforms like GitHub and GitLab support this standard. If a .git-blame-ignore-revs file is present in the default branch’s root directory, their web interface will automatically ignore those commits when users view the file blame history.
4. Overriding the Ignores
If you ever need to inspect a formatting commit directly, you can instruct Git to bypass the ignore list using:
git blame --no-ignore-revs-file path/to/file.js
Conclusion
Global code formatting runs improve readability but can damage history tracking. By implementing a .git-blame-ignore-revs file:
- Formatting runs can be excluded from author attribution.
- Commit histories are mapped back to their original logic implementations.
- Review interfaces on GitHub remain clutter-free for the team.
Set this up in your repository today to safeguard your code audit trail!