Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -22,8 +22,9 @@ panvimdoc:
lint:
stylua --check lsp/ lua/ tests/

# the C locale keeps panvimdoc from mangling emoji when it uppercases headings
docs: panvimdoc
$(PANVIMDOC_DIR)/panvimdoc.sh \
LC_ALL=C $(PANVIMDOC_DIR)/panvimdoc.sh \
--project-name ruby-lsp.nvim \
--input-file README.md \
--vim-version "NVIM v0.12.0" \
Expand Down
43 changes: 40 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,25 +59,59 @@ Don't lazy-load the plugin. Its `lsp/ruby_lsp.lua` must be on the runtimepath be

If you're upgrading and already start Ruby LSP yourself, remove your `vim.lsp.enable("ruby_lsp")` call and your `fullTestDiscovery` setting. Or set `lsp.auto_start = false` and keep your `vim.lsp.enable("ruby_lsp")` call, as long as the plugin still isn't lazy-loaded.

## 🔍 Code Lenses

The plugin turns on code lenses in buffers Ruby LSP is attached to, so **Run**, **Run In Terminal**, and **Debug** show above your tests. Run the lens on the cursor line with `grx`, Neovim's default mapping for `vim.lsp.codelens.run()`. To use a different key, map it yourself:

```lua
vim.keymap.set("n", "<leader>cl", vim.lsp.codelens.run, { desc = "run code lens" })
```

Set `codelens = false` to leave code lenses to your own config. With it on, the plugin enables code lenses for every server attached to a Ruby buffer, which overrides a global `vim.lsp.codelens.enable(false)` there.

## 🖥️ Ruby LSP Server

The plugin configures and starts Ruby LSP for you, in any project with a `Gemfile` or `.git` directory. You don't need nvim-lspconfig or a `ruby_lsp` config of your own. If nvim-lspconfig is installed, its config merges with the plugin's without conflict.

Before starting, the plugin checks that `ruby-lsp --version` runs from the project root. If you set `cmd` to a list such as `{ "bundle", "exec", "ruby-lsp" }`, it only checks that the first entry is executable. When the check fails, the server stays off and nothing is shown. Run `:checkhealth ruby-lsp` to see why.

Set `lsp.auto_start` to choose where the server starts. `true` starts it in every Ruby project, and `false` leaves it to you to call `vim.lsp.enable("ruby_lsp")`. A function decides per project. This one skips projects that use solargraph:
### Starting the Ruby LSP server yourself

By default the plugin starts the Ruby LSP server in every Ruby project. To start the server yourself instead, set `lsp.auto_start = false` and call `vim.lsp.enable("ruby_lsp")` when you want it:

```lua
require("ruby-lsp").setup({
lsp = {
auto_start = false,
},
})

vim.lsp.enable("ruby_lsp")
```

### Choosing which projects start the Ruby LSP server (optional)

`lsp.auto_start` also takes a function. It receives the project root and returns whether to start the Ruby LSP server there. For example, if some of your projects bundle solargraph and you want solargraph to handle those, skip Ruby LSP when `Gemfile.lock` lists it:

```lua
require("ruby-lsp").setup({
lsp = {
auto_start = function(root_dir)
return vim.fn.filereadable(root_dir .. "/.solargraph.yml") == 0
local lockfile = root_dir .. "/Gemfile.lock"
if vim.fn.filereadable(lockfile) == 0 then
return true
end
return not vim.iter(vim.fn.readfile(lockfile)):any(function(line)
return line:match("^%s+solargraph%f[^%w_-]") ~= nil
end)
end,
},
})
```

To customize the server, use `after/lsp/ruby_lsp.lua` or `vim.lsp.config("ruby_lsp", { ... })`. Your settings merge on top of the plugin's:
### Customizing the Ruby LSP server

Use `after/lsp/ruby_lsp.lua` or `vim.lsp.config("ruby_lsp", { ... })`. Your settings merge on top of the plugin's:

