{"id":14981681,"url":"https://github.com/rrethy/vim-illuminate","last_synced_at":"2025-05-14T05:10:26.807Z","repository":{"id":37822166,"uuid":"142644238","full_name":"RRethy/vim-illuminate","owner":"RRethy","description":"illuminate.vim - (Neo)Vim plugin for automatically highlighting other uses of the word under the cursor using either LSP, Tree-sitter, or regex matching.","archived":false,"fork":false,"pushed_at":"2025-04-27T00:28:44.000Z","size":150,"stargazers_count":2332,"open_issues_count":2,"forks_count":60,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-27T01:25:54.532Z","etag":null,"topics":["neovim","neovim-builtin-lsp","vim"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RRethy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-07-28T03:41:48.000Z","updated_at":"2025-04-27T00:28:48.000Z","dependencies_parsed_at":"2025-04-11T11:48:42.971Z","dependency_job_id":"4dee2398-1ae8-49e1-a000-147214b21408","html_url":"https://github.com/RRethy/vim-illuminate","commit_stats":{"total_commits":195,"total_committers":21,"mean_commits":9.285714285714286,"dds":0.4666666666666667,"last_synced_commit":"5eeb7951fc630682c322e88a9bbdae5c224ff0aa"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RRethy%2Fvim-illuminate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RRethy%2Fvim-illuminate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RRethy%2Fvim-illuminate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RRethy%2Fvim-illuminate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RRethy","download_url":"https://codeload.github.com/RRethy/vim-illuminate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["neovim","neovim-builtin-lsp","vim"],"created_at":"2024-09-24T14:04:03.957Z","updated_at":"2025-05-14T05:10:26.756Z","avatar_url":"https://github.com/RRethy.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Overview\n\nNeovim plugin for automatically highlighting other uses of the word under the cursor using either LSP, Tree-sitter, or regex matching.\n\nhttps://github.com/user-attachments/assets/fc1487cf-aa19-4238-af23-ab1ac2f5744a\n\n# Quickstart\n\nJust install the plugin and things will work *just work*, no configuration needed.\n\nYou'll also get `\u003ca-n\u003e` and `\u003ca-p\u003e` as keymaps to move between references and `\u003ca-i\u003e` as a textobject for the reference illuminated under the cursor.\n\n*Note: Vim users should refer to the [docs](https://github.com/RRethy/vim-illuminate?tab=readme-ov-file#vim-users) for the Vimscript implementation of this plugin.*\n\n# Configuration\n\n```lua\n-- default configuration\nrequire('illuminate').configure({\n    -- providers: provider used to get references in the buffer, ordered by priority\n    providers = {\n        'lsp',\n        'treesitter',\n        'regex',\n    },\n    -- delay: delay in milliseconds\n    delay = 100,\n    -- filetype_overrides: filetype specific overrides.\n    -- The keys are strings to represent the filetype while the values are tables that\n    -- supports the same keys passed to .configure except for filetypes_denylist and filetypes_allowlist\n    filetype_overrides = {},\n    -- filetypes_denylist: filetypes to not illuminate, this overrides filetypes_allowlist\n    filetypes_denylist = {\n        'dirbuf',\n        'dirvish',\n        'fugitive',\n    },\n    -- filetypes_allowlist: filetypes to illuminate, this is overridden by filetypes_denylist\n    -- You must set filetypes_denylist = {} to override the defaults to allow filetypes_allowlist to take effect\n    filetypes_allowlist = {},\n    -- modes_denylist: modes to not illuminate, this overrides modes_allowlist\n    -- See `:help mode()` for possible values\n    modes_denylist = {},\n    -- modes_allowlist: modes to illuminate, this is overridden by modes_denylist\n    -- See `:help mode()` for possible values\n    modes_allowlist = {},\n    -- providers_regex_syntax_denylist: syntax to not illuminate, this overrides providers_regex_syntax_allowlist\n    -- Only applies to the 'regex' provider\n    -- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')\n    providers_regex_syntax_denylist = {},\n    -- providers_regex_syntax_allowlist: syntax to illuminate, this is overridden by providers_regex_syntax_denylist\n    -- Only applies to the 'regex' provider\n    -- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')\n    providers_regex_syntax_allowlist = {},\n    -- under_cursor: whether or not to illuminate under the cursor\n    under_cursor = true,\n    -- large_file_cutoff: number of lines at which to use large_file_config\n    -- The `under_cursor` option is disabled when this cutoff is hit\n    large_file_cutoff = 10000,\n    -- large_file_config: config to use for large files (based on large_file_cutoff).\n    -- Supports the same keys passed to .configure\n    -- If nil, vim-illuminate will be disabled for large files.\n    large_file_overrides = nil,\n    -- min_count_to_highlight: minimum number of matches required to perform highlighting\n    min_count_to_highlight = 1,\n    -- should_enable: a callback that overrides all other settings to\n    -- enable/disable illumination. This will be called a lot so don't do\n    -- anything expensive in it.\n    should_enable = function(bufnr) return true end,\n    -- case_insensitive_regex: sets regex case sensitivity\n    case_insensitive_regex = false,\n    -- disable_keymaps: disable default keymaps\n    disable_keymaps = false,\n})\n```\n\n# Highlight Groups\n\n#### IlluminatedWordText\n\nDefault highlight group used for references if no kind information is available.\n\n```vim\nhi def IlluminatedWordText gui=underline cterm=underline\n```\n\n#### IlluminatedWordRead\n\nHighlight group used for references of kind read.\n\n```vim\nhi def IlluminatedWordRead gui=underline cterm=underline\n```\n\n#### IlluminatedWordWrite\n\nHighlight group used for references of kind write.\n\n```vim\nhi def IlluminatedWordWrite gui=underline cterm=underline\n```\n\n# Commands\n\n#### :IlluminatePause\n\nGlobally pause vim-illuminate.\n\n#### :IlluminateResume\n\nGlobally resume vim-illuminate.\n\n#### :IlluminateToggle\n\nGlobally toggle the pause/resume for vim-illuminate.\n\n#### :IlluminatePauseBuf\n\nBuffer-local pause of vim-illuminate.\n\n#### :IlluminateResumeBuf\n\nBuffer-local resume of vim-illuminate.\n\n#### :IlluminateToggleBuf\n\nBuffer-local toggle of the pause/resume for vim-illuminate.\n\n# Functions\n\n#### require('illuminate').configure(config)\n\nOverride the default configuration with `config`\n\n#### require('illuminate').pause()\n\nGlobally pause vim-illuminate.\n\n#### require('illuminate').resume()\n\nGlobally resume vim-illuminate.\n\n#### require('illuminate').toggle()\n\nGlobally toggle the pause/resume for vim-illuminate.\n\n#### require('illuminate').toggle_buf()\n\nBuffer-local toggle of the pause/resume for vim-illuminate.\n\n#### require('illuminate').pause_buf()\n\nBuffer-local pause of vim-illuminate.\n\n#### require('illuminate').resume_buf()\n\nBuffer-local resume of vim-illuminate.\n\n#### require('illuminate').freeze_buf()\n\nFreeze the illumination on the buffer, this won't clear the highlights.\n\n#### require('illuminate').unfreeze_buf()\n\nUnfreeze the illumination on the buffer.\n\n#### require('illuminate').toggle_freeze_buf()\n\nToggle the frozen state of the buffer.\n\n#### require('illuminate').invisible_buf()\n\nTurn off the highlighting for the buffer, this won't stop the engine from running so you can still use `\u003cc-n\u003e` and `\u003cc-p\u003e`.\n\n#### require('illuminate').visible_buf()\n\nTurn on the highlighting for the buffer, this is only needed if you've previous called `require('illuminate').invisible_buf()`.\n\n#### require('illuminate').toggle_visibility_buf()\n\nToggle the visibility of highlights in the buffer.\n\n#### require('illuminate').goto_next_reference(wrap)\n\nMove the cursor to the closest references after the cursor which it is not currently on. Wraps the buffer if on the last reference.\n\nWraps the references unless `wrap` is false (defaults to **'wrapscan'**).\n\n#### require('illuminate').goto_prev_reference(wrap)\n\nMove the cursor to the closest references before the cursor which it is not currently on. Wraps the buffer if on the first reference.\n\nWraps the references unless `wrap` is false (defaults to **'wrapscan'**).\n\n#### require('illuminate').textobj_select()\n\nSelects the reference the cursor is currently on for use as a text-object.\n\n# Vim Users\n\n**Note:** This section is deprecated for Neovim users, Neovim users can use the newer version of the plugin. Neovim users can force this old version of the plugin by adding `let g:Illuminate_useDeprecated = 1` to their `init.vim`.\n\nIlluminate will delay before highlighting, this is not lag, it is to avoid the jarring experience of things illuminating too fast. This can be controlled with `g:Illuminate_delay` (which is default to 0 milliseconds):\n\n**Note**: Delay only works for Vim8 and Neovim.\n\n```vim\n\" Time in milliseconds (default 0)\nlet g:Illuminate_delay = 0\n```\nIlluminate will by default highlight the word under the cursor to match the behaviour seen in Intellij and VSCode. However, to make it not highlight the word under the cursor, use the following:\n\n```vim\n\" Don't highlight word under cursor (default: 1)\nlet g:Illuminate_highlightUnderCursor = 0\n```\n\nBy default illuminate will highlight all words the cursor passes over, but for many languages, you will only want to highlight certain highlight-groups.\nYou can determine the highlight-group of a symbol under your cursor with `:echo synIDattr(synID(line(\".\"), col(\".\"), 1), \"name\")`.\n\nYou can define which highlight groups you want the illuminating to apply to. This can be done with a dict mapping a filetype to a list of highlight-groups in your vimrc such as:\n```vim\nlet g:Illuminate_ftHighlightGroups = {\n      \\ 'vim': ['vimVar', 'vimString', 'vimLineComment',\n      \\         'vimFuncName', 'vimFunction', 'vimUserFunc', 'vimFunc']\n      \\ }\n```\n\nA blacklist of highlight groups can also be setup by adding the suffix `:blacklist` to the filetype. However, if the whitelist for that filetype already exists, it will override the blacklist.\n```vim\nlet g:Illuminate_ftHighlightGroups = {\n      \\ 'vim:blacklist': ['vimVar', 'vimString', 'vimLineComment',\n      \\         'vimFuncName', 'vimFunction', 'vimUserFunc', 'vimFunc']\n      \\ }\n```\n\nilluminate can also be disabled for various filetypes using the following:\n```vim\nlet g:Illuminate_ftblacklist = ['nerdtree']\n```\n\nOr you can enable it only for certain filetypes with:\n```vim\nlet g:Illuminate_ftwhitelist = ['vim', 'sh', 'python']\n```\n\nBy default the highlighting will be done with the highlight-group `CursorLine` since that is in my opinion the nicest. It can however be overridden using the following (use standard Vim highlighting syntax):\nNote: It must be in an autocmd to get around a weird Neovim behaviour.\n```vim\naugroup illuminate_augroup\n    autocmd!\n    autocmd VimEnter * hi link illuminatedWord CursorLine\naugroup END\n\naugroup illuminate_augroup\n    autocmd!\n    autocmd VimEnter * hi illuminatedWord cterm=underline gui=underline\naugroup END\n```\n\nLastly, you can also specify a specific highlight for the word under the cursor so it differs from all other matches using the following higlight group:\n```vim\naugroup illuminate_augroup\n    autocmd!\n    autocmd VimEnter * hi illuminatedCurWord cterm=italic gui=italic\naugroup END\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrethy%2Fvim-illuminate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrethy%2Fvim-illuminate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrethy%2Fvim-illuminate/lists"}