Including and Excluding Files

RuboCop does a recursive file search starting from the directory it is run in, or directories given as command line arguments. Files that match any pattern listed under AllCops/Include and extensionless files with a hash-bang (#!) declaration containing one of the known ruby interpreters listed under AllCops/RubyInterpreters are inspected, unless the file also matches a pattern in AllCops/Exclude. Hidden directories (i.e., directories whose names start with a dot) are not searched by default.

Here is an example that might be used for a Rails project:

AllCops:
  Exclude:
    - 'db/**/*'
    - 'config/**/*'
    - 'script/**/*'
    - 'bin/{rails,rake}'
    - !ruby/regexp /old_and_unused\.rb$/

# other configuration
# ...

When inspecting a certain directory (or file) given as RuboCop’s command line arguments, patterns listed under AllCops / Exclude are also inspected. If you want to apply AllCops / Exclude rules in this circumstance, add --force-exclusion to the command line argument.

Here is an example:

# .rubocop.yml
AllCops:
  Exclude:
    - foo.rb

If foo.rb is specified as a RuboCop’s command line argument, the result is:

# RuboCop inspects foo.rb.
$ bundle exec rubocop foo.rb

# RuboCop does not inspect foo.rb.
$ bundle exec rubocop --force-exclusion foo.rb

Path relativity

In .rubocop.yml and any other configuration file beginning with .rubocop, files, and directories are specified relative to the directory where the configuration file is. In configuration files that don’t begin with .rubocop, e.g. our_company_defaults.yml, paths are relative to the directory where rubocop is run.

This affects cops that have customisable paths: if the default is db/migrate/*.rb, and the cop is enabled in db/migrate/.rubocop.yml, the path will need to be explicitly set as *.rb, as the default will look for db/migrate/db/migrate/*.rb. This is unlikely to be what you wanted.

Unusual files, that would not be included by default

RuboCop comes with a comprehensive list of common ruby file names and extensions. But, if you’d like RuboCop to check files that are not included by default, you’ll need to pass them in on the command line, or add entries for them under AllCops/Include.

Your configuration files override RuboCop’s defaults. In the following example, we want to include foo.unusual_extension, but we also must copy any other patterns we need from the overridden default.yml.

AllCops:
  Include:
    - foo.unusual_extension
    - '**/*.rb'
    - '**/*.gemfile'
    - '**/*.gemspec'
    - '**/*.rake'
    - '**/*.ru'
    - '**/Gemfile'
    - '**/Rakefile'

This behavior of Include (overriding default.yml) was introduced in 0.56.0 via #5882. This change allows people to include/exclude precisely what they need to, without the defaults getting in the way.

Using `inherit_mode` instead

inherit_mode:
  merge:
    - Include

AllCops:
  Include:
    - foo.unusual_extension

See "Merging arrays using inherit_mode".

Deprecated patterns

Patterns that are just a file name, e.g. Rakefile, will match that file name in any directory, but this pattern style is deprecated. The correct way to match the file in any directory, including the current, is **/Rakefile.

The pattern config/** will match any file recursively under config, but this pattern style is deprecated and should be replaced by config/**/*.

`Include` and `Exclude` are relative to their directory

The Include and Exclude parameters are special. They are valid for the directory tree starting where they are defined. They are not shadowed by the setting of Include and Exclude in other .rubocop.yml files in subdirectories. This is different from all other parameters, which follow RuboCop’s general principle that configuration for an inspected file is taken from the nearest .rubocop.yml, searching upwards.

This behavior will be overridden if you specify the --ignore-parent-exclusion command line argument.

Cop-specific `Include` and `Exclude`

Cops can be run only on specific sets of files when that’s needed (for instance you might want to run some Rails model checks only on files whose paths match app/models/*.rb). All cops support the Include param.

Rails/HasAndBelongsToMany:
  Include:
    - app/models/*.rb

Cops can also exclude only specific sets of files when that’s needed (for instance you might want to run some cop only on a specific file). All cops support the Exclude param.

Rails/HasAndBelongsToMany:
  Exclude:
    - app/models/problematic.rb