It’s possible to extend RuboCop with custom (third-party) cops and formatters.
--require command line option you can also specify ruby
files that should be loaded with the optional
require directive in the
require: - ../my/custom/file.rb - rubocop-extension
The paths are directly passed to
Depending on what gems you have in your bundle, RuboCop might suggest extensions
that can be added to provide further functionality. For instance, if you are using
rspec without the corresponding
rubocop-rspec extension, RuboCop will suggest
This message can be disabled by adding the following to your configuration:
AllCops: SuggestExtensions: false
You can also opt-out of suggestions for a particular extension library as so (unspecified extensions will continue to be notified, as appropriate):
AllCops: SuggestExtensions: rubocop-rake: false
You can configure the custom cops in your
.rubocop.yml just like any
Writing your own Cops
If you’d like to create an extension gem, you can use rubocop-extension-generator.
See development to learn how to implement a cop.
The main RuboCop gem focuses on the core Ruby language and doesn’t include functionality related to any external Ruby libraries/frameworks. There are, however, many RuboCop extensions dedicated to those and a few of them are maintained by RuboCop’s Core Team.
rubocop-performance - Performance optimization analysis
rubocop-rails - Rails-specific analysis
rubocop-rspec - RSpec-specific analysis
rubocop-minitest - Minitest-specific analysis
rubocop-rake - Rake-specific analysis
rubocop-sequel - Code style checking for Sequel gem
rubocop-thread_safety - Thread-safety analysis
rubocop-require_tools - Dynamic analysis for missing
rubocop-i18n - i18n wrapper function analysis (
cookstyle - Custom cops and config defaults for Chef Infra Cookbooks
rubocop-packaging - Upstream best practices and coding conventions for downstream (e.g. Debian packages) compatibility.
rubocop-sorbet Sorbet-specific analysis
Any extensions missing? Send us a Pull Request!
Configuring an Extension
If you’re writing an extension, you can tie some of its configuration into RuboCop.
When a cop that has been released is later renamed or removed, or one of its parameters is, RuboCop can output error messages letting users know to update their configuration to the newest values. If any obsolete configurations are encountered, RuboCop will output an error message and quit.
You can tie your extension into this system by creating your own
obsoletions.yml file and letting RuboCop know where to find it:
RuboCop::ConfigObsoletion.files << File.expand_path(filename)
There are currently three types of obsoletions that can be defined for cops:
renamed: A cop was changed to have a new name, or moved to a different department.
removed: A cop was deleted (usually this is configured with
reasonwhy it was removed).
split: A cop was removed and replaced with multiple other cops.
Two additional types are available to be defined for parameter changes. These configurations can apply to multiple cops and multiple parameters at the same time (so are expressed in YAML as an array of hashes):
changed_parameters: A parameter has been renamed.
changed_enforced_styles: A previously accepted
EnforcedStylevalue has been changed or removed.
Parameter obsoletions can be set with
Example Obsoletion Configuration
config/obsoletion.yml for more examples.
All plural keys (eg.
renamed: Layout/AlignArguments: Layout/ArgumentAlignment Lint/BlockAlignment: Layout/BlockAlignment removed: Layout/SpaceAfterControlKeyword: alternatives: Layout/SpaceAroundKeyword Lint/InvalidCharacterLiteral: reason: it was never being actually triggered split: Style/MethodMissing: alternatives: - Style/MethodMissingSuper - Style/MissingRespondToMissing changed_parameters: # must be an array of hashes - cops: - Metrics/BlockLength - Metrics/MethodLength parameters: ExcludedMethods alternative: IgnoredMethods severity: warning changed_enforced_styles: # must be an array of hashes - cops: Layout/IndentationConsistency parameters: EnforcedStyle value: rails reason: > `EnforcedStyle: rails` has been renamed to `EnforcedStyle: indented_internal_methods`
You can customize RuboCop’s output format with custom formatters.
Creating a Custom Formatter
To implement a custom formatter, you need to subclass
RuboCop::Formatter::BaseFormatter and override some methods,
or implement all formatter API methods by duck typing.
Please see the documents below for more formatter API details.
Using a Custom Formatter from the Command Line
You can tell RuboCop to use your custom formatter with a combination of
For example, when you have defined
./path/to/my_custom_formatter.rb, you would type this command:
$ rubocop --require ./path/to/my_custom_formatter --format MyCustomFormatter