rubocop-hq/rubocop

= Server Mode

NOTE: The server mode was introduced in RuboCop 1.31. If you're using an older
RuboCop version you can check out the https://github.com/fohte/rubocop-daemon[rubocop-daemon]
project that served as the inspiration for RuboCop's built-in functionality.

You can reduce the RuboCop boot time significantly (something like 850x faster) by using the `--server` command-line option.

The `--server` option speeds up the launch of the `rubocop` command by utilizing
a standalone server process that loads the RuboCop runtime production files (i.e. `require 'rubocop'`).

Normally RuboCop starts somewhat slowly because it needs to `require` a ton of files and that's fairly
slow. With the RuboCop server we sidestep this nasty issue and make it much more pleasant to
interact with RuboCop from text editors and IDEs.

NOTE: The feature cannot be used on JRuby and Windows, as they do not support the `fork` system call.

== Run with Server

There are two ways to enable server:

- `rubocop --server`: If server process has not started yet,
start server process and execute inspection with server.
- `rubocop --start-server`: Just start server process.

When the server is started, it outputs the host and port.

```console
$ rubocop --start-server
RuboCop server starting on 127.0.0.1:55772.
```

NOTE: The `rubocop` command is executed using the server process if a server is started.
Whenever a server process is not running, it will load the RuboCop runtime files and execute.
(same behavior as with RuboCop 1.30 and lower)

If a server is already running, the command only displays the server's PID. A new server will not be started.

```console
$ rubocop --start-server
RuboCop server (16060) is already running.
```

The server process name is basically `rubocop --server` and the project directory path:

```console
$ ps aux | grep 'rubocop --server'
user             16060   0.0  0.0  5078568   2264   ??  S     7:54AM   0:00.00 rubocop --server /Users/user/src/github.com/rubocop/rubocop
user             16337   0.0  0.0  5331560   2396   ??  S    23:51PM   0:00.00 rubocop --server /Users/user/src/github.com/rubocop/rubocop-rails
```

When you update and run `rubocop`, the server process will restart automatically.

```console
$ rubocop --server
RuboCop version incompatibility found, RuboCop server restarting...
RuboCop server starting on 127.0.0.1:60665.
```

If you would like to start the server in the foreground, which can be useful when running within Docker, you can pass the `--no-detach` option.

```console
$ rubocop --start-server --no-detach
```

== Restart Server

The started server does not reload the configuration file.
You will need to restart the server when you upgrade RuboCop or change
the RuboCop configuration.

```console
$ rubocop --restart-server
RuboCop server starting on 127.0.0.1:55822.
```

== Command Line Options

These are the command-line options for server operations:

|===
| Command flag | Description

| `--server`
| If a server process has not been started yet, start the server process and execute inspection with server.

| `--no-server`
| If a server process has been started, stop the server process and execute inspection without the server.

| `--restart-server`
| Restart server process.

| `--start-server`
| Start server process.

| `--stop-server`
| Stop server process.

| `--server-status`
| Show server status.

| `--no-detach`
| Run the server process in the foreground.
|===

TIP: You can specify the server host and port with the $RUBOCOP_SERVER_HOST and the $RUBOCOP_SERVER_PORT environment variables.

If `RUBOCOP_OPTS` environment variable or `.rubocop` file contains `--server` option, `rubocop` command defaults to server mode.
Other server options such as `stop-server`, `restart-server` specified on the command line will take precedence over them.

== Environment Variables

You can change the startup host and port of server process with
environment variables.

* `$RUBOCOP_SERVER_HOST`
* `$RUBOCOP_SERVER_PORT`

The following is an example:

```console
$ RUBOCOP_SERVER_PORT=98989 rubocop --start-server
```