```lua
vim.lsp.config("ruby_lsp", {
Expand Down Expand Up @@ -165,6 +199,9 @@ require("ruby-lsp").setup({
auto_start = true,
},

-- Show code lenses in buffers Ruby LSP is attached to
codelens = true,

-- Add :RubyLsp* user commands to buffers Ruby LSP is attached to
user_commands = false,
})
Expand Down
90 changes: 69 additions & 21 deletions doc/ruby-lsp.nvim.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
*ruby-lsp.nvim.txt*
For NVIM v0.12.0 Last change: 2026 October 31
For NVIM v0.12.0 Last change: 2026 November 01

==============================================================================
Table of Contents *ruby-lsp.nvim-table-of-contents*
Expand All @@ -8,7 +8,8 @@ Table of Contents *ruby-lsp.nvim-table-of-contents*
- 💡 Why |ruby-lsp.nvim-ruby-lsp.nvim-💡-why|
- 📝 Commands |ruby-lsp.nvim-ruby-lsp.nvim-📝-commands|
- 📋 Requirements |ruby-lsp.nvim-ruby-lsp.nvim-📋-requirements|
- 🛠️ Installation |ruby-lsp.nvim-ruby-lsp.nvim-���-️-installation|
- 🛠️ Installation |ruby-lsp.nvim-ruby-lsp.nvim-🛠️-installation|
- 🔍 Code Lenses |ruby-lsp.nvim-ruby-lsp.nvim-🔍-code-lenses|
- 🖥️ Ruby LSP Server|ruby-lsp.nvim-ruby-lsp.nvim-🖥️-ruby-lsp-server|
- 🧪 Neotest |ruby-lsp.nvim-ruby-lsp.nvim-🧪-neotest|
- 🐞 Debugging |ruby-lsp.nvim-ruby-lsp.nvim-🐞-debugging|
Expand All @@ -28,7 +29,7 @@ this plugin they actually do something: run through neotest
with nvim-dap <https://github.com/mfussenegger/nvim-dap>.


П�� WHY *ruby-lsp.nvim-ruby-lsp.nvim-💡-why*
💡 WHY *ruby-lsp.nvim-ruby-lsp.nvim-💡-why*

Ruby LSP’s code lenses call client-side commands like `rubyLsp.runTest` and
`rubyLsp.debugTest`. VS Code’s Ruby LSP extension implements them, but Neovim
Expand All @@ -40,7 +41,7 @@ neotest adapter and an rdbg debug adapter that use Ruby LSP to find and run
your tests.


П�� COMMANDS *ruby-lsp.nvim-ruby-lsp.nvim-📝-commands*
📝 COMMANDS *ruby-lsp.nvim-ruby-lsp.nvim-📝-commands*

-----------------------------------------------------------------------
Command What it does
Expand Down Expand Up @@ -81,7 +82,7 @@ attached to:
the buffer in the quickfix list
-----------------------------------------------------------------------

П�� REQUIREMENTS *ruby-lsp.nvim-ruby-lsp.nvim-📋-requirements*
📋 REQUIREMENTS *ruby-lsp.nvim-ruby-lsp.nvim-📋-requirements*

- Neovim >= 0.12
- Ruby LSP <https://github.com/Shopify/ruby-lsp> >= 0.23.0, installed with `gem install ruby-lsp`. With a Ruby version manager, install it once for each Ruby version you use.
Expand All @@ -95,7 +96,7 @@ OPTIONAL ~
- ruby-lsp-rspec <https://github.com/st0012/ruby-lsp-rspec> in your Gemfile for RSpec projects. Minitest works out of the box.


П��ϸ� INSTALLATION *ruby-lsp.nvim-ruby-lsp.nvim-���-️-installation*
🛠️ INSTALLATION *ruby-lsp.nvim-ruby-lsp.nvim-🛠️-installation*

With lazy.nvim <https://github.com/folke/lazy.nvim>:

Expand All @@ -118,7 +119,23 @@ If you’re upgrading and already start Ruby LSP yourself, remove your
long as the plugin still isn’t lazy-loaded.


П��ϸ� RUBY LSP SERVER *ruby-lsp.nvim-ruby-lsp.nvim-🖥️-ruby-lsp-server*
🔍 CODE LENSES *ruby-lsp.nvim-ruby-lsp.nvim-🔍-code-lenses*

The plugin turns on code lenses in buffers Ruby LSP is attached to, so **Run**,
**Run In Terminal**, and **Debug** show above your tests. Run the lens on the
cursor line with `grx`, Neovim’s default mapping for
`vim.lsp.codelens.run()`. To use a different key, map it yourself:

>lua
vim.keymap.set("n", "<leader>cl", vim.lsp.codelens.run, { desc = "run code lens" })
<

Set `codelens = false` to leave code lenses to your own config. With it on, the
plugin enables code lenses for every server attached to a Ruby buffer, which
overrides a global `vim.lsp.codelens.enable(false)` there.


🖥️ RUBY LSP SERVER *ruby-lsp.nvim-ruby-lsp.nvim-🖥️-ruby-lsp-server*

The plugin configures and starts Ruby LSP for you, in any project with a
`Gemfile` or `.git` directory. You don’t need nvim-lspconfig or a `ruby_lsp`
Expand All @@ -131,24 +148,52 @@ project root. If you set `cmd` to a list such as `{ "bundle", "exec",
check fails, the server stays off and nothing is shown. Run `:checkhealth
ruby-lsp` to see why.

Set `lsp.auto_start` to choose where the server starts. `true` starts it in
every Ruby project, and `false` leaves it to you to call
`vim.lsp.enable("ruby_lsp")`. A function decides per project. This one skips
projects that use solargraph:

STARTING THE RUBY LSP SERVER YOURSELF ~

By default the plugin starts the Ruby LSP server in every Ruby project. To
start the server yourself instead, set `lsp.auto_start = false` and call
`vim.lsp.enable("ruby_lsp")` when you want it:

>lua
require("ruby-lsp").setup({
lsp = {
auto_start = false,
},
})

vim.lsp.enable("ruby_lsp")
<


CHOOSING WHICH PROJECTS START THE RUBY LSP SERVER (OPTIONAL) ~

`lsp.auto_start` also takes a function. It receives the project root and
returns whether to start the Ruby LSP server there. For example, if some of
your projects bundle solargraph and you want solargraph to handle those, skip
Ruby LSP when `Gemfile.lock` lists it:

>lua
require("ruby-lsp").setup({
lsp = {
auto_start = function(root_dir)
return vim.fn.filereadable(root_dir .. "/.solargraph.yml") == 0
local lockfile = root_dir .. "/Gemfile.lock"
if vim.fn.filereadable(lockfile) == 0 then
return true
end
return not vim.iter(vim.fn.readfile(lockfile)):any(function(line)
return line:match("^%s+solargraph%f[^%w_-]") ~= nil
end)
end,
},
})
<

To customize the server, use `after/lsp/ruby_lsp.lua` or
`vim.lsp.config("ruby_lsp", { ... })`. Your settings merge on top of the
plugin’s:

CUSTOMIZING THE RUBY LSP SERVER ~

Use `after/lsp/ruby_lsp.lua` or `vim.lsp.config("ruby_lsp", { ... })`. Your
settings merge on top of the plugin’s:

>lua
vim.lsp.config("ruby_lsp", {
Expand All @@ -162,7 +207,7 @@ If you override `root_dir`, your function replaces the plugin’s start checks,
including `lsp.auto_start` and the check that `ruby-lsp` runs.


П�� NEOTEST *ruby-lsp.nvim-ruby-lsp.nvim-🧪-neotest*
🧪 NEOTEST *ruby-lsp.nvim-ruby-lsp.nvim-🧪-neotest*

The neotest adapter finds tests with Ruby LSP and runs the commands Ruby LSP
resolves for them, so it works the same for Minitest and RSpec, in Rails apps
Expand All @@ -181,7 +226,7 @@ results show up in neotest’s signs, summary, and output. **Run In Terminal**
always uses a terminal.


П�� DEBUGGING *ruby-lsp.nvim-ruby-lsp.nvim-🐞-debugging*
🐞 DEBUGGING *ruby-lsp.nvim-ruby-lsp.nvim-🐞-debugging*

When nvim-dap is installed, the plugin registers a `ruby` debug adapter that
starts your tests under rdbg. The **Debug** code lens uses it, and the plugin
Expand All @@ -205,7 +250,7 @@ adapter is already registered under the `dap.adapter` name, since they depend
on its own adapter.


š�ϸ� OPTIONS *ruby-lsp.nvim-ruby-lsp.nvim-⚙️-options*
⚙️ OPTIONS *ruby-lsp.nvim-ruby-lsp.nvim-⚙️-options*

These are the defaults. You only need to pass the ones you want to change.

Expand Down Expand Up @@ -253,13 +298,16 @@ These are the defaults. You only need to pass the ones you want to change.
auto_start = true,
},

-- Show code lenses in buffers Ruby LSP is attached to
codelens = true,

-- Add :RubyLsp* user commands to buffers Ruby LSP is attached to
user_commands = false,
})
<


