Standard

Install

Getting started is as easy as gem install standard or throwing it in your project’s Gemfile:

gem "standard", group: [:development, :test]

Running Standard

Once installed, you can either run it as a CLI or as a Rake task.

The CLI is called standardrb to distinguish it from StandardJS:

$ standardrb

And the Rake task can be run if your Rakefile includes require "standard/rake". This will load the standard task, allowing you to run:

$ rake standard

Either way, Standard will inspect any Ruby files found in the current directory tree. If any errors are found, it’ll report them. If your code is standard-compliant, it will get out of your way by quietly exiting code 0.

Fixing errors

A majority of Standard’s rules can be safely fixed automatically.

# CLI
$ standardrb --fix

# Rake
$ rake standard:fix

Because we’re confident Standard’s fixes won’t change the behavior of our code, we typically run with fix enabled all the time because it saves us from having to look at and think about problems the computer can solve for us.

Applying unsafe fixes

There are a number of other rules that can be automatically remedied, but not without the risk of changing your code’s behavior. While we wouldn’t recommend running it all the time, if the CLI suggests that additional errors can be fixed unsafely, here’s how to do that:

# CLI
$ standardrb --fix-unsafely

# Rake
$ rake standard:fix_unsafely

So long as your code is checked into source control, there’s no mortal harm in running with unsafe fixes enabled. If the changes look good to you and your tests pass, then it’s probably less error prone than manually editing everything by hand.

Integrating Standard into your workflow

Because code formatting is so integral to programming productivity and linter violations risk becoming bugs if released into production, tools like Standard Ruby are only as useful as their integration into code editors and continuous integration systems.

Other tools

These tool integrations are also available:

Guard
Spring

Ignoring errors

While Standard is very strict in how each formatting and linting rule is configured, it’s mercifully flexible when you need to ignore a violation to focus on a higher priority (like, say, keeping the build running). There are a number of ways to ignore any errors, with the right answer depending on the situation.

Ignoring a line with a comment

Individual lines can be ignored with a comment directive at the end of the line. As an example, the line text = 'hi' violates two rules, Lint/UselessAssignment and Style/StringLiterals.

You could ignore one, both, or all errors with the following comments:

# Disable one error but keep Lint/UselessAssignment
text = 'hi' # standard:disable Style/StringLiterals

# Disable both errors explicitly
text = 'hi' # standard:disable Style/StringLiterals, Lint/UselessAssignment

# Disable all errors on the line with "all"
text = "hi" # standard:disable all

Ignoring multiple lines with comments

Similarly to individual lines, you can also disable multiple lines by wrapping them in comments that disable and re-enable them:

# standard:disable Style/StringLiterals, Lint/UselessAssignment
text = "hi"
puts 'bye'
# standard:enable Style/StringLiterals, Lint/UselessAssignment

Ignoring entire files and globs

You can ignore entire files and file patterns by adding them to ignore: in your project’s .standard.yml file:

ignore:
  - 'some/file/in/particular.rb'
  - 'a/whole/directory/**/*'

Ignoring specific rules in files and globs

For a given file or glob, you can even ignore only specific rules by nesting an array of the rules you’d like to ignore:

ignore:
  - 'test/**/*':
    - Layout/AlignHash

Ignoring every violation and converting them into a todo list

If you’re adopting Standard in a large codebase and you don’t want to convert everything all at once, you can work incrementally by generating a “todo” file which will cause Standard to ignore every violation present in each file of the codebase.

This way, you can gradually work through the todo list, removing ignore directives and fixing any associated errors, while also being alerted to any regressions if they’re introduced into the project.

Here are the commands you might run to get started:

# Start by clearing any auto-fixable errors:
$ standardrb --fix

# Generate a `.standard_todo.yml' to work from
$ standardrb --generate-todo

Configuring Standard

While the rules aren’t configurable, Standard offers a number of options that can be configured as CLI flags and YAML properties.

YAML options

In addition to CLI flags, Standard will search for a .standard.yml file (ascending to parent directories if the current working directory doesn’t contain one). If you find yourself repeatedly running Standard with the same CLI options, it probably makes more sense to set it once in a YAML file:

fix: true               # default: false
parallel: true          # default: false
format: progress        # default: Standard::Formatter
ruby_version: 3.0       # default: RUBY_VERSION
default_ignores: false  # default: true

ignore:                 # default: []
  - 'vendor/**/*'

plugins:                # default: []
  - standard-rails

extend_config:                # default: []
  - .standard_ext.yml

Extending Standard

Standard includes two extension mechanisms: plugins and configuration extensions. While neither can change the rules configured out-of-the-box by Standard, they can define, require, and configure additional RuboCop rules.

Both are “first-in-wins”, meaning once a rule is configured by a plugin or extension, it can’t be changed or reconfigured by a later plugin or extension. This way, each Standard plugin you add becomes a de facto “standard” of its own. Plugins have precedence over extensions as they are loaded first.

Plugins

Adding a plugin to your project is as easy as adding it to your Gemfile and specifying it in .standard.yml in the root of your project. For example, after installing standard-rails, you can configure it by adding it to plugins:

plugins:
  - standard-rails

Each plugin can be passed configuration options by specifying them in a nested hash. For example, standard-rails allows you to configure its rules for a particular version of Rails (though this will usually be detected for you automatically):

plugins:
  - standard-rails:
      target_rails_version: 7.0

You can develop your own plugins, too! Check out the lint_roller gem to learn how. For a simple example, you can look at standard-custom, which is one of the default plugins included by Standard.

Extended config files

Of course, you may want to add more rules without going to the trouble of packaging them in a plugin gem. For cases like this, you can define one or more RuboCop configuration files and then list them in your .standard.yml file under extend_config.

For example, after installing the betterlint gem from our friends at Betterment, we could create a RuboCop config file named .betterlint.yml:

require:
  - rubocop/cop/betterment.rb

Betterment/UnscopedFind:
  Enabled: true

  unauthenticated_models:
    - SystemConfiguration

And then reference it in our .standard.yml:

extend_config:
  - .betterlint.yml

Who uses Standard Ruby?

Here are a few examples of Ruby Standard-compliant teams & projects:

Does your team use Standard? Add your name to the list!

If you really want to show off, you can also add a badge to your project’s README, like this one:

[![Ruby Code Style](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/standardrb/standard)

Code of Conduct

This project follows Test Double’s code of conduct for all community interactions, including (but not limited to) one-on-one communications, public posts/comments, code reviews, pull requests, and GitHub issues. If violations occur, Test Double will take any action they deem appropriate for the infraction, up to and including blocking a user from the organization’s repositories.