File: Auto Gen Config — RuboCop master

If you have a code base with an overwhelming amount of offenses, it can be a good idea to use <code>rubocop --auto-gen-config</code>, which creates <code>.rubocop_todo.yml</code> and adds <code>inherit_from: .rubocop_todo.yml</code> in your <code>.rubocop.yml</code>. The generated file <code>.rubocop_todo.yml</code> 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 <code>--exclude-limit COUNT</code>, 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 <code>--no-exclude-limit</code> option, e.g., <code>rubocop --auto-gen-config --no-exclude-limit</code>.

Working through the TODO

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

Tip	Pay attention to the comments above each entry in <code>.rubocop_todo.yml</code>. 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 <code>.rubocop_todo.yml</code> file one by one as you work through all the offenses in the code. You can also regenerate your <code>.rubocop_todo.yml</code> using the same options by running <code>rubocop --regenerate-todo</code>.

Keeping the TODO from rotting

Entries in <code>.rubocop_todo.yml</code> 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 <code>--report-unused-todo-entries</code> 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. <code>--report-unused-todo-entries</code> 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 <code>--regenerate-todo</code> 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 <code>.rubocop_todo.yml</code>. 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 <code>--auto-gen-only-exclude</code> when running with <code>--auto-gen-config</code>. 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 <code>.rubocop_todo.yml</code>, 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 <code>--no-auto-gen-enforced-style</code> option along with <code>--auto-gen-config</code>.