Configuring Cops

Every cop supports a set of common configuration parameters, and many cops have additional parameters specific to their behavior.

Qualifying cop name with its type, e.g., Style, is recommended, but not necessary as long as the cop name is unique across all types.

Enabled

Specific cops can be disabled by setting Enabled to false for that specific cop.

Layout/LineLength:
  Enabled: false

Most cops are enabled by default. Cops, introduced or significantly updated between major versions, are in a special pending status (read more in "Versioning"). Some cops, configured with Enabled: false in config/default.yml, are disabled by default.

Enabled also accepts preview, for a cop that is not settled enough to be pending yet. Those run only for projects that ask for them, with AllCops: Preview: true or --preview:

AllCops:
  Preview: true

Unlike pending cops, preview cops are never reported as needing a decision - opting in is the point. See "Preview" for what else the setting covers, when to reach for it instead of pending, and how it interacts with NewCops, --only and the enable-everything settings.

The cop enabling process can be altered by setting DisabledByDefault or EnabledByDefault (but not both) to true. These settings override the default for all cops to disabled or enabled, except Lint/Syntax which is always enabled, regardless of the cops' default values (whether enabled, disabled or pending).

AllCops:
  DisabledByDefault: true

All cops except Lint/Syntax are then disabled by default. Only cops appearing in user configuration files with Enabled: true will be enabled; every other cop will be disabled without having to explicitly disable them in configuration. It is also possible to enable entire departments by adding for example

Style:
  Enabled: true

All cops in the Style department are then enabled. In this case, only the cops in the Style department that are enabled by default will be enabled. The cops in the Style department that are disabled by default will remain disabled.

The same effects can be obtained from the command line using --disable-all-cops and --enable-all-cops. These options take precedence over the configuration files, which is useful when you want to inspect the source with a different cop set without modifying .rubocop.yml. Note that --disable-all-cops does not disable Lint/Syntax, which is always enabled.

If a department is disabled, cops in that department can still be individually enabled, and that setting overrides the setting for its department in the same configuration file and in any inherited file.

inherit_from: config_that_disables_the_metrics_department.yml

Metrics/MethodLength:
  Enabled: true

Style:
  Enabled: false

Style/Alias:
  Enabled: true

Severity

Every offense carries a severity, which is what --fail-level and AllCops: FailLevel filter on and what the leading letter in the default output shows. The allowed values, from lowest to highest, are info, refactor, convention, warning, error and fatal.

A cop’s default severity comes from its department:

Department Default What it says

Department	Default	What it says
`Lint`, `Security`	`warning`	The code is probably wrong: a likely bug, a security problem, or something that misbehaves at runtime. Worth failing a build over.
`Metrics`	`refactor`	A maintainability smell such as size or complexity. Something to fix deliberately, not something to be blocked by.
everything else	`convention`	A matter of style and consistency. The code works; it does not read the way the project wants it to.

Lint, Security

warning

The code is probably wrong: a likely bug, a security problem, or something that misbehaves at runtime. Worth failing a build over.

Metrics

refactor

A maintainability smell such as size or complexity. Something to fix deliberately, not something to be blocked by.

everything else

convention

A matter of style and consistency. The code works; it does not read the way the project wants it to.

info sits below all of these: offenses at that level are reported but never cause a non-zero exit, whatever the fail level.

A few cops ship with a severity other than their department’s, where a department mixes lint-like and style cops: Bundler/InsecureProtocolSource reports as a warning while Bundler/OrderedGems does not. Any cop’s severity can be changed in configuration, and so can a whole department’s:

Lint:
  Severity: error

Metrics/CyclomaticComplexity:
  Severity: warning

A cop configured this way keeps reporting exactly what it reported before; only the level changes. Which level makes the run fail is a separate setting, see Choosing what fails a run.

Lint/Syntax is the one exception to all of this: it checks for syntax errors before any other cop runs, and neither its Enabled nor its Severity (fatal) can be changed in configuration.

Details

Individual cops can be embellished with extra details in offense messages:

Layout/LineLength:
  Details: >-
    If lines are too short, text becomes hard to read because you must
    constantly jump from one line to the next while reading. If lines are too
    long, the line jumping becomes too hard because you "lose the line" while
    going back to the start of the next line. 80 characters is a good
    compromise.

These details will only be seen when RuboCop is run with the --extra-details flag or if ExtraDetails is set to true in your global RuboCop configuration.

AutoCorrect

Cops that support the --autocorrect option offer flexible settings for autocorrection. These settings can be specified in the configuration file as follows:

always
contextual
disabled

`always (Default)`

This setting enables autocorrection always by default. For backward compatibility, true is treated the same as always.

Style/PerlBackrefs:
  AutoCorrect: always # or true

`contextual`

This setting enables autocorrection when launched from the rubocop command, but it is not available through LSP. e.g., rubocop --lsp, rubocop --editor-mode, or a program where RuboCop::LSP.enable has been applied.

Inspections via the command line are treated as code that has been finalized.

Style/PerlBackrefs:
  AutoCorrect: contextual

This setting prevents autocorrection during editing in the editor, e.g., with the textDocument/formatting LSP method. However, the workspace/executeCommand LSP method, which is triggered by intentional user actions, respects the user’s intention for autocorrection.

Additionally, for cases like Metrics cops where the highlight range extends over the entire body of classes, modules, methods, or blocks, the offending range will be confined to only the name. This helps avoid redundant and noisy offenses in editor display.

`disabled`

This setting disables autocorrection. For backward compatibility, false is treated the same as disabled.

Style/PerlBackrefs:
  AutoCorrect: disabled # or false

AllowedMethods

Many cops can be configured to exclude specific methods from inspection. AllowedMethods accepts a list of method names as strings. A cop will skip any method whose name exactly matches one of the entries:

Metrics/BlockLength:
  AllowedMethods:
    - refine
    - class_methods
    - instance_methods

Only bare method names are supported — you cannot use qualified names like Foo.bar or foo.bar. Class and module names are not supported either. If you need more flexibility, use AllowedPatterns instead.

The IgnoredMethods and ExcludedMethods parameters are deprecated aliases for AllowedMethods. They still work, but you should migrate your configuration to use AllowedMethods.

AllowedPatterns

AllowedPatterns provides regex-based exclusions for cops that support it. Each entry is treated as a regular expression — strings are automatically converted via Regexp.new, so the !ruby/regexp YAML tag is optional.

Metrics/BlockLength:
  AllowedPatterns:
    # These two forms are equivalent:
    - !ruby/regexp /\b(class|instance)_methods\b/
    - '\b(class|instance)_methods\b'

What the pattern matches against depends on the cop:

Metrics cops (e.g. BlockLength, MethodLength) match against the method name.
Layout/LineLength matches against the entire source line.
Naming cops (e.g. MethodName, VariableName) match against the identifier name.

For example, to allow all methods starting with test_ in Metrics/MethodLength:

Metrics/MethodLength:
  AllowedPatterns:
    - ^test_

To allow long lines containing URLs in Layout/LineLength:

Layout/LineLength:
  AllowedPatterns:
    - '^\s*#\s*https?://'

The IgnoredPatterns parameter is a deprecated alias for AllowedPatterns. It still works, but you should migrate your configuration to use AllowedPatterns.