A Telescope picker to quickly access plugins config files for lazy.nvim configurations.
Example: Searching for Telescope configurations:
⚡ Simply search the plugin name and open its configuration at the corresponding line.
No matter if the config is in a unique file, grouped in the same file with other plugins configs, grouped in a big table or splitted across multiple plugin dependencies.
⚡ No more head overload trying to remember in which file you changed that plugin option or searching through files to check for overlapping configs.
⚡ Add custom entries for your special needs.
For example a custom entry to quickly access a configuration file from a config distribution like LazyVim, NvChad, etc.
⚡ Quickly execute builtin actions on the selected entry:
<C-g>x
).<C-g>r
).live_grep
picker from the selected repository local clone directory
path (<C-g>l
).The plugin check the current LazyPluginSpec
, extract each plugin data and
generate the full filepath for each with the corresponding line number, so the
file is open at the appropriate cursor position.
return {
"nvim-telescope/telescope.nvim",
dependencies = {
{ "polirritmico/telescope-lazy-plugins.nvim" },
},
-- etc.
}
require("telescope").load_extension("lazy_plugins")
Run
:checkhealth telescope
after the installation is recommended (needs to be loaded first).
:Telescope lazy_plugins
require("telescope").extensions.lazy_plugins.lazy_plugins()
Add the options in the telescope.nvim
opts extensions
table inside
lazy_plugins
(check the configuration examples).
Option | Type | Description |
---|---|---|
lazy_config |
string |
Path to the lua file containing the lazy options passed to the setup() call. With this value setted, the lazy entry is added, e.g. searching for lazy to open nvim/lua/config/lazy.lua . |
lazy_spec_table |
string |
If plugins are directly passed to the require("lazy").setup() function inside a plugins table (instead of using only imports paths), set this option to the file where that table is defined. When no module is found inside a plugin spec this path would be used instead. |
name_only |
boolean |
Match only the repository name. False to match the full account/repo_name . |
show_disabled |
boolean |
Also show disabled plugins from the Lazy spec. |
picker_opts |
table |
Layout options passed into Telescope. Check :h telescope.layout . |
mappings |
table |
Keymaps attached to the picker. See :h telescope.mappings . Also, 'Custom Actions' could be added. |
live_grep |
table |
Options to pass into the Telescope builtin live_grep picker. See :h telescope.builtin.live_grep . |
custom_entries |
table |
A collection of custom entries to add into the picker. See the 'Custom Entries' section. |
lp_actions
refers to the table provided by telescope-lazy-plugins.actions
,
accessible via:
require("telescope").extensions.lazy_plugins.actions
Insert | Normal | lp_actions | Description |
---|---|---|---|
<CR> |
<CR> |
open |
Open the selected plugin config file at the first line of the plugin spec. |
<C-g>x |
gx |
open_repo_url |
Open the plugin repository url in your default web browser. |
<C-g>r |
gr |
open_repo_dir |
Open the plugin repository Lazy local clone folder. |
<C-g>l |
gl |
open_repo_live_grep |
Open Telescope live_grep at the repository local clone folder. |
<LefMouse> |
<LeftMouse> |
nothing |
A dummy function to prevent closing Telescope on mouse clicks. Useful for keeping Telescope open when focus is regained by a mouse click after browsing the plugin documentation. |
custom_action |
A wrapper to pass custom actions. See the 'Custom Actions' section. |
The plugin also offer the possibility to add and define your custom actions
through custom_action
and helper functions.
Helper Functions:
append_to_telescope_history
: Append the search value into the Telescope
history. For example, when using :Telescope resume
.close
: Close the Telescope picker. Use if you want to close Telescope during
the execution of your custom_action
.custom_action:
A wrapper function to use custom actions. This function get and validates the
selected entry field, executes the passed custom_function
in a protected call
and returns its output.
Param/Output | Type | Description |
---|---|---|
prompt_bufnr |
integer | Telescope prompt buffer value |
field |
string | Field of the LazyPluginData to validate the selected entry (before the custom_function call). Check the 'Custom Entries' section for details on the entry field. |
custom_function |
function | Custom function to execute, e.g., foo(bufnr, entry, custom_args) . Check the custom action example. |
args |
table | Custom args if needed. |
return: output |
any | The output of the custom_function, nil or the error object from pcall. |
Demo of a custom action to close Telescope when opening a repository url on the browser:
lazy_plugins = {
mappings = {
["i"] = {
["<C-g>"] = function(bufnr)
local lp_actions = require("telescope").extensions.lazy_plugins.actions
lp_actions.open_repo_url()
lp_actions.close(bufnr)
end,
},
},
Demo of a custom action to show a message with the repository local clone path from the selected entry:
-- To access the selected entry value, `custom_action` could be used:
local lp_actions = require("telescope").extensions.lazy_plugins.actions
---@param bufnr integer passed by the telescope mapping execution call
---@param entry LazyPluginData passed inside `custom_action`
---@param custom_args {foo: string} If needed custom_args could be added in a table
local function demo_custom_function(bufnr, entry, custom_args)
vim.notify(string.format("%s%s", custom_args.foo, entry.repo_dir))
lp_actions.append_to_telescope_history(bufnr)
lp_actions.close(bufnr)
end
-- etc.
lazy_plugins = {
mappings = {
["i"] = {
["<C-g>d"] = function(prompt_bufnr)
local data = { foo = "Plugin path from the selected entry.repo_dir: " }
lp_actions.custom_action(
prompt_bufnr,
"repo_dir", -- This is used to validate that the entry valid. Could be any field of LazyPluginData.
demo_custom_function,
data
)
end,
},
},
},
Custom entries could be added into the custom_entries
field in the options.
Should follow this specs:
---@class LazyPluginsCustomEntry
---@field name string Entry name
---@field filepath string Full path to the lua target file
---@field line? integer Optional: Line number to set the view on the target file. Defaults to 1.
---@field repo_url? string Optional: URL to open with the `open_repo_url` action
---@field repo_dir? string Optional: Directory path to open with the `open_repo_dir` action
--- Custom entry example:
{
name = "custom-entry",
filepath = vim.fn.stdpath("config") .. "lua/extra-options/somefile.lua",
-- Optional:
line = 42,
repo_url = "https://www.lua.org/manual/5.2/",
repo_dir = vim.fn.stdpath("config") .. "lua/extra-options/",
}
{
name_only = true, -- match only the `repo_name`, false to match the full `account/repo_name`
show_disabled = true, -- also show disabled plugins from the Lazy spec.
lazy_config = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- path to the file containing the lazy opts and setup() call.
lazy_spec_table = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- path to the file containing the lazy plugin spec table.
custom_entries = {}, ---@type table<LazyPluginsCustomEntry>
live_grep = {}, -- Opts to pass into `live_grep`. Check `:h telescope.builtin.live_grep`
mappings = {
["i"] = {
["<C-g>x"] = lp_actions.open_repo_url,
["<C-g>r"] = lp_actions.open_repo_dir,
["<C-g>l"] = lp_actions.open_repo_live_grep,
["<LeftMouse>"] = lp_actions.nothing, -- Set to `false` to fallback to the default telescope setting
},
["n"] = {
["gx"] = lp_actions.open_repo_url,
["gr"] = lp_actions.open_repo_dir,
["gl"] = lp_actions.open_repo_live_grep,
["<LeftMouse>"] = lp_actions.nothing, -- Set to `false` to fallback to the default telescope setting
},
},
picker_opts = {
sorting_strategy = "ascending",
layout_strategy = "flex",
layout_config = {
flex = { flip_columns = 150 },
horizontal = { preview_width = { 0.55, max = 100, min = 30 } },
vertical = { preview_cutoff = 20, preview_height = 0.5 },
},
},
}
{
"nvim-telescope/telescope.nvim",
cmd = "Telescope",
dependencies = {
{ "nvim-lua/plenary.nvim" },
{
"polirritmico/telescope-lazy-plugins.nvim",
keys = {
{ "<leader>cp", "<Cmd>Telescope lazy_plugins<CR>", desc = "Telescope: Plugins configurations" },
},
},
},
opts = {
extensions = {
lazy_plugins = {
lazy_config = vim.fn.stdpath("config") .. "/lua/lazy/init.lua", -- path to the file containing the lazy opts and setup() call.
},
},
-- etc.
},
}
Lazy-loading Telescope extensions could be a little tricky. This approach
creates a user auto command that checks when the telescope.nvim
plugin is
loaded and then executes the load_extension
function (Could be used with any
Telescope extension).
local load_extension_after_telescope_is_loaded = function(extension_name)
local lazy_cfg = require("lazy.core.config").plugins
if lazy_cfg["telescope.nvim"] and lazy_cfg["telescope.nvim"]._.loaded then
-- if telescope is loaded, then simply load the extension:
require("telescope").load_extension(extension_name)
else
-- If telescope is not loaded, create an autocmd that will load the
-- extension after telescope is loaded.
vim.api.nvim_create_autocmd("User", {
pattern = "LazyLoad",
callback = function(event)
if event.data == "telescope.nvim" then
require("telescope").load_extension(extension_name)
return true
end
end,
})
end
end
return {
{
"nvim-telescope/telescope.nvim",
cmd = "Telescope",
dependencies = {
{ "nvim-lua/plenary.nvim" },
{
"polirritmico/telescope-lazy-plugins.nvim",
init = function()
load_extension_after_telescope_is_loaded("lazy_plugins")
end,
},
},
keys = {
{"<leader>cp", "<Cmd>Telescope lazy_plugins<CR>", desc = "Telescope: Plugins configurations"},
},
-- Add the configuration through the Telescope options:
opts = {
extensions = {
lazy_plugins = {
show_disabled = true,
lazy_config = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- path to the file containing the lazy opts and setup() call.
lazy_spec_table = vim.fn.stdpath("config") .. "/lua/config/lazy.lua", -- path to the file containing the lazy plugin spec table.
-- This is not needed. It is just an example of how you can customize the picker layout. Check `:h telescope.layout`.
picker_opts = {
layout_strategy = "vertical",
layout_config = {
vertical = { preview_cutoff = 15, preview_height = 0.5 },
},
},
-- This is not needed. It is just an example of how you can add custom entries.
custom_entries = {
{
name = "custom-entry-example",
filepath = vim.fn.stdpath("config") .. "/lua/config/mappings.lua",
repo_url = "https://www.lua.org/manual/5.2/",
line = 23,
},
},
},
},
},
},
-- etc.
}
If your plugins are inside a large table passed directly to the
require('lazy').setup({...}, opts)
call, make sure to set the
lazy_spec_table
option to specify the file where the spec table is defined.
For example, for configurations in a single init.lua
file:
-- Content of file: ~/.conf/nvim/init.lua
local opts = {
-- Lazy configuration options
}
require("lazy").setup({
-- full list of plugins and configs like this:
"username/a_plugin",
opts = {
configurations = "custom values",
},
-- etc.
{
"nvim-telescope/telescope.nvim",
dependencies = {
{ "nvim-lua/plenary.nvim" },
{ "polirritmico/telescope-lazy-plugins.nvim" },
},
opts = {
extensions = {
lazy_plugins = {
-- Since this config is only in one big table, pass the path of this
-- file (~/.config/nvim/init.lua) into the `lazy_spec_table` field:
lazy_spec_table = vim.fn.stdpath("config") .. "/init.lua"
},
},
},
},
}, opts)
This are the highlights defined by Telescope Lazy Plugins:
Highlight group | Defaults to | Description |
---|---|---|
TelescopeLazyPlugins | Normal | Plugin name |
TelescopeLazyPluginsFile | Comment | Module file with the config spec |
TelescopeLazyPluginsEnabled | Function | Enabled plugin icon |
TelescopeLazyPluginsDisabled | Delimiter | Disabled plugin icon |
This plugin is made mainly for my personal use, but suggestions, issues, or pull requests are very welcome.
Enjoy