Auto-generating Configuration

If you have a code base with an overwhelming amount of offenses, it can be a good idea to use rubocop --auto-gen-config, which creates .rubocop_todo.yml and adds inherit_from: .rubocop_todo.yml in your .rubocop.yml. The generated file .rubocop_todo.yml contains configuration to disable cops that currently detect an offense in the code by changing the configuration for the cop, excluding the offending files, or disabling the cop altogether once a file count limit has been reached.

By adding the option --exclude-limit COUNT, e.g., rubocop --auto-gen-config --exclude-limit 5, you can change how many files are excluded before the cop is entirely disabled. The default COUNT is 15. If you don’t want the cop to be entirely disabled regardless of the number of files, use the --no-exclude-limit option, e.g., rubocop --auto-gen-config --no-exclude-limit.

Working through the TODO

The next step is to cut and paste configuration from .rubocop_todo.yml into .rubocop.yml for everything that you think is in line with your (organization’s) code style and not a good fit for a todo list.

Pay attention to the comments above each entry in .rubocop_todo.yml. They can reveal configuration parameters such as EnforcedStyle, which can be used to modify the behavior of a cop instead of disabling it completely.

Then you can start removing the entries in the generated .rubocop_todo.yml file one by one as you work through all the offenses in the code. You can also regenerate your .rubocop_todo.yml using the same options by running rubocop --regenerate-todo.

Keeping the TODO from rotting

Entries in .rubocop_todo.yml outlive their purpose silently: when an excluded file is fixed as a side effect of other work, or deleted, nothing tells you the entry is no longer needed. Running with --report-unused-todo-entries reports every Exclude entry whose cop no longer flags its file and fails the run when any are found:

$ rubocop --report-unused-todo-entries

1 unused todo entry found in `.rubocop_todo.yml`:
  Style/ClassVars: lib/fixed_file.rb

Regenerating the todo also removes stale entries, but the two commands serve opposite purposes. Regeneration re-baselines: it rewrites the whole file, and in doing so also absorbs any new offenses into the todo list - run in CI, it would legitimize every newly introduced offense. --report-unused-todo-entries only ever moves in one direction: new offenses still fail the build as usual, and stale entries fail it too until they are removed. That makes it safe to run on every CI build as a ratchet that forces the todo list to shrink over time, while --regenerate-todo remains a deliberate, local re-baselining step.

Entries for cops that are not loaded in the current run (for example, extension cops when running plain rubocop) are not judged, since the absence of their offenses proves nothing.

Another way of silencing offense reports, aside from configuration, is through source code directives. These can be added manually or automatically.

Metrics cops

The cops in the Metrics department will by default get Max parameters generated in .rubocop_todo.yml. The value of these will be just high enough so that no offenses are reported the next time you run rubocop. If you prefer to exclude files, like for other cops, add --auto-gen-only-exclude when running with --auto-gen-config. It will still change the maximum if the number of excluded files is higher than the exclude limit.

EnforcedStyle

Some cops have a configurable option named EnforcedStyle. By default, when generating the .rubocop_todo.yml, if one style is used for all files, these cops will add the settings for the style being used. If you want to exclude on a file-by-file basis, add the --no-auto-gen-enforced-style option along with --auto-gen-config.