Rubocop and Rails: Getting started

Feeling good about your Rails project? Think your Ruby code is ready for a peer review? I have a cure for those warm and fuzzy feelings – run it through a lint program or two.

Enter rubocop. (A serious mood killer.) I also added haml-lint to the party. (Ouch!)

Actually, true confession, I’ve always loved style guides and lint tools. They appeal to the tidiness freak in me. Plus anyone who’s been coding professionally for even a short time has picked up someone else’s code and wished like crazy the previous coder had followed a style guide (of any kind!) And before scoffing at how pedantic a strong lint tool can be, think of it as an environmental issue – leaving the planet of code cleaner, healthier and a better place than you found it.

The following are the steps I took to clean-up a small Rails4/Ruby2 project along with some tips.

Kudos, btw, to rubocop for having a really useful README. It’s worth a read before going any further. If you get stuck, it’s the first place to check.


1. Clean start

Make sure there aren’t any outstanding, uncommitted changes in the code you’re working with. You’ll need to be able to revert to your starting files if something goes wrong. (And it probably will given the tedious, mind-numbing corrections you’re about to make. Typos happen.)

Reality check: If your Rails project isn’t already parked in git or SVN or some kind of source code control scheme, go do that first. Lint is not your biggest problem.


2. Install gems

Install the rubocop gem. I’m using HAML so I also installed the haml-lint gem.

Or, like I did, add them to your Gemfile if bundler is better for your workflow.

At this point, if you just can’t help yourself, run rubocop -RD from the root of your Rails project. Chances are you’re watching a steady stream of violation messages. Don’t despair, it’s (probably) not as bad as it looks. (Plus think of how virtuous you’re going to feel when this is all cleaned up.)


3. Create a .rubocop.yml config file

a. Add an empty .rubocop.yml file to the root of your Rails project source.
b. Run rubocop --auto-gen-config. The .rubocop-todo.yml file generated contains a list of the failed lint checks with a count and the check disabled. This allows you to enable each lint check individually.
c. Add the line

to the top of your .rubocop.yml file.
d. Add the inclusions and exclusions recommended by rubocop for a Rails project.

This is the .rubocop.yml that I started with:


4. Run, fix, test and repeat. And repeat. And repeat. And repeat …

There’s no right or wrong way to do this. It’s just a matter of plowing through the work, repeating the cycle of

  • enabling a lint check in .rubocop-todo.yml,
  • running rubocop,
  • fixing, adjusting or disabling the violations that appear,
  • and periodically running your tests to make sure no errors were introduced.

Then repeat this cycle with haml-lint.

When you’re done, remove the rubocop-todo.yml line from the top of .rubocop.yml.



(a) Start working with rubocop without the -R option. Once that’s clean, turn on the Rails specific checks. The Rails violations are probably going to require a little more thought and investigation.

(b) The -D option is very useful since it connects the violation message to the lint check that failed. (Not sure why it’s not on by default?)

(c) Try to avoid creating multiple .rubocop.yml files. Ask yourself first, is this really necessary or am I being lazy?

(d) One set of files that does need a custom .rubocop.yml file is Rspec. I ended up with the following at the root of the Rspec files:

The violations generated by some of Rspec’s standard formatting are okay to ignore and could obscure any real issues. Don’t forget to inherit the main .rubocop.yml file.

(e) There are going to be rules that you decide you just don’t care about, flat out disagree with or will take care of later. For those, transfer the lint check from the rubocop-todo.yml file to the main .rubocop.yml file with a comment on why it’s there. (Your future self with thank you.)

(f) I didn’t use the --auto-correct option since I wanted to understand exactly what was being modified. But that doesn’t mean that grep and sed can be your friend. For example:


They are your friend until they’re not! Be sure to limit the name and/or location of any mass search and replace. For example, doing a too broad search/replace for spaces can harm your git repository if you’re not careful.

(g) If you get stumped on what to do about a failing lint check, look for comments and options in the rubocop config files: default.yml, disabled.yml and enabled.yml.

(h) When I found individual lines or methods that needed more work, I added

to the source. Then found them later using a simple

(i) Thankfully haml-lint uses the rubocop config files.

Have other rubocop and Rails tips? Please share them in a comment below.


5. Integrate as a regular practice

The final step is to add all this to your regular work process. The following is a simple rake task that runs rubocop, haml-lint as well as rspec. Update 06/09/2014: I’ve since added reek and rails-best-practices. Overkill for sure but it’s interesting to see what they each catch. Notice that with version 0.23.0 rubocop has changed it’s module name to ‘RuboCop’.

Save the above as lib/tasks/testcode.rake and then run rake testcode.



On the first pass of a small Rails4/Ruby2 project with very little legacy, I ended up with 5 .rubocop.yml files (gist of config files) Some of the settings like MethodLength I’ll be revisiting in the future but it’s okay for now.

I also installed and tried out the ruby-lint gem but was unable to get it to generate useful output for a Rails project. Hopefully in the future this will work since it sounds like a good compliment to rubocop. (If you got it to work with Rails, please comment below. I’d love to hear how.)

Ruby Style Guide
rubocop gem
haml-lint gem

See a correction? Need more explanation? Was this helpful? Please leave a comment below.