RuboCop Deployment and Usage Guide

Prerequisites

• Ruby: MRI 2.7+ or JRuby 9.4+
• RubyGems: For gem installation
• Bundler (optional): For managing gem dependencies in projects

Installation

Installing RuboCop as a Gem

gem install rubocop

Installing via Bundler

Add to your Gemfile:

gem 'rubocop', require: false

For version pinning to prevent unwanted updates:

gem 'rubocop', '~> 1.82', require: false

Quick Start

Navigate to your Ruby project directory and run:

cd my/cool/ruby/project
rubocop

Using with LSP

RuboCop includes a built-in LSP server for editor integration. See the LSP documentation for setup instructions.

Configuration

Configuration Files

RuboCop uses a .rubocop.yml configuration file. You can generate a default configuration with:

rubocop --auto-gen-config

Command Line Options

Key options include:

• --stdin: Read from standard input (requires a file path argument)
• --cache: Enable caching for faster subsequent runs
• --parallel: Run analysis in parallel across multiple cores
• --auto-correct: Automatically fix offenses where possible

Environment Variables

RuboCop supports configuration via environment variables through ArgumentsEnv. Common variables include:

• RUBOCOP_OPTS: Additional options passed to RuboCop
• RUBOCOP_CACHE: Controls caching behavior

Build & Run

Local Development

Since RuboCop is a Ruby gem, there's no compilation step. To run locally:

# Clone the repository
git clone https://github.com/rubocop/rubocop.git
cd rubocop

# Install dependencies
bundle install

# Run RuboCop on the codebase itself
bundle exec rubocop

Running with Auto-Correction

rubocop --auto-correct

Checking Specific Files

rubocop path/to/file.rb path/to/another/file.rb

Using with STDIN

echo "def foo; end" | rubocop --stdin foo.rb

Deployment

As a Development Dependency

Add RuboCop to your project's Gemfile and run it as part of your development workflow or CI pipeline.

CI/CD Integration

Add to your .github/workflows/ci.yml:

- name: Run RuboCop
  run: bundle exec rubocop

Docker Integration

Create a Dockerfile for your Ruby application:

FROM ruby:3.1

RUN gem install rubocop

WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install

COPY . .

Troubleshooting

Common Issues

Issue: rubocop: command not found

Solution: Ensure RuboCop is installed and in your PATH. If using Bundler, use bundle exec rubocop.

Issue: "Infinite loop detected" during auto-correction

Solution: This occurs when RuboCop keeps correcting offenses back and forth. Check the specific files mentioned in the error and review the conflicting cops.

Issue: Performance issues with large codebases

Solution: Enable caching with --cache or configure parallel processing with --parallel.

Debugging

Enable verbose output:

rubocop --debug

Check RuboCop version:

rubocop --version

Compatibility Issues

RuboCop targets Ruby 2.0+ for code analysis but officially supports MRI 2.7+ and JRuby 9.4+. Ensure your runtime matches these requirements.

Configuration Problems

If RuboCop isn't behaving as expected, check:

1. Your .rubocop.yml configuration
2. Any Include/Exclude patterns in your config
3. That you're using a compatible RuboCop version with your Ruby version

Reporting Issues

For bugs or feature requests, file an issue on the GitHub repository. Include:

• RuboCop version (rubocop --version)
• Ruby version (ruby --version)
• A minimal reproducible example
• Your configuration file if relevant