П�� HEALTH CHECK *ruby-lsp.nvim-ruby-lsp.nvim-🩺-health-check*
🩺 HEALTH CHECK *ruby-lsp.nvim-ruby-lsp.nvim-🩺-health-check*

>
:checkhealth ruby-lsp
Expand All @@ -270,7 +318,7 @@ It reports whether `ruby-lsp` runs from the current project, the
the plugin can use.


П�� DEVELOPMENT *ruby-lsp.nvim-ruby-lsp.nvim-🔧-development*
🔧 DEVELOPMENT *ruby-lsp.nvim-ruby-lsp.nvim-🔧-development*

One-time setup to enable the local git hooks:

Expand All @@ -289,7 +337,7 @@ requires pandoc <https://pandoc.org/installing.html>.
<


П�� ACKNOWLEDGEMENTS *ruby-lsp.nvim-ruby-lsp.nvim-🙏-acknowledgements*
🙏 ACKNOWLEDGEMENTS *ruby-lsp.nvim-ruby-lsp.nvim-🙏-acknowledgements*

Thank you to the Ruby LSP <https://github.com/Shopify/ruby-lsp> team for such a
great tool. This isn’t an official Ruby LSP project, just my work to make
Expand Down
2 changes: 2 additions & 0 deletions lua/ruby-lsp/config.lua
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,8 @@ local defaults = {
auto_start = true,
},

