Rubocopping legacy applications

Published 2025-04-16

Bringing Rubocop enforcement to legacy applications can be both valuable and a headache.

Here’s a reasonable workflow:

Start with a clean slate—remove any existing Rubocop configuration.
Create a .rubocop.yml that contains your desired configuration—enable/disable cops or supply the settings to them you need. I’d suggest using the rubocop-rails-omakase gem introduced as the default Rubocop setup in Rails 8. If using that, ensure you include it in .rubocop.yml as documented in the README.

Note rubocop-rails-omakase basically disables all cops and then turns back on a selection of basic ones. It’s much more forgiving that a vanilla Rubocop setup, but for a legacy codebase this is probably appropriate.

Run rubocop -a, which will make all the changes which can be safely made.

If using rubocop-rails-omakase, it’s likely this will fix everything. Commit your changes and enjoy your green tick.

If you have outstanding issues, decide whether to fix them now, leave Rubocop failing, or ignore them (for now) by adding the appropriate ignores.

Avoiding littering git blame

The downside of performing a large scale change to the codebase like this is you end up with git blame reporting an uninteresting and irrelevant commit for most lines of the codebase. We can tell git to ignore certain commits for the purpose of blames, however.

Create a .git-blame-ignore-revs file in the root of the codebase which contains a list of commit SHAs to ignore (one per line)
Tell git about this file in your config by running git config blame.ignoreRevsFile .git-blame-ignore-revs
Update the project README to highlight this in the project setup.
I’d also suggest pointing to the README in your Rubocopping commit messages—this way if anyone sees them because they haven’t configured git, they’ll be pointed in the right direction.