Getting Started

This guide will get you up and running with RuboCop in a few minutes. RuboCop serves three primary roles:

  1. Code style checker (a.k.a. linter) — enforces style conventions from the Ruby Style Guide

  2. Lint tool — catches bugs and suspicious code, like a smarter ruby -w

  3. Code formatter — automatically fixes layout and formatting

First Run

After installing RuboCop, just run it from your project’s root directory:

$ rubocop

RuboCop will recursively check all Ruby files and report any offenses it finds:

Inspecting 5 files
.W.C.

Offenses:

lib/foo.rb:2:3: C: Style/IfUnlessModifier: Favor modifier if usage when having a single-line body.
  if something
  ^^
lib/bar.rb:5:5: W: Lint/UselessAssignment: Useless assignment to variable - x.
    x = 42
    ^

5 files inspected, 2 offenses detected

Each offense shows the file, line, column, severity (C for convention, W for warning, E for error), the cop name, and a description. The letter on the progress line (. = clean, C/W/E = offense found) gives you a quick overview.

Setting Up Your Project

For an existing project with many offenses, the easiest way to get started is to generate a TODO file:

$ rubocop --auto-gen-config

This creates two files:

  • .rubocop_todo.yml — temporarily disables all current offenses

  • .rubocop.yml — your configuration file (with inherit_from: .rubocop_todo.yml added)

Now rubocop will pass cleanly, and you can work through the TODO entries at your own pace. See Auto-generating Configuration for details.

For a new project, you can generate a starter config file instead:

$ rubocop --init

Customizing RuboCop

All configuration lives in .rubocop.yml. Here are a few common adjustments:

# Increase the maximum line length
Layout/LineLength:
  Max: 120

# Disable a cop entirely
Style/Documentation:
  Enabled: false

# Restrict a cop to specific files
Rails/HasAndBelongsToMany:
  Include:
    - app/models/**/*.rb

See Configuration for the full reference.

Fixing Offenses Automatically

Many cops can autocorrect the problems they find. Use -a for safe corrections only, or -A to include unsafe ones:

# Safe autocorrections only
$ rubocop -a

# All autocorrections (safe and unsafe)
$ rubocop -A

# Fix only formatting (layout) offenses
$ rubocop -x
Review the diff after running autocorrect, especially with -A. See Autocorrect for more details on safe vs. unsafe corrections.

Inspecting Only What Changed

On a large project you often care only about the code you just touched. --changed asks git which files differ and inspects those:

# Files you have modified since the last commit, including untracked ones
$ rubocop --changed

# Everything your branch changes relative to main - useful on CI
$ rubocop --changed=main

Deleted files are skipped, and Include/Exclude still apply, so the result is the intersection of "what git says changed" and "what RuboCop would inspect anyway". Paths given on the command line narrow it further, so rubocop --changed lib inspects the changed files under lib.

Two things it is good for. On a large codebase that is mid-adoption, it keeps a local run fast and focused on the code you are actually touching:

$ rubocop --changed --diff

And on CI, it holds new code to a standard the whole repository does not meet yet, without a todo file:

$ git fetch origin main --depth=1
$ rubocop --changed=origin/main
The whole file is inspected, not just the lines that changed, so a file you touched can still report an offense from a part you did not write. Tools like Pronto exist for line-level filtering.

In a repository without any commits every file counts as changed, and outside a git repository --changed reports the error rather than guessing.

Editor Integration

For the best experience, set up RuboCop in your editor so you get real-time feedback as you type. RuboCop has a built-in LSP server that works with any editor that supports the Language Server Protocol.

The recommended setup for popular editors:

  • VS Code — Install the Ruby LSP extension

  • Emacs — Use Eglot (built-in since Emacs 29) or lsp-mode

  • Vim/Neovim — Use the built-in LSP client or ALE

See Integration with Other Tools for more editors and alternative approaches.

Next Steps