RuboCop Gradual is a tool that helps track down and fix RuboCop offenses in your code gradually. It's a more flexible alternative to RuboCop's --auto-gen-config
option.
RuboCop Gradual:
Gain full control of gradual improvements: just add rubocop-gradual
and use it as proxy for rubocop
.
Install the gem and add to the application's Gemfile by executing:
$ bundle add rubocop-gradual
Run RuboCop Gradual to create a lock file (defaults to .rubocop_gradual.lock
):
$ rubocop-gradual
Commit the lock file to the project repository to keep track of all non-fixed offenses.
Run rubocop-gradual
before commiting changes to update the lock file. RuboCop Gradual will keep updating the lock file to keep track of all non-fixed offenses, but it will throw an error if there are any new offenses.
Proposed workflow:
rubocop_todo.yml
if it exists.rubocop-gradual
to generate a lock file and commit it to the project repository.rubocop-gradual --check
to your CI pipeline instead of rubocop
/standard
. It will throw an error if the lock file is out of date.rubocop-gradual
to update the lock file, or rubocop-gradual -a
to run autocorrection for all new and changed files and then update the lock file.rubocop-gradual
as a pre-commit hook to your repository (using lefthook, for example).rubocop-gradual --force-update
. -U, --force-update Force update Gradual lock file.
--check Check Gradual lock file is up-to-date.
-a, --autocorrect Autocorrect offenses (only when it's safe).
-A, --autocorrect-all Autocorrect offenses (safe and unsafe).
--gradual-file FILE Specify Gradual lock file.
-v, --version Display version.
-h, --help Prints this help.
To use built-in Rake tasks add the following to your Rakefile:
# Rakefile
require "rubocop/gradual/rake_task"
RuboCop::Gradual::RakeTask.new
This will add rake tasks:
bundle exec rake -T
rake rubocop_gradual # Run RuboCop Gradual
rake rubocop_gradual:autocorrect # Run RuboCop Gradual with autocorrect (only when it's safe)
rake rubocop_gradual:autocorrect_all # Run RuboCop Gradual with autocorrect (safe and unsafe)
rake rubocop_gradual:check # Run RuboCop Gradual to check the lock file
rake rubocop_gradual:force_update # Run RuboCop Gradual to force update the lock file
It's possible to customize the Rake task name and options:
# Rakefile
require "rubocop/gradual/rake_task"
RuboCop::Gradual::RakeTask.new(:custom_task_name) do |task|
task.options = %w[--gradual-file custom_gradual_file.lock]
task.verbose = false
end
RuboCop Gradual supports partial linting. It's useful when you want to run RuboCop Gradual on a subset of files, for example, on changed files in a pull request:
rubocop-gradual path/to/file # run `rubocop-gradual` on a subset of files
rubocop-gradual --staged # run `rubocop-gradual` on staged files
rubocop-gradual --unstaged # run `rubocop-gradual` on unstaged files
rubocop-gradual --commit origin/main # run `rubocop-gradual` on changed files since the commit
# it's possible to combine options with autocorrect:
rubocop-gradual --staged --autocorrect # run `rubocop-gradual` with autocorrect on staged files
RuboCop Gradual can be used in "Require mode", which is a way to replace rubocop
with rubocop-gradual
:
# .rubocop.yml
require:
- rubocop/gradual/patch
Now base rubocop
command will run rubocop-gradual
:
rubocop # run `rubocop-gradual`
rubocop -a # run `rubocop-gradual` with autocorrect (only when it's safe)
rubocop -A # run `rubocop-gradual` with autocorrect (safe and unsafe)
rubocop gradual check # run `rubocop-gradual` to check the lock file
rubocop gradual force_update # run `rubocop-gradual` to force update the lock file
To set a custom path to Gradual lock file, add --gradual-file FILE
to a special .rubocop-gradual
file:
# .rubocop-gradual
--rubocop-gradual-file path/to/my_lock_file.lock
To temporarily disable RuboCop Gradual, prepend command with NO_GRADUAL=1
:
NO_GRADUAL=1 rubocop # run `rubocop`
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
.
Bug reports and pull requests are welcome on GitHub at https://github.com/skryukov/rubocop-gradual
The gem is available as open source under the terms of the MIT License.