polirritmico/telescope-lazy-plugins.nvim

github github
search
stars 27
issues 0
subscribers 1
forks 1
CREATED

2024-02-04

UPDATED

3 days ago


๐Ÿงญ Telescope Lazy Plugins

Pull Requests GitHub last commit GitHub issues

๐Ÿง Description

A Telescope picker to quickly access plugins config files for lazy.nvim configurations.

๐Ÿ“ท Screenshot

Example: Searching for Telescope configurations:

Screenshot

โšก 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:

  • Open the selected repository webpage (<C-g>x).
  • Open the selected repository local clone directory (<C-g>r).
  • Open a live_grep picker from the selected repository local clone directory path (<C-g>l).
  • Create your custom actions.

The plugin check the current LazyPluginSpec, extract each plugin data, and generate the full filepath for each plugin, including the corresponding line number. This allows the correct config file to open at the appropriate cursor position.

๐Ÿ“ฆ Installation

  • Add it into the Telescope dependencies:
return {
  "nvim-telescope/telescope.nvim",
  dependencies = {
    { "polirritmico/telescope-lazy-plugins.nvim" },
  },
  -- etc.
}
  • Load the extension:
require("telescope").load_extension("lazy_plugins")

Run :checkhealth telescope after the installation is recommended (needs to be loaded first).

๐Ÿ” Usage

  • Command-line:
:Telescope lazy_plugins
  • Lua:
require("telescope").extensions.lazy_plugins.lazy_plugins()

๐Ÿ› ๏ธ Configuration:

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.

โŒจ๏ธ Mappings

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.

โš“ Defaults

{
  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 },
    },
  },
}

โš™๏ธ Configuration Examples:

๐Ÿš Simple config:

{
  "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:

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.
}

๐Ÿ“œ Full spec table

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)

๐Ÿ’ป Advanced Features

๐Ÿ”ง Custom Actions

The plugin also offer the possibility to add and define your custom actions to the picker 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 action or to avoid importing telescope in your config.

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.

Examples:

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 the entry. Could be any field of LazyPluginData.
          demo_custom_function,
          data
        )
      end,
    },
  },
},

๐Ÿ’ˆ Custom Entries

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/",
}

๐ŸŽจ Highlights

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

๐ŸŒฑ Contributions

This plugin is made mainly for my personal use, but suggestions, issues, or pull requests are very welcome.

Enjoy