# 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:

```text
# 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:

```bash
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.