codelens = true,

user_commands = false,
}

Expand Down
1 change: 1 addition & 0 deletions lua/ruby-lsp/health.lua
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,7 @@ local function check_install(root)
else
vim.health.info('auto_start: ' .. (auto_start and 'on' or 'off'))
end
vim.health.info('codelens: ' .. (config.get().codelens and 'on' or 'off'))

if bundles_ruby_lsp(root) then
vim.health.warn('ruby-lsp is in ' .. root .. '/Gemfile.lock', {
Expand Down
8 changes: 7 additions & 1 deletion lua/ruby-lsp/init.lua
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,13 @@ function M.setup(opts)
return
end
-- per buffer, so it runs before the per-client guard below
if config.get().user_commands then
local cfg = config.get()
-- scoped to the buffer only: with client_id, Neovim records the flag on the
-- client, so is_enabled({ bufnr }) is false and the lenses outlive the client
if cfg.codelens then
vim.lsp.codelens.enable(true, { bufnr = ev.buf })
end
if cfg.user_commands then
require('ruby-lsp.user_commands').attach(client, ev.buf)
end
if client._ruby_lsp_nvim_attached then
Expand Down
4 changes: 4 additions & 0 deletions tests/config_spec.lua
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,10 @@ describe('config', function()
it('leaves user commands off by default', function()
assert.is_false(config.get().user_commands)
end)

it('enables code lenses by default', function()
assert.is_true(config.get().codelens)
end)
end)

describe('setup', function()
Expand Down
10 changes: 10 additions & 0 deletions tests/health_spec.lua
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,16 @@ describe('health', function()
assert.truthy(find('info', 'auto_start: function'))
end)

it('reports the codelens setting', function()
health.check()
assert.truthy(find('info', 'codelens: on'))

reports = {}
config.setup({ codelens = false })
health.check()
assert.truthy(find('info', 'codelens: off'))
end)

it('places the checks after the Neovim version check', function()
health.check()

Expand Down
Loading
Loading