= Basic Usage

RuboCop has three primary uses:

. Code style checker (a.k.a. linter)
. A replacement for `ruby -w` (a subset of its linting capabilities)
. Code formatter

In the next sections we'll briefly cover all of them.

== Code style checker

Running `rubocop` with no arguments will check all Ruby source files
in the current directory:

[source,sh]
----
$ rubocop
----

Alternatively you can pass `rubocop` a list of files and directories to check:

[source,sh]
----
$ rubocop app spec lib/something.rb
----

Here's RuboCop in action. Consider the following Ruby source code:

[source,ruby]
----
def badName
  if something
    test
    end
end
----

Running RuboCop on it (assuming it's in a file named `test.rb`) would produce the following report:

----
Inspecting 1 file
W

Offenses:

test.rb:1:1: C: Style/FrozenStringLiteralComment: Missing magic comment # frozen_string_literal: true.
def badName
^
test.rb:1:5: C: Naming/MethodName: Use snake_case for method names.
def badName
    ^^^^^^^
test.rb:2:3: C: Style/GuardClause: Use a guard clause instead of wrapping the code inside a conditional expression.
  if something
  ^^
test.rb:2:3: C: Style/IfUnlessModifier: Favor modifier if usage when having a single-line body. Another good alternative is the usage of control flow &&/||.
  if something
  ^^
test.rb:4:5: W: Layout/EndAlignment: end at 4, 4 is not aligned with if at 2, 2.
    end
    ^^^

1 file inspected, 5 offenses detected
----

=== Auto-correcting offenses

You can also run RuboCop in an auto-correct mode, where it will try to
automatically fix the problems it found in your code:

[source,sh]
----
$ rubocop -a
# or
$ rubocop --auto-correct
----

TIP: See xref:usage/auto_correct.adoc[Auto-correct] for more details.

=== Changing what RuboCop considers to be offenses

RuboCop comes with a preconfigured set of rules for each of its cops, based on the https://rubystyle.guide[Ruby Style Guide].
Depending on your project, you may wish to reconfigure a cop, tell to ignore certain files, or disable it altogether.

The most common way to change RuboCop's behaviour is to create a configuration file named `.rubocop.yml` in the
project's root directory.

For more information, see xref:configuration.adoc[Configuration].

== RuboCop as a replacement for `ruby -w`

RuboCop natively implements almost all `ruby -w` lint warning checks, and then some. If you want you can use RuboCop
simply as a replacement for `ruby -w`:

[source,sh]
----
$ rubocop -l
# or
$ rubocop --lint
----

== RuboCop as a formatter

There's a handy shortcut to run auto-correction only on code layout (a.k.a. formatting) offenses:

[source,sh]
----
$ rubocop -x
# or
$ rubocop --fix-layout
----

NOTE: This option was introduced in RuboCop 0.57.0.

== Command-line flags

For more details check the available command-line options:

[source,sh]
----
$ rubocop -h
----

|===
| Command flag | Description

| `-a/--auto-correct`
| Auto-correct offenses (only when it's safe). See xref:usage/auto_correct.adoc[Auto-correct].

| `-A/--auto-correct-all`
| Auto-correct offenses (safe and unsafe). See xref:usage/auto_correct.adoc[Auto-correct].

| `--auto-gen-config`
| Generate a configuration file acting as a TODO list.

| `--[no-]color`
| Force color output on or off.

| `-c/--config`
| Run with specified config file.

| `-C/--cache`
| Store and reuse results for faster operation.

| `-d/--debug`
| Displays some extra debug output.

| `--disable-pending-cops`
| Run without pending cops.

| `--disable-uncorrectable`
| Used with --auto-correct to annotate any offenses that do not support autocorrect with `rubocop:todo` comments.

| `-D/--[no-]display-cop-names`
| Displays cop names in offense messages. Default is true.

| `--display-only-fail-level-offenses`
| Only output offense messages at the specified `--fail-level` or above

| `--enable-pending-cops`
| Run with pending cops.

| `--except`
| Run all cops enabled by configuration except the specified cop(s) and/or departments.

| `--exclude-limit`
| Limit how many individual files `--auto-gen-config` can list in `Exclude` parameters, default is 15.

| `-E/--extra-details`
| Displays extra details in offense messages.

| `-f/--format`
| Choose a formatter, see xref:formatters.adoc[Formatters].

| `-F/--fail-fast`
| Inspect files in order of modification time and stops after first file with offenses.

| `--fail-level`
| Minimum xref:configuration.adoc#severity[severity] for exit with error code. Full severity name or upper case initial can be given. Normally, auto-corrected offenses are ignored. Use `A` or `autocorrect` if you'd like them to trigger failure.

| `--force-exclusion`
| Force excluding files specified in the configuration `Exclude` even if they are explicitly passed as arguments.

| `--only-recognized-file-types`
| Inspect files given on the command line only if they are listed in `AllCops`/`Include` parameters of user configuration or default configuration.

| `-h/--help`
| Print usage information.

| `--ignore-parent-exclusion`
| Ignores all Exclude: settings from all .rubocop.yml files present in parent folders. This is useful when you are importing submodules when you want to test them without being affected by the parent module's rubocop settings.

| `--init`
| Generate a .rubocop.yml file in the current directory.

| `-l/--lint`
| Run only lint cops.

| `-L/--list-target-files`
| List all files RuboCop will inspect.

| `--no-auto-gen-timestamp`
| Don't include the date and time when --auto-gen-config was run in the config file it generates

| `--no-offense-counts`
| Don't show offense counts in config file generated by --auto-gen-config

| `--only`
| Run only the specified cop(s) and/or cops in the specified departments.

| `-o/--out`
| Write output to a file instead of STDOUT.

| `--parallel`
| Use available CPUs to execute inspection in parallel.

| `-r/--require`
| Require Ruby file (see xref:extensions.adoc#loading-extensions[Loading Extensions]).

| `--safe`
| Run only safe cops.

| `--safe-auto-correct`
| Omit cops annotated as "not safe". See xref:auto_correct.adoc[Auto-correct].

| `--show-cops`
| Shows available cops and their configuration.

| `-s/--stdin`
| Pipe source from STDIN. This is useful for editor integration. Takes one argument, a path, relative to the root of the project. RuboCop will use this path to determine which cops are enabled (via eg. Include/Exclude), and so that certain cops like Naming/FileName can be checked.

| `-x/--fix-layout`
| Auto-correct only code layout (formatting) offenses.

| `-v/--version`
| Displays the current version and exits.

| `-V/--verbose-version`
| Displays the current version plus the version of Parser and Ruby.
|===

Default command-line options are loaded from `.rubocop` and `RUBOCOP_OPTS` and are combined with command-line options that are explicitly passed to `rubocop`.
Thus, the options have the following order of precedence (from highest to lowest):

. Explicit command-line options
. Options from `RUBOCOP_OPTS` environment variable
. Options from `.rubocop` file.

== Exit codes

RuboCop exits with the following status codes:

* `0` if no offenses are found or if the severity of all offenses are less than
`--fail-level`. (By default, if you use `--auto-correct`, offenses which are
auto-corrected do not cause RuboCop to fail.)
* `1` if one or more offenses equal or greater to `--fail-level` are found. (By
default, this is any offense which is not auto-corrected.)
* `2` if RuboCop terminates abnormally due to invalid configuration, invalid CLI
options, or an internal error.
