= Autocorrect
:page-aliases: auto_correct.adoc

In autocorrect mode, RuboCop will try to automatically fix offenses.

There are three autocorrect modes:

|===
| Flag | Description

| `-a` / `--autocorrect`
| Safe corrections only — won't change code semantics.

| `-A` / `--autocorrect-all`
| All corrections, including unsafe ones that may change semantics.

| `-x` / `--fix-layout`
| Layout (formatting) corrections only — never changes logic.
|===

TIP: Always review the diff and run your test suite after autocorrecting,
especially when using `-A`.

== Safe vs. unsafe

RuboCop distinguishes between safe and unsafe cops and autocorrections:

* *Safe* (`true/false`) — indicates whether the cop can yield false positives
by design.
* *SafeAutoCorrect* (`true/false`) — indicates whether the autocorrection
preserves code semantics. If a cop itself is unsafe, its autocorrect is
automatically considered unsafe as well.

When you run `rubocop -a`, cops and autocorrections marked as unsafe are
skipped. When you run `rubocop -A`, everything is applied.

NOTE: Some cops may not yet be annotated for safety. Eventually, the safety
of each cop will be specified in the default configuration.

=== Example: unsafe cop

[source,ruby]
----
class Miner
  def dig(how_deep)
    # ...
  end
end


Miner.new.dig(42) # => Style/SingleArgumentDig
                  # => Use Miner.new[] instead of dig
----

This is the wrong diagnostic; this (contrived) use of `dig` is not an issue,
and there might not be an alternative. This cop is marked as `Safe: false`.

=== Example: safe cop with unsafe autocorrect

[source,ruby]
----
# example.rb:
str = 'hello' # => Missing magic comment `# frozen_string_literal: true`
str << 'world'

# autocorrects to:
# frozen_string_literal: true

str = 'hello'
str << 'world' # => now fails because `str` is frozen

# must be manually corrected to:
# frozen_string_literal: true

str = +'hello' # => We want an unfrozen string literal here...
str << 'world' # => ok
----

This diagnostic is valid since the magic comment is indeed missing (thus `Safe: true`),
but the autocorrection is not; some string literals need to be prefixed with `+` to avoid
having them frozen.

== Disabling uncorrectable offenses

[source,sh]
----
$ rubocop --autocorrect --disable-uncorrectable
----

The `--disable-uncorrectable` flag generates `# rubocop:todo` comments in the
code to suppress reporting of offenses that could not be corrected
automatically. This is useful for gradually adopting new cops.

== Configuring autocorrect per cop

Individual cops can have their autocorrect behavior configured in `.rubocop.yml`.
See xref:configuration/cop_settings.adoc#autocorrect[AutoCorrect] for the
available settings: `always`, `contextual`, and `disabled`.
