rubocop --auto-gen-config: The TODO File
rubocop --auto-gen-config writes .rubocop_todo.yml that disables or limits cops to the offenses already present, so new code is held to the full rules.
Turning RuboCop on a large old codebase floods the log. The TODO file captures the current debt so CI only fails on new offenses.
What it does
rubocop --auto-gen-config inspects the project and writes .rubocop_todo.yml with an entry per offending cop, either excluding the specific files or raising the cop's threshold to the current count. The main .rubocop.yml inherits it so existing offenses pass while new ones fail.
Common usage
# generate the todo file
bundle exec rubocop --auto-gen-config
# in .rubocop.yml, inherit it
inherit_from: .rubocop_todo.yml
# regenerate with a count threshold instead of file lists
bundle exec rubocop --auto-gen-config --auto-gen-only-excludeFlags
| Flag | What it does |
|---|---|
| --auto-gen-config | Generate .rubocop_todo.yml from current offenses |
| --auto-gen-only-exclude | Use Exclude lists rather than Max thresholds |
| --exclude-limit <n> | Switch a cop to disabled past this many files |
| --no-auto-gen-timestamp | Omit the generation timestamp comment |
In CI
Commit .rubocop_todo.yml and have inherit_from pick it up so CI fails only on new offenses. Periodically pay down the debt by deleting entries and fixing those cops, then regenerate. The timestamp comment changes each run, so --no-auto-gen-timestamp keeps diffs clean.
Common errors in CI
If CI still flags old offenses, .rubocop.yml is missing the inherit_from: .rubocop_todo.yml line. "obsolete" warnings when running mean the todo file references cops renamed or removed in a RuboCop upgrade; regenerate it after bumping the gem.