How should we roll out repository-wide formatting without making history and open branches painful?

Roll out repository-wide formatting as a single planned migration. The reliable pattern is to pin the formatter version and config, define ignore rules first, land one mechanical formatting commit with no semantic edits, record that commit in a blame-ignore file, and only then enforce formatting in CI. That keeps review noise contained, preserves day-to-day blame usefulness, and gives open branches one clear reconciliation point.

What rollout pattern works best?

Separate migration logistics from formatter choice. Pick the formatter and exact settings first, then freeze them for the migration. If you change the version or rules during rollout, you create a second wave of mechanical churn.

Define excluded files in .prettierignore before rewriting the repository. Prettier also respects .gitignore, so check that the combined rules cover the intended files (Prettier ignore docs). Commit the pinned formatter version, configuration, and exclusions as a preparation step.

Then make one formatting-only commit. Do not mix in refactors, renames, dependency updates, or behavior fixes. The value of the migration comes from having one obvious boundary that every engineer can recognize in history and rebase around.

How do we keep Git history and blame usable?

Do not try to avoid the formatting commit. Make it explicit and teach blame to skip it. The Git documentation for git blame includes both --ignore-rev and --ignore-revs-file in the command synopsis (git-blame documentation). That is the right mechanism for a repository-wide formatting commit.

A practical team workflow is to add a root .git-blame-ignore-revs file containing the formatting commit SHA and document that developers should configure their tools to use it where supported. This does not rewrite history; it changes annotation behavior so investigation still points to the prior semantic change instead of the mechanical rewrite.

When should formatting enforcement start?

Define exactly when enforcement starts. Before the migration commit lands, formatting checks mostly generate baseline noise. After it lands, formatting checks become a clean guardrail.

Use this sequence:

1. Commit formatter version, config, and .prettierignore.
2. Pause merges briefly or pick a low-traffic window.
3. Run the formatter across the repo.
4. Commit that output alone.
5. Add the formatting commit SHA to .git-blame-ignore-revs.
6. Turn on CI formatting checks for future changes.

Prerequisites: one integration branch, authority to coordinate a short cutover, and no active release freeze.

Run the repository’s pinned formatting command, inspect the resulting diff, and create the mechanical commit. Record its actual full commit hash in .git-blame-ignore-revs in a subsequent commit; a commit cannot contain its own final hash. Configure the team’s blame tooling to read that file.

When should you delay or narrow the migration?

Delay it during release stabilization, while major file moves are in flight, or when several long-lived branches already diverge heavily. In those cases, format one subtree at a time or wait for a calmer merge window. This advice is about rollout mechanics; it does not help if the team is still debating formatter rules.

What should the team verify before adopting this workflow?

Verify the pinned formatter version, the ignore list, the exact cutover window, and that the formatting commit contains no semantic edits. Next step: open a preparatory PR with only the pinned formatter, config, and ignore files, then schedule the mechanical formatting commit immediately after that PR merges.

Reviewed: 2026-09-05