Migration Guide for v2

[RRethy]

Vim plugin for automatically highlighting other uses of the word under the cursor using either LSP, Tree-sitter, or regex matching. Think nvim-cursorword, vim-cursorword, or nvim-cursorword, but better.

Min Neovim Version: v0.7.2

If you have any issues, open an issue

Migration Guide

Remove any vim-illuminate configuration from your init file, simply having the plugin installed will load it and start highlighting the buffers using one of LSP, Tree-sitter, or regex matching (in that order) depending on which is available.

If you don't care to use the latest and greatest, then add let g:Illuminate_useDeprecated = 1 (or vim.g.Illuminate_useDeprecated = 1 for Lua configs) to your init file and everything will continue to work the same as before.

If you have any require('illuminate').on_attach() lines in your config currently, you can remove them since the it now finds the LSP dynamically. Leaving that line in your config is fine too, it'll just cause existing behaviour to be used instead.

You may need to update your highlight groups to use IlluminatedWordText, IlluminatedWordRead, and IlluminatedWordWrite.

More than just highlighting

You can now use <a-n> and <a-p> to jump around the references.

You can also use <a-i> as a textobject for the reference under the cursor.

Full configuration

-- default configuration
require('illuminate').configure({
    -- providers: provider used to get references in the buffer, ordered by priority
    providers = {
        'lsp',
        'treesitter',
        'regex',
    },
    -- delay: delay in milliseconds
    delay = 100,
    -- filetypes_denylist: filetypes to not illuminate, this overrides filetypes_allowlist
    filetypes_denylist = {
        'dirvish',
        'fugitive',
    },
    -- filetypes_allowlist: filetypes to illuminate, this is overriden by filetypes_denylist
    filetypes_allowlist = {},
    -- modes_denylist: modes to not illuminate, this overrides modes_allowlist
    modes_denylist = {},
    -- modes_allowlist: modes to illuminate, this is overriden by modes_denylist
    modes_allowlist = {},
    -- providers_regex_syntax_denylist: syntax to not illuminate, this overrides providers_regex_syntax_allowlist
    -- Only applies to the 'regex' provider
    -- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')
    providers_regex_syntax_denylist = {},
    -- providers_regex_syntax_allowlist: syntax to illuminate, this is overriden by providers_regex_syntax_denylist
    -- Only applies to the 'regex' provider
    -- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')
    providers_regex_syntax_allowlist = {},
    -- under_cursor: whether or not to illuminate under the cursor
    under_cursor = true,
})

Highlight Groups

IlluminatedWordText

Default highlight group used for references if no kind information is available.

hi def IlluminatedWordText gui=underline

IlluminatedWordRead

Highlight group used for references of kind read.

hi def IlluminatedWordRead gui=underline

IlluminatedWordWrite

Highlight group used for references of kind write.

hi def IlluminatedWordWrite gui=underline

Commands

:IlluminatePause

Globally pause vim-illuminate.

:IlluminateResume

Globally resume vim-illuminate.

:IlluminateToggle

Globally toggle the pause/resume for vim-illuminate.

:IlluminatePauseBuf

Buffer-local pause of vim-illuminate.

:IlluminateResumeBuf

Buffer-local resume of vim-illuminate.

:IlluminateToggleBuf

Buffer-local toggle of the pause/resume for vim-illuminate.

Functions

require('illuminate').configure(config)

Override the default configuration with config

require('illuminate').pause()

Globally pause vim-illuminate.

require('illuminate').resume()

Globally resume vim-illuminate.

require('illuminate').toggle()

Globally toggle the pause/resume for vim-illuminate.

require('illuminate').toggle_buf()

Buffer-local toggle of the pause/resume for vim-illuminate.

require('illuminate').pause_buf()

Buffer-local pause of vim-illuminate.

require('illuminate').resume_buf()

Buffer-local resume of vim-illuminate.

require('illuminate').freeze_buf()

Freeze the illumination on the buffer, this won't clear the highlights.

require('illuminate').unfreeze_buf()

Unfreeze the illumination on the buffer.

require('illuminate').goto_next_reference()

Move the cursor to the closest references after the cursor which it is not currently on. Wraps the buffer if on the last reference.

require('illuminate').goto_prev_reference()

Move the cursor to the closest references before the cursor which it is not currently on. Wraps the buffer if on the first reference.

require('illuminate').textobj_select()

Selects the reference the cursor is currently on for use as a text-object.