Extensions

It’s possible to extend RuboCop with custom cops and formatters.

Loading Extensions

Besides the --require command line option you can also specify ruby files that should be loaded with the optional require directive in the .rubocop.yml file:

require:
 - ../my/custom/file.rb
 - rubocop-extension

The paths are directly passed to Kernel.require. If your extension file is not in $LOAD_PATH, you need to specify the path as relative path prefixed with ./ explicitly or absolute path. Paths starting with a . are resolved relative to .rubocop.yml.

Extension Suggestions

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 enabling it.

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

Custom Cops

You can configure the custom cops in your .rubocop.yml just like any other cop.

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.

Known Custom Cops

rubocop-performance - Performance optimization analysis
rubocop-rails - Rails-specific analysis
rubocop-rspec - RSpec-specific analysis
rubocop-minitest - Minitest-specific analysis
rubocop-thread_safety - Thread-safety analysis
rubocop-require_tools - Dynamic analysis for missing require statements
rubocop-i18n - i18n wrapper function analysis (gettext and rails-i18n)
rubocop-sequel - Code style checking for Sequel gem
cookstyle - Custom cops and config defaults for Chef Infra Cookbooks
rubocop-rake - Rake-specific analysis
rubocop-packaging - Upstream best practices and coding conventions for downstream compatibility.

Any extensions missing? Send us a Pull Request!

Custom Formatters

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 --format and --require option. For example, when you have defined MyCustomFormatter in ./path/to/my_custom_formatter.rb, you would type this command:

$ rubocop --require ./path/to/my_custom_formatter --format MyCustomFormatter