Git blame after massive code formatting

Running a massive, codebase-wide lint or format update using a tool like Ruff is incredibly satisfying for clean code, but it does come with a major side effect: it can completely wreck your git blame history.

Suddenly, every line changed by the formatter will show your name and the formatting commit hash, obscuring the actual author who wrote the logic.

Fortunately, Git has a built-in mechanism to handle exactly this. Here is how a mass formatting update affects your history and how to fix it.

---

1. The Problem: Polluted git blame

When you run ruff format . and commit the changes, Git sees hundreds or thousands of lines modified.

• The issue: If a teammate uses git blame to figure out why a specific line of code was written two years ago, they will only see your formatting commit from yesterday.

• The friction: They now have to waste time digging through Git history, looking at the commit prior to your formatting PR to find the actual context.

---

2. The Solution: .git-blame-ignore-revs

Git allows you to specify a list of commits that git blame should completely ignore. Instead of showing the formatting commit, Git will look through it and blame the previous author as if the formatting change never happened.

Here is how to set it up for your Ruff update:

Step 1: Create the Ignore File

In the root of your repository, create a file named .git-blame-ignore-revs.

Step 2: Add the Formatting Commit

Once your mass-formatting PR is merged, get the full SHA-1 commit hash and add it to the file with a comment:

# Mass reformatting and linting using Ruff
c3a2f8d6b8b4f12a3d4e5f6a7b8c9d0e1f2a3b4c

Step 3: Configure Git to Use the File

For this to work automatically for everyone on your team, you need to tell Git to respect this file. Run the following command in your repository:

git config blame.ignoreRevsFile .git-blame-ignore-revs

💡 Pro-Tip: Check this configuration file into your repo. To make sure your teammates don't have to run the local git config command manually, you can add it to a setup script or a Makefile that developers run when onboarding.

---

3. How it Looks in GitHub/GitLab

The major git hosting platforms support this natively:

• GitHub: Automatically detects a file named exactly .git-blame-ignore-revs in the root directory. When viewing a file's blame on GitHub, it will bypass those commits out of the box.

• GitLab: Also natively supports the .git-blame-ignore-revs file in the root repository.

---

4. Best Practices for the Ruff Update

To make this transition as seamless as possible, follow this workflow:

1. Keep it isolated: Run ruff check --fix and ruff format in a dedicated PR that contains absolutely zero manual logic changes. If you mix formatting with actual bug fixes, ignoring that commit will also ignore the history of the bug fix.

2. Warn the team: Let everyone know it's coming so they can merge their open branches beforehand. Merging a giant formatting PR can cause minor merge conflicts for open feature branches.

3. Commit the ignore file immediately: Add the commit hash to .git-blame-ignore-revs as soon as the formatting PR lands on your main branch.