skip to content

How do you make RuboCop run, or autocorrect, just one cop or department with --only, and skip cops with --except?

level: juniorimportance: should knowfreq 40%

answer

  1. comma-separated cop or department names
  2. -l is --only Lint
  3. --only runs a named cop even if disabled
  4. Lint/Syntax cannot be excepted
  5. pair with -a to fix one cop

basics

~10 s

Pass a comma-separated list: rubocop --only Layout/LineLength,Style/StringLiterals runs just those, --only Lint a department, and --except Metrics runs everything else. Add -a to autocorrect only that selection.

solid answer

~40 s

`--only` takes a comma-separated list of cop or department names and runs just those: `rubocop --only Style/StringLiterals`, `rubocop --only Lint`. `-l` (`--lint`) is shorthand for `--only Lint`, and `-x` is `--only Layout` plus autocorrect. `--except Metrics,Style/Documentation` runs everything **except** the named ones. Names are checked: a typo stops the run with `Unrecognized cop or department` and a *Did you mean?* suggestion. A cop named in `--only` runs even if `.rubocop.yml` disables it, which makes it handy for trying a cop out. `Lint/Syntax` is always included and cannot be excepted. Combined with `-a` or `-A`, `--only` is the standard way to autocorrect one cop at a time and commit each change separately.

code

bash · 4 lines
bash
bundle exec rubocop --only Style/StringLiterals,Style/StringLiteralsInInterpolation -a
bundle exec rubocop --only Style/Documentation --format offenses
bundle exec rubocop -l
bundle exec rubocop --except Metrics,Style/Documentation

go deeper

for a junior

Recall the comma-separated --only and --except lists, the -l shortcut for Lint, and pairing --only with -a to fix one cop.

for a middle

Explain that a named cop runs even when the config disables it, that Lint/Syntax always runs, and why redundant-directive checks skip --only runs.

for a senior

Use --only for one-cop-per-commit autocorrect and for measuring a cop before enabling it, and keep lasting decisions in .rubocop.yml.

for a principal

Keep CI and editors on the same cop set: ad hoc --except in a pipeline creates offenses that developers see locally but the gate ignores.

## Selecting cops for one run A full RuboCop run applies every enabled cop. Often you want a narrower run: to fix one kind of offense, to try a cop the project has not enabled, or to leave a noisy department out of a quick check. Two options select cops for a single run without editing `.rubocop.yml`: - **`--only COP1,COP2`** - run only the listed cops or departments. - **`--except COP1,COP2`** - run everything that would normally run, minus the listed ones. Both take a **comma-separated list with no spaces**. Entries can be qualified cop names (`Style/StringLiterals`), department names (`Lint`, `Metrics`), or unqualified cop names that RuboCop qualifies for you when they are unique. ## Shortcuts | Shortcut | Equivalent | Notes | |---|---|---| | `-l`, `--lint` | `--only Lint` | correctness cops only | | `-x`, `--fix-layout` | `--only Layout` plus autocorrect | formatting fixes only | ## Rules worth knowing 1. **Names are validated.** `rubocop --only Style/StringLiteral` stops with `Unrecognized cop or department: Style/StringLiteral.` followed by `Did you mean? Style/StringLiterals`. 2. **A named cop runs even when disabled.** If `.rubocop.yml` says `Style/Documentation: Enabled: false`, `rubocop --only Style/Documentation` still runs it, which is a quick way to see what enabling a cop would cost. A department name, by contrast, only selects that department's cops that are enabled. 3. **`Lint/Syntax` always runs.** `--only` adds it automatically, and `--except Lint/Syntax` is rejected with `Syntax checking cannot be turned off.` 4. **Redundant-directive checks are skipped.** Under `--only`, RuboCop cannot tell whether a `rubocop:disable` comment is redundant, because most cops did not run, so `Lint/RedundantCopDisableDirective` does not report; naming it in `--only` is an error. 5. **Exclusions still apply.** `--only` changes which cops run, not which files; `Exclude` settings are respected as usual. ## Typical uses - **Autocorrect one cop at a time:** `rubocop -a --only Style/StringLiterals`, run the tests, commit. Repeat per cop. Each commit is small, reviewable and revertible on its own. - **Try a cop before enabling it:** `rubocop --only Style/Documentation --format offenses` shows how many offenses it would add. - **A fast correctness check:** `rubocop -l` before pushing. - **A formatting-only change:** `rubocop -x` touches whitespace and alignment and nothing else. - **Quiet a slow department locally:** `rubocop --except Metrics` while iterating, keeping CI on the full set. ## A worked session A team wants to adopt double quotes everywhere: 1. `rubocop --only Style/StringLiterals --format offenses` shows the offense count for that one cop. 2. `rubocop --only Style/StringLiterals,Style/StringLiteralsInInterpolation -a` rewrites the quotes; both cops are safe, so `-a` is enough. 3. The test suite runs, and the change is committed alone, so reviewers see only quote changes. 4. The team sets `EnforcedStyle: double_quotes` in `.rubocop.yml` in the same commit, so the next full run agrees. The same loop - measure, correct one cop, test, commit - works for any correctable cop, and keeps each commit small enough to review and revert. ## `--only` versus configuration `--only` and `--except` are for a single invocation. A lasting decision - this project does not use `Style/Documentation` - belongs in `.rubocop.yml` as `Enabled: false`, where reviewers can see it and every tool that reads the configuration, including editors, applies it. If a CI job runs with `--except` to skip a department, the editor integration will still report those cops, and developers will see offenses the build ignores.

  • Why does rubocop --only Lint/RedundantCopDisableDirective fail?
    Deciding that a `rubocop:disable` comment is redundant requires running the cop it disables and finding nothing. Under `--only`, most cops do not run, so RuboCop cannot judge any directive and rejects that combination with `Lint/RedundantCopDisableDirective cannot be used with --only.` Run it in a full run instead.
  • What happens if you pass a department name like Style to --only?
    RuboCop runs the cops of the `Style` department that are enabled for the file, and nothing else apart from `Lint/Syntax`. Unlike naming a single cop, a department name does not switch on cops the configuration disables.

saying these in an interview costs you the question

  • --only ignores cops that .rubocop.yml disables, even when named explicitly.
  • --except Lint/Syntax skips parsing checks for faster runs.
  • A misspelled name in --only is silently ignored.
  • --only also skips the files that the other cops would inspect.
  • Use --except in CI to disable a cop permanently instead of editing the config.