mirror of
https://github.com/jimeh/rubocopfmt.el.git
synced 2026-02-19 09:06:41 +00:00
Jim Myhrberg
b4be08469c
Latest version of RuboCop now only performs auto-corrections from "safe" cops when given the `--auto-correct`/`-a` option. To run auto-corrections from all cops, including "unsafe" ones, you must now pass in `--auto-correct-all`/`-A` instead. The new `rubocopfmt-include-unsafe-cops` defcustom defaults to no `nil`, for backwards compatibility. Turn on unsafe cops by setting it to `t`.
130 lines
4.0 KiB
Markdown
130 lines
4.0 KiB
Markdown
# rubocopfmt.el
|
|
|
|
Emacs minor-mode to format Ruby code with
|
|
[RuboCop](https://github.com/bbatsov/rubocop) on save via it's `--auto-correct`
|
|
option.
|
|
|
|
## Installation
|
|
|
|
Available on MELPA as [`rubocopfmt`](https://melpa.org/#/rubocopfmt).
|
|
|
|
### use-package
|
|
|
|
```elisp
|
|
(use-package rubocopfmt
|
|
:hook
|
|
(ruby-mode . rubocopfmt-mode))
|
|
```
|
|
|
|
### package.el
|
|
|
|
```
|
|
M-x package-install rubocopfmt
|
|
```
|
|
|
|
Then add the following to your Emacs config:
|
|
|
|
```elisp
|
|
(require 'rubocopfmt)
|
|
(add-hook 'ruby-mode-hook #'rubocopfmt-mode)
|
|
```
|
|
|
|
### Manual
|
|
|
|
Place `rubocopfmt.el` somewhere into you `load-path` and require it. For example
|
|
`~/.emacs.d/vendor`:
|
|
|
|
```elisp
|
|
(add-to-list 'load-path "~/.emacs.d/vendor")
|
|
(require 'rubocopfmt)
|
|
(add-hook 'ruby-mode-hook #'rubocopfmt-mode)
|
|
```
|
|
|
|
## Usage
|
|
|
|
With `rubocopfmt-mode` enabled, Ruby buffer will automatically be formatted with
|
|
RuboCop on save.
|
|
|
|
### Unsafe Cops
|
|
|
|
RuboCop no longer runs auto-corrections for unsafe cops. To enable unsafe cops,
|
|
set `rubocopfmt-include-unsafe-cops` to `t`. If you're using use-package:
|
|
|
|
```elisp
|
|
(use-package rubocopfmt
|
|
:hook
|
|
(ruby-mode . rubocopfmt-mode)
|
|
:custom
|
|
(rubocopfmt-include-unsafe-cops t))
|
|
```
|
|
|
|
## Commands
|
|
|
|
- `rubocopfmt` - Format current buffer with RuboCop.
|
|
- `rubocopfmt-mode` - Toggle automatic formatting on save on/off.
|
|
|
|
## Internals
|
|
|
|
`rubocopfmt` works by executing `rubocop` against the file you are saving. To
|
|
ensure RuboCop behaves as expected, it is executed from within the same
|
|
directory as the file you are working on.
|
|
|
|
## Bundler Integration
|
|
|
|
If a `Gemfile` is found in the current directory or in any parent directory,
|
|
`bundle exec rubocop [...]` will be used to execute RuboCop. This does mean that
|
|
projects with a `Gemfile` are required to have `rubocop` listed as a dependency
|
|
for rubocopfmt to work.
|
|
|
|
This ensures that formatting is done with the same version of RuboCop that the
|
|
project lists as a dependency.
|
|
|
|
If you don't care about having a specific version of RuboCop and/or are using it
|
|
as an external tool, but still use a `Gemfile`, you can opt out from this
|
|
behaviour by setting `rubocopfmt-use-bundler-when-possible` to `nil`.
|
|
|
|
## Disabled Cops
|
|
|
|
There's a few of cops in RuboCop that can cause confusion and annoyance when run
|
|
against work-in-progress code. Hence `rubocopfmt` disables the worst offenders
|
|
by default. You can configure which cops are disabled by customizing the
|
|
`rubocopfmt-disabled-cops` variable.
|
|
|
|
Cops disabled by default:
|
|
|
|
- `Lint/Debugger`: Removes `debugger` statements. Not helpful when you need to
|
|
debug something.
|
|
- `Lint/UnusedBlockArgument`: Don't prefix unused block argument variable names
|
|
with `_`. This cop causes issues if you save after defining a block, but
|
|
before you use all arguments of the block.
|
|
- `Lint/UnusedMethodArgument`: Don't prefix unused method argument variable
|
|
names with `_`. This cop causes issues if you save after defining a method,
|
|
but before you use all arguments of the method.
|
|
- `Style/EmptyMethod`: Don't remove remove empty line for empty methods. This
|
|
cop is annoying if you save right after defining a new method.
|
|
|
|
## Performance
|
|
|
|
RuboCop is not very fast, often taking as much as 1-3 seconds to run. This can
|
|
be annoying, but there's a couple of options to improve performance. Both seem
|
|
to get the formatting time down to around 100-200ms just.
|
|
|
|
### rubocop-daemon
|
|
|
|
With [rubocop-daemon](https://github.com/fohte/rubocop-daemon) you end up with a
|
|
rubocop server running in the background. If you try this out, I highly
|
|
recommend using the bash script wrapper they provide, as that yields the best
|
|
possible performance.
|
|
|
|
### lsp-mode / solargraph
|
|
|
|
If you use [lsp-mode](https://github.com/emacs-lsp/lsp-mode) and
|
|
[solargraph](https://github.com/castwide/solargraph), with it configured to use
|
|
RuboCop as a reporter, then `lsp-format-buffer` should be able to format Ruby
|
|
buffers extremely fast.
|
|
|
|
`rubocopfmt-mode` can use `lsp-format-buffer` instead of `rubocopfmt` to format
|
|
buffers on save. This is currently an experimental feature, but you can turn it
|
|
on by customizing `rubocopfmt-on-save-use-lsp-format-buffer` and setting it to
|
|
`t`.
|