lazy.nvim/doc/lazy.nvim.txt

*lazy.nvim.txt*                             A modern plugin manager for Neovim

==============================================================================
Table of Contents                                *lazy.nvim-table-of-contents*

1. 📰 What’s new?                           |lazy.nvim-📰-what’s-new?|
  - 11.x                                   |lazy.nvim-📰-what’s-new?-11.x|
2. 🚀 Getting Started                       |lazy.nvim-🚀-getting-started|
  - ✨ Features                 |lazy.nvim-🚀-getting-started-✨-features|
  - ⚡️ Requirements   |lazy.nvim-🚀-getting-started-⚡️-requirements|
3. 🛠️ Installation                       |lazy.nvim-🛠️-installation|
  - Structured Setup         |lazy.nvim-🛠️-installation-structured-setup|
  - Single File Setup       |lazy.nvim-🛠️-installation-single-file-setup|
4. 🔌 Plugin Spec                               |lazy.nvim-🔌-plugin-spec|
  - Spec Source                       |lazy.nvim-🔌-plugin-spec-spec-source|
  - Spec Loading                     |lazy.nvim-🔌-plugin-spec-spec-loading|
  - Spec Setup                         |lazy.nvim-🔌-plugin-spec-spec-setup|
  - Spec Lazy Loading           |lazy.nvim-🔌-plugin-spec-spec-lazy-loading|
  - Spec Versioning               |lazy.nvim-🔌-plugin-spec-spec-versioning|
  - Spec Advanced                   |lazy.nvim-🔌-plugin-spec-spec-advanced|
  - Examples                             |lazy.nvim-🔌-plugin-spec-examples|
  - Lazy Loading                     |lazy.nvim-🔌-plugin-spec-lazy-loading|
  - Versioning                         |lazy.nvim-🔌-plugin-spec-versioning|
5. 📦 Packages                                     |lazy.nvim-📦-packages|
  - Lazy                                        |lazy.nvim-📦-packages-lazy|
  - Rockspec                                |lazy.nvim-📦-packages-rockspec|
  - Packspec                                |lazy.nvim-📦-packages-packspec|
6. ⚙️ Configuration                       |lazy.nvim-⚙️-configuration|
  - 🌈 Highlight Groups|lazy.nvim-⚙️-configuration-🌈-highlight-groups|
7. 🚀 Usage                                           |lazy.nvim-🚀-usage|
  - ▶️ Startup Sequence     |lazy.nvim-🚀-usage-▶️-startup-sequence|
  - 🚀 Commands                         |lazy.nvim-🚀-usage-🚀-commands|
  - 📆 User Events                   |lazy.nvim-🚀-usage-📆-user-events|
  - ❌ Uninstalling                   |lazy.nvim-🚀-usage-❌-uninstalling|
  - 🔒 Lockfile                         |lazy.nvim-🚀-usage-🔒-lockfile|
  - 📦 Migration Guide           |lazy.nvim-🚀-usage-📦-migration-guide|
  - ⚡ Profiling & Debug         |lazy.nvim-🚀-usage-⚡-profiling-&-debug|
  - 📂 Structuring Your Plugins|lazy.nvim-🚀-usage-📂-structuring-your-plugins|
8. 🔥 Developers                                 |lazy.nvim-🔥-developers|
  - Best Practices                  |lazy.nvim-🔥-developers-best-practices|
  - Building                              |lazy.nvim-🔥-developers-building|
  - Minit (Minimal Init)      |lazy.nvim-🔥-developers-minit-(minimal-init)|
9. Links                                                     |lazy.nvim-links|

==============================================================================
1. 📰 What’s new?                           *lazy.nvim-📰-what’s-new?*


11.X                                       *lazy.nvim-📰-what’s-new?-11.x*

- **New Website**: There’s a whole new website with a fresh look and improved
    documentation. Check it out at <https://lazy.folke.io>. The GitHub `README.md`
    has been updated to point to the new website. The `vimdoc` contains all the
    information that is available on the website.
- **Spec Resolution & Merging**: the code that resolves a final spec from a
    plugin’s fragments has been rewritten. This should be a tiny bit faster, but
    more importantly, fixes some issues and is easier to maintain.
- Packages <https://lazy.folke.io/packages> can now specify their dependencies
    and configuration using one of:
    - **Lazy**: `lazy.lua` file
    - **Rockspec**: luarocks <https://luarocks.org/> `*-scm-1.rockspec` file <https://github.com/luarocks/luarocks/wiki/Rockspec-format>
    - **Packspec**: `pkg.json` (experimental, since the format <https://github.com/neovim/packspec/issues/41> is not quite there yet)
    Related _lazy.nvim_ options:
    >lua
        {
          pkg = {
            enabled = true,
            cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua",
            -- the first package source that is found for a plugin will be used.
            sources = {
              "lazy",
              "rockspec", -- will only be used when rocks.enabled is true
              "packspec",
            },
          },
          rocks = {
            enabled = true,
            root = vim.fn.stdpath("data") .. "/lazy-rocks",
            server = "https://nvim-neorocks.github.io/rocks-binaries/",
          },
        }
    <
- Installing neorg <https://github.com/nvim-neorg/neorg> is now as simple as:
    >lua
        { "nvim-neorg/neorg", opts = {} }
    <
- Packages are not limited to just Neovim plugins. You can install any
    **luarocks** package, like:
    >lua
        { "https://github.com/lubyk/yaml" }
    <
    Luarocks packages without a `/lua` directory are never lazy-loaded, since
    it’s just a library.
- `build` functions or `*.lua` build files (like `build.lua`) now run
    asynchronously. You can use `coroutine.yield(status_msg)` to show progress.
    Yielding will also schedule the next `resume` to run in the next tick, so you
    can do long-running tasks without blocking Neovim.


==============================================================================
2. 🚀 Getting Started                       *lazy.nvim-🚀-getting-started*

**lazy.nvim** is a modern plugin manager for Neovim.


✨ FEATURES                     *lazy.nvim-🚀-getting-started-✨-features*

- 📦 Manage all your Neovim plugins with a powerful UI
- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of Lua modules
- 💾 Partial clones instead of shallow clones
- 🔌 Automatic lazy-loading of Lua modules and lazy-loading on events, commands, filetypes, and key mappings
- ⏳ Automatically install missing plugins before starting up Neovim, allowing you to start using it right away
- 💪 Async execution for improved performance
- 🛠️ No need to manually compile plugins
- 🧪 Correct sequencing of dependencies
- 📁 Configurable in multiple files
- 📚 Generates helptags of the headings in `README.md` files for plugins that don’t have vimdocs
- 💻 Dev options and patterns for using local plugins
- 📊 Profiling tools to optimize performance
- 🔒 Lockfile `lazy-lock.json` to keep track of installed plugins
- 🔎 Automatically check for updates
- 📋 Commit, branch, tag, version, and full Semver <https://devhints.io/semver> support
- 📈 Statusline component to see the number of pending updates
- 🎨 Automatically lazy-loads colorschemes


⚡️ REQUIREMENTS       *lazy.nvim-🚀-getting-started-⚡️-requirements*

- Neovim >= **0.8.0** (needs to be built with **LuaJIT**)
- Git >= **2.19.0** (for partial clones support)
- a Nerd Font <https://www.nerdfonts.com/> **(optional)**
- luarocks <https://luarocks.org/> to install rockspecs.
    You can remove `rockspec` from `opts.pkg.sources` to disable this feature.


==============================================================================
3. 🛠️ Installation                       *lazy.nvim-🛠️-installation*

There are multiple ways to install **lazy.nvim**. The **Structured Setup** is
the recommended way, but you can also use the **Single File Setup** if you
prefer to keep everything in your `init.lua`.

Please refer to the Configuration </configuration> section for an overview of
all available options.




STRUCTURED SETUP             *lazy.nvim-🛠️-installation-structured-setup*

>lua
    require("config.lazy")
<

>lua
    -- Bootstrap lazy.nvim
    local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
    if not (vim.uv or vim.loop).fs_stat(lazypath) then
      local lazyrepo = "https://github.com/folke/lazy.nvim.git"
      local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
      if vim.v.shell_error ~= 0 then
        vim.api.nvim_echo({
          { "Failed to clone lazy.nvim:\n", "ErrorMsg" },
          { out, "WarningMsg" },
          { "\nPress any key to exit..." },
        }, true, {})
        vim.fn.getchar()
        os.exit(1)
      end
    end
    vim.opt.rtp:prepend(lazypath)
    
    -- Make sure to setup `mapleader` and `maplocalleader` before
    -- loading lazy.nvim so that mappings are correct.
    -- This is also a good place to setup other settings (vim.opt)
    vim.g.mapleader = " "
    vim.g.maplocalleader = "\\"
    
    -- Setup lazy.nvim
    require("lazy").setup({
      -- highlight-start
      spec = {
        -- import your plugins
        { import = "plugins" },
      },
      -- highlight-end
      -- Configure any other settings here. See the documentation for more details.
      -- colorscheme that will be used when installing plugins.
      install = { colorscheme = { "habamax" } },
      -- automatically check for plugin updates
      checker = { enabled = true },
    })
<

You can then create your plugin specs in `~/.config/nvim/lua/plugins/`. Each
file should return a table with the plugins you want to install.

For more info see Structuring Your Plugins </usage/structuring>


SINGLE FILE SETUP           *lazy.nvim-🛠️-installation-single-file-setup*

>lua
    -- Bootstrap lazy.nvim
    local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
    if not (vim.uv or vim.loop).fs_stat(lazypath) then
      local lazyrepo = "https://github.com/folke/lazy.nvim.git"
      local out = vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
      if vim.v.shell_error ~= 0 then
        vim.api.nvim_echo({
          { "Failed to clone lazy.nvim:\n", "ErrorMsg" },
          { out, "WarningMsg" },
          { "\nPress any key to exit..." },
        }, true, {})
        vim.fn.getchar()
        os.exit(1)
      end
    end
    vim.opt.rtp:prepend(lazypath)
    
    -- Make sure to setup `mapleader` and `maplocalleader` before
    -- loading lazy.nvim so that mappings are correct.
    -- This is also a good place to setup other settings (vim.opt)
    vim.g.mapleader = " "
    vim.g.maplocalleader = "\\"
    
    -- Setup lazy.nvim
    require("lazy").setup({
      -- highlight-start
      spec = {
        -- add your plugins here
      },
      -- highlight-end
      -- Configure any other settings here. See the documentation for more details.
      -- colorscheme that will be used when installing plugins.
      install = { colorscheme = { "habamax" } },
      -- automatically check for plugin updates
      checker = { enabled = true },
    })
<


==============================================================================
4. 🔌 Plugin Spec                               *lazy.nvim-🔌-plugin-spec*


SPEC SOURCE                           *lazy.nvim-🔌-plugin-spec-spec-source*

  -----------------------------------------------------------------------------------
  Property   Type       Description
  ---------- ---------- -------------------------------------------------------------
  [1]        string?    Short plugin url. Will be expanded using
                        config.git.url_format. Can also be a url or dir.

  dir        string?    A directory pointing to a local plugin

  url        string?    A custom git url where the plugin is hosted

  name       string?    A custom name for the plugin used for the local plugin
                        directory and as the display name

  dev        boolean?   When true, a local plugin directory will be used instead. See
                        config.dev
  -----------------------------------------------------------------------------------
A valid spec should define one of `[1]`, `dir` or `url`.


SPEC LOADING                         *lazy.nvim-🔌-plugin-spec-spec-loading*

  --------------------------------------------------------------------------------------------------
  Property       Type                      Description
  -------------- ------------------------- ---------------------------------------------------------
  dependencies   LazySpec[]                A list of plugin names or plugin specs that should be
                                           loaded when the plugin loads. Dependencies are always
                                           lazy-loaded unless specified otherwise. When specifying a
                                           name, make sure the plugin spec has been defined
                                           somewhere else.

  enabled        boolean? or fun():boolean When false, or if the function returns false, then this
                                           plugin will not be included in the spec

  cond           boolean? or               Behaves the same as enabled, but won’t uninstall the
                 fun(LazyPlugin):boolean   plugin when the condition is false. Useful to disable
                                           some plugins in vscode, or firenvim for example.

  priority       number?                   Only useful for start plugins (lazy=false) to force
                                           loading certain plugins first. Default priority is 50.
                                           It’s recommended to set this to a high number for
                                           colorschemes.
  --------------------------------------------------------------------------------------------------

SPEC SETUP                             *lazy.nvim-🔌-plugin-spec-spec-setup*

  --------------------------------------------------------------------------------------------------
  Property   Type                          Description
  ---------- ----------------------------- ---------------------------------------------------------
  init       fun(LazyPlugin)               init functions are always executed during. Mostly useful
                                           for setting vim.g.* configuration used by Vim plugins
                                           startup

  opts       table or                      opts should be a table (will be merged with parent
             fun(LazyPlugin, opts:table)   specs), return a table (replaces parent specs) or should
                                           change a table. The table will be passed to the
                                           Plugin.config() function. Setting this value will imply
                                           Plugin.config()

  config     fun(LazyPlugin, opts:table)   config is executed when the plugin loads. The default
             or true                       implementation will automatically run
                                           require(MAIN).setup(opts) if opts or config = true is
                                           set. Lazy uses several heuristics to determine the
                                           plugin’s MAIN module automatically based on the plugin’s
                                           name. (opts is the recommended way to configure plugins).

  main       string?                       You can specify the main module to use for config() and
                                           opts(), in case it can not be determined automatically.
                                           See config()

  build      fun(LazyPlugin) or string or  build is executed when a plugin is installed or updated.
             false or a list of build      See Building for more information.
             commands                      
  --------------------------------------------------------------------------------------------------
Always use `opts` instead of `config` when possible. `config` is almost never
needed.




SPEC LAZY LOADING               *lazy.nvim-🔌-plugin-spec-spec-lazy-loading*

  --------------------------------------------------------------------------------------------------------------------
  Property   Type                                                             Description
  ---------- ---------------------------------------------------------------- ----------------------------------------
  lazy       boolean?                                                         When true, the plugin will only be
                                                                              loaded when needed. Lazy-loaded plugins
                                                                              are automatically loaded when their Lua
                                                                              modules are required, or when one of the
                                                                              lazy-loading handlers triggers

  event      string? or string[] or                                           Lazy-load on event. Events can be
             fun(self:LazyPlugin, event:string[]):string[] or                 specified as BufEnter or with a pattern
             {event:string[]\|string, pattern?:string[]\|string}              like BufEnter *.lua

  cmd        string? or string[] or                                           Lazy-load on command
             fun(self:LazyPlugin, cmd:string[]):string[]                      

  ft         string? or string[] or                                           Lazy-load on filetype
             fun(self:LazyPlugin, ft:string[]):string[]                       

  keys       string? or string[] or LazyKeysSpec[] or                         Lazy-load on key mapping
             fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[]   
  --------------------------------------------------------------------------------------------------------------------
Refer to the Lazy Loading <./lazy_loading.md> section for more information.


SPEC VERSIONING                   *lazy.nvim-🔌-plugin-spec-spec-versioning*

  ------------------------------------------------------------------------------
  Property     Type                 Description
  ------------ -------------------- --------------------------------------------
  branch       string?              Branch of the repository

  tag          string?              Tag of the repository

  commit       string?              Commit of the repository

  version      string? or false to  Version to use from the repository. Full
               override the default Semver ranges are supported

  pin          boolean?             When true, this plugin will not be included
                                    in updates

  submodules   boolean?             When false, git submodules will not be
                                    fetched. Defaults to true
  ------------------------------------------------------------------------------
Refer to the Versioning <./versioning.md> section for more information.


SPEC ADVANCED                       *lazy.nvim-🔌-plugin-spec-spec-advanced*

  ----------------------------------------------------------------------------------------
  Property   Type       Description
  ---------- ---------- ------------------------------------------------------------------
  optional   boolean?   When a spec is tagged optional, it will only be included in the
                        final spec, when the same plugin has been specified at least once
                        somewhere else without optional. This is mainly useful for Neovim
                        distros, to allow setting options on plugins that may/may not be
                        part of the user’s plugins.

  specs      LazySpec   A list of plugin specs defined in the scope of the plugin. This is
                        mainly useful for Neovim distros, to allow setting options on
                        plugins that may/may not be part of the user’s plugins. When the
                        plugin is disabled, none of the scoped specs will be included in
                        the final spec. Similar to dependencies without the automatic
                        loading of the specs.

  module     false?     Do not automatically load this Lua module when it’s required
                        somewhere

  import     string?    Import the given spec module.
  ----------------------------------------------------------------------------------------

EXAMPLES                                 *lazy.nvim-🔌-plugin-spec-examples*

>lua
    return {
      -- the colorscheme should be available when starting Neovim
      {
        "folke/tokyonight.nvim",
        lazy = false, -- make sure we load this during startup if it is your main colorscheme
        priority = 1000, -- make sure to load this before all the other start plugins
        config = function()
          -- load the colorscheme here
          vim.cmd([[colorscheme tokyonight]])
        end,
      },
    
      -- I have a separate config.mappings file where I require which-key.
      -- With lazy the plugin will be automatically loaded when it is required somewhere
      { "folke/which-key.nvim", lazy = true },
    
      {
        "nvim-neorg/neorg",
        -- lazy-load on filetype
        ft = "norg",
        -- options for neorg. This will automatically call `require("neorg").setup(opts)`
        opts = {
          load = {
            ["core.defaults"] = {},
          },
        },
      },
    
      {
        "dstein64/vim-startuptime",
        -- lazy-load on a command
        cmd = "StartupTime",
        -- init is called during startup. Configuration for vim plugins typically should be set in an init function
        init = function()
          vim.g.startuptime_tries = 10
        end,
      },
    
      {
        "hrsh7th/nvim-cmp",
        -- load cmp on InsertEnter
        event = "InsertEnter",
        -- these dependencies will only be loaded when cmp loads
        -- dependencies are always lazy-loaded unless specified otherwise
        dependencies = {
          "hrsh7th/cmp-nvim-lsp",
          "hrsh7th/cmp-buffer",
        },
        config = function()
          -- ...
        end,
      },
    
      -- if some code requires a module from an unloaded plugin, it will be automatically loaded.
      -- So for api plugins like devicons, we can always set lazy=true
      { "nvim-tree/nvim-web-devicons", lazy = true },
    
      -- you can use the VeryLazy event for things that can
      -- load later and are not important for the initial UI
      { "stevearc/dressing.nvim", event = "VeryLazy" },
    
      {
        "Wansmer/treesj",
        keys = {
          { "J", "<cmd>TSJToggle<cr>", desc = "Join Toggle" },
        },
        opts = { use_default_keymaps = false, max_join_length = 150 },
      },
    
      {
        "monaqa/dial.nvim",
        -- lazy-load on keys
        -- mode is `n` by default. For more advanced options, check the section on key mappings
        keys = { "<C-a>", { "<C-x>", mode = "n" } },
      },
    
      -- local plugins need to be explicitly configured with dir
      { dir = "~/projects/secret.nvim" },
    
      -- you can use a custom url to fetch a plugin
      { url = "git@github.com:folke/noice.nvim.git" },
    
      -- local plugins can also be configured with the dev option.
      -- This will use {config.dev.path}/noice.nvim/ instead of fetching it from GitHub
      -- With the dev option, you can easily switch between the local and installed version of a plugin
      { "folke/noice.nvim", dev = true },
    }
<


LAZY LOADING                         *lazy.nvim-🔌-plugin-spec-lazy-loading*

**lazy.nvim** automagically lazy-loads Lua modules. This means that if you have
a plugin `A` that is lazy-loaded and a plugin `B` that requires a module of
plugin `A`, then plugin `A` will be loaded on demand as expected.


Additionally, you can also lazy-load on **events**, **commands**, **file
types** and **key mappings**.

Plugins will be lazy-loaded when one of the following is `true`:

- The plugin only exists as a dependency in your spec
- It has an `event`, `cmd`, `ft` or `keys` key
- `config.defaults.lazy == true`


🌈 COLORSCHEMES ~

Colorscheme plugins can be configured with `lazy=true`. The plugin will
automagically load when doing `colorscheme foobar`.



⌨️ LAZY KEY MAPPINGS ~

The `keys` property can be a `string` or `string[]` for simple normal-mode
mappings, or it can be a `LazyKeysSpec` table with the following key-value
pairs:

- **[1]**: (`string`) lhs **(required)**
- **[2]**: (`string|fun()`) rhs **(optional)**
- **mode**: (`string|string[]`) mode **(optional, defaults to "n")**
- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **(optional)**
- any other option valid for `vim.keymap.set`

Key mappings will load the plugin the first time they get executed.

When `[2]` is `nil`, then the real mapping has to be created by the `config()`
function.

>lua
    -- Example for neo-tree.nvim
    {
      "nvim-neo-tree/neo-tree.nvim",
        keys = {
          { "<leader>ft", "<cmd>Neotree toggle<cr>", desc = "NeoTree" },
        },
        config = function()
          require("neo-tree").setup()
        end,
    }
<


VERSIONING                             *lazy.nvim-🔌-plugin-spec-versioning*

If you want to install a specific revision of a plugin, you can use `commit`,
`tag`, `branch`, `version`.

The `version` property supports Semver <https://semver.org/> ranges.



EXAMPLES ~

- `*`: latest stable version (this excludes pre-release versions)
- `1.2.x`: any version that starts with `1.2`, such as `1.2.0`, `1.2.3`, etc.
- `^1.2.3`: any version that is compatible with `1.2.3`, such as `1.3.0`, `1.4.5`, etc., but not `2.0.0`.
- `~1.2.3`: any version that is compatible with `1.2.3`, such as `1.2.4`, `1.2.5`, but not `1.3.0`.
- `>1.2.3`: any version that is greater than `1.2.3`, such as `1.3.0`, `1.4.5`, etc.
- `>=1.2.3`: any version that is greater than or equal to `1.2.3`, such as `1.2.3`, `1.3.0`, `1.4.5`, etc.
- `<1.2.3`: any version that is less than `1.2.3`, such as `1.1.0`, `1.0.5`, etc.
- `<=1.2.3`: any version that is less than or equal to `1.2.3`, such as `1.2.3`, `1.1.0`, `1.0.5`, etc


==============================================================================
5. 📦 Packages                                     *lazy.nvim-📦-packages*

**lazy.nvim** supports three ways for plugins to define their dependencies and
configuration.

- **Lazy**: `lazy.lua` file
- **Rockspec**: luarocks <https://luarocks.org/> `*-scm-1.rockspec` file <https://github.com/luarocks/luarocks/wiki/Rockspec-format>
- **Packspec**: `pkg.json` (experimental, since the format <https://github.com/neovim/packspec/issues/41> is not quite there yet)

You can enable/disable package sources with `config.pkg.sources`
</configuration>. The order of sources is important, as the first source that
finds a package will be used.



LAZY                                            *lazy.nvim-📦-packages-lazy*

Using a `lazy.lua` file is the recommended way to define your plugin
dependencies and configuration. Syntax is the same as any plugin spec.


ROCKSPEC                                    *lazy.nvim-📦-packages-rockspec*

When a plugin contains a `*-1.rockspec` file, **lazy.nvim** will automatically
build the rock and its dependencies.

A **rockspec** will only be used if one of the following is true:

- the package does not have a `/lua` directory
- the package has a complex build step
- the package has dependencies (excluding `lua`)


PACKSPEC                                    *lazy.nvim-📦-packages-packspec*

Supports the pkg.json
<https://github.com/nvim-lua/nvim-package-specification/issues/41> format, with
a lazy extension in `lazy`. `lazy` can contain any valid lazy spec fields. They
will be added to the plugin’s spec.


==============================================================================
6. ⚙️ Configuration                       *lazy.nvim-⚙️-configuration*

**lazy.nvim** comes with the following defaults:

>lua
    {
      root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed
      defaults = {
        -- Set this to `true` to have all your plugins lazy-loaded by default.
        -- Only do this if you know what you are doing, as it can lead to unexpected behavior.
        lazy = false, -- should plugins be lazy-loaded?
        -- It's recommended to leave version=false for now, since a lot the plugin that support versioning,
        -- have outdated releases, which may break your Neovim install.
        version = nil, -- always use the latest git commit
        -- version = "*", -- try installing the latest stable version for plugins that support semver
        -- default `cond` you can use to globally disable a lot of plugins
        -- when running inside vscode for example
        cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil
      },
      -- leave nil when passing the spec as the first argument to setup()
      spec = nil, ---@type LazySpec
      local_spec = true, -- load project specific .lazy.lua spec files. They will be added at the end of the spec.
      lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update.
      ---@type number? limit the maximum amount of concurrent tasks
      concurrency = jit.os:find("Windows") and (vim.uv.available_parallelism() * 2) or nil,
      git = {
        -- defaults for the `Lazy log` command
        -- log = { "--since=3 days ago" }, -- show commits from the last 3 days
        log = { "-8" }, -- show the last 8 commits
        timeout = 120, -- kill processes that take more than 2 minutes
        url_format = "https://github.com/%s.git",
        -- lazy.nvim requires git >=2.19.0. If you really want to use lazy with an older version,
        -- then set the below to false. This should work, but is NOT supported and will
        -- increase downloads a lot.
        filter = true,
      },
      pkg = {
        enabled = true,
        cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua",
        versions = true, -- Honor versions in pkg sources
        -- the first package source that is found for a plugin will be used.
        sources = {
          "lazy",
          "rockspec",
          "packspec",
        },
      },
      rocks = {
        root = vim.fn.stdpath("data") .. "/lazy-rocks",
        server = "https://nvim-neorocks.github.io/rocks-binaries/",
      },
      dev = {
        ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects
        path = "~/projects",
        ---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub
        patterns = {}, -- For example {"folke"}
        fallback = false, -- Fallback to git when local plugin doesn't exist
      },
      install = {
        -- install missing plugins on startup. This doesn't increase startup time.
        missing = true,
        -- try to load one of these colorschemes when starting an installation during startup
        colorscheme = { "habamax" },
      },
      ui = {
        -- a number <1 is a percentage., >1 is a fixed size
        size = { width = 0.8, height = 0.8 },
        wrap = true, -- wrap the lines in the ui
        -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
        border = "none",
        -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent.
        backdrop = 60,
        title = nil, ---@type string only works when border is not "none"
        title_pos = "center", ---@type "center" | "left" | "right"
        -- Show pills on top of the Lazy window
        pills = true, ---@type boolean
        icons = {
          cmd = " ",
          config = "",
          event = " ",
          favorite = " ",
          ft = " ",
          init = " ",
          import = " ",
          keys = " ",
          lazy = "󰒲 ",
          loaded = "●",
          not_loaded = "○",
          plugin = " ",
          runtime = " ",
          require = "󰢱 ",
          source = " ",
          start = " ",
          task = "✔ ",
          list = {
            "●",
            "➜",
            "★",
            "‒",
          },
        },
        -- leave nil, to automatically select a browser depending on your OS.
        -- If you want to use a specific browser, you can define it here
        browser = nil, ---@type string?
        throttle = 20, -- how frequently should the ui process render events
        custom_keys = {
          -- You can define custom key maps here. If present, the description will
          -- be shown in the help menu.
          -- To disable one of the defaults, set it to false.
    
          ["<localleader>l"] = {
            function(plugin)
              require("lazy.util").float_term({ "lazygit", "log" }, {
                cwd = plugin.dir,
              })
            end,
            desc = "Open lazygit log",
          },
    
          ["<localleader>t"] = {
            function(plugin)
              require("lazy.util").float_term(nil, {
                cwd = plugin.dir,
              })
            end,
            desc = "Open terminal in plugin dir",
          },
        },
      },
      diff = {
        -- diff command <d> can be one of:
        -- * browser: opens the github compare view. Note that this is always mapped to <K> as well,
        --   so you can have a different command for diff <d>
        -- * git: will run git diff and open a buffer with filetype git
        -- * terminal_git: will open a pseudo terminal with git diff
        -- * diffview.nvim: will open Diffview to show the diff
        cmd = "git",
      },
      checker = {
        -- automatically check for plugin updates
        enabled = false,
        concurrency = nil, ---@type number? set to 1 to check for updates very slowly
        notify = true, -- get a notification when new updates are found
        frequency = 3600, -- check for updates every hour
        check_pinned = false, -- check for pinned packages that can't be updated
      },
      change_detection = {
        -- automatically check for config file changes and reload the ui
        enabled = true,
        notify = true, -- get a notification when changes are found
      },
      performance = {
        cache = {
          enabled = true,
        },
        reset_packpath = true, -- reset the package path to improve startup time
        rtp = {
          reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory
          ---@type string[]
          paths = {}, -- add any custom paths here that you want to includes in the rtp
          ---@type string[] list any plugins you want to disable here
          disabled_plugins = {
            -- "gzip",
            -- "matchit",
            -- "matchparen",
            -- "netrwPlugin",
            -- "tarPlugin",
            -- "tohtml",
            -- "tutor",
            -- "zipPlugin",
          },
        },
      },
      -- lazy can generate helptags from the headings in markdown readme files,
      -- so :help works even for plugins that don't have vim docs.
      -- when the readme opens with :help it will be correctly displayed as markdown
      readme = {
        enabled = true,
        root = vim.fn.stdpath("state") .. "/lazy/readme",
        files = { "README.md", "lua/**/README.md" },
        -- only generate markdown helptags for plugins that dont have docs
        skip_if_doc_exists = true,
      },
      state = vim.fn.stdpath("state") .. "/lazy/state.json", -- state info for checker and other things
      -- Enable profiling of lazy.nvim. This will add some overhead,
      -- so only enable this when you are debugging lazy.nvim
      profiling = {
        -- Enables extra stats on the debug tab related to the loader cache.
        -- Additionally gathers stats about all package.loaders
        loader = false,
        -- Track each new require in the Lazy profiling tab
        require = false,
      },
    }
<

If you don’t want to use a Nerd Font, you can replace the icons with Unicode symbols. ~

>lua
    {
      ui = {
        icons = {
          cmd = "⌘",
          config = "🛠",
          event = "📅",
          ft = "📂",
          init = "⚙",
          keys = "🗝",
          plugin = "🔌",
          runtime = "💻",
          require = "🌙",
          source = "📄",
          start = "🚀",
          task = "📌",
          lazy = "💤 ",
        },
      },
    }
<


🌈 HIGHLIGHT GROUPS   *lazy.nvim-⚙️-configuration-🌈-highlight-groups*

  -----------------------------------------------------------------------
  Highlight Group         Default Group           Description
  ----------------------- ----------------------- -----------------------
  LazyButton              CursorLine              

  LazyButtonActive        Visual                  

  LazyComment             Comment                 

  LazyCommit              @variable.builtin       commit ref

  LazyCommitIssue         Number                  

  LazyCommitScope         Italic                  conventional commit
                                                  scope

  LazyCommitType          Title                   conventional commit
                                                  type

  LazyDimmed              Conceal                 property

  LazyDir                 @markup.link            directory

  LazyH1                  IncSearch               home button

  LazyH2                  Bold                    titles

  LazyLocal               Constant                

  LazyNoCond              DiagnosticWarn          unloaded icon for a
                                                  plugin where cond() was
                                                  false

  LazyNormal              NormalFloat             

  LazyProgressDone        Constant                progress bar done

  LazyProgressTodo        LineNr                  progress bar todo

  LazyProp                Conceal                 property

  LazyReasonCmd           Operator                

  LazyReasonEvent         Constant                

  LazyReasonFt            Character               

  LazyReasonImport        Identifier              

  LazyReasonKeys          Statement               

  LazyReasonPlugin        Special                 

  LazyReasonRequire       @variable.parameter     

  LazyReasonRuntime       @macro                  

  LazyReasonSource        Character               

  LazyReasonStart         @variable.member        

  LazySpecial             @punctuation.special    

  LazyTaskError           ErrorMsg                task errors

  LazyTaskOutput          MsgArea                 task output

  LazyUrl                 @markup.link            url

  LazyValue               @string                 value of a property
  -----------------------------------------------------------------------

==============================================================================
7. 🚀 Usage                                           *lazy.nvim-🚀-usage*


▶️ STARTUP SEQUENCE         *lazy.nvim-🚀-usage-▶️-startup-sequence*

**lazy.nvim** does **NOT** use Neovim packages and even disables plugin loading
completely (`vim.go.loadplugins = false`). It takes over the complete startup
sequence for more flexibility and better performance.

In practice this means that step 10 of |Neovim Initialization| is done by Lazy:

1. All the plugins’ `init()` functions are executed
2. All plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet)
3. All files from `/plugin` and `/ftdetect` directories in your rtp are sourced (excluding `/after`)
4. All `/after/plugin` files are sourced (this includes `/after` from plugins)

Files from runtime directories are always sourced in alphabetical order.


🚀 COMMANDS                             *lazy.nvim-🚀-usage-🚀-commands*

Plugins are managed with the `:Lazy` command. Open the help with `<?>` to see
all the key mappings.

You can press `<CR>` on a plugin to show its details. Most properties can be
hovered with `<K>` to open links, help files, readmes, git commits and git
issues.

Lazy can automatically check for updates in the background. This feature can be
enabled with `config.checker.enabled = true`.

Any operation can be started from the UI, with a sub command or an API
function:

  ----------------------------------------------------------------------------------
  Command                   Lua                              Description
  ------------------------- -------------------------------- -----------------------
  :Lazy build {plugins}     require("lazy").build(opts)      Rebuild a plugin

  :Lazy check [plugins]     require("lazy").check(opts?)     Check for updates and
                                                             show the log (git
                                                             fetch)

  :Lazy clean [plugins]     require("lazy").clean(opts?)     Clean plugins that are
                                                             no longer needed

  :Lazy clear               require("lazy").clear()          Clear finished tasks

  :Lazy debug               require("lazy").debug()          Show debug information

  :Lazy health              require("lazy").health()         Run :checkhealth lazy

  :Lazy help                require("lazy").help()           Toggle this help page

  :Lazy home                require("lazy").home()           Go back to plugin list

  :Lazy install [plugins]   require("lazy").install(opts?)   Install missing plugins

  :Lazy load {plugins}      require("lazy").load(opts)       Load a plugin that has
                                                             not been loaded yet.
                                                             Similar to :packadd.
                                                             Like
                                                             :Lazy load foo.nvim.
                                                             Use :Lazy! load to skip
                                                             cond checks.

  :Lazy log [plugins]       require("lazy").log(opts?)       Show recent updates

  :Lazy profile             require("lazy").profile()        Show detailed profiling

  :Lazy reload {plugins}    require("lazy").reload(opts)     Reload a plugin
                                                             (experimental!!)

  :Lazy restore [plugins]   require("lazy").restore(opts?)   Updates all plugins to
                                                             the state in the
                                                             lockfile. For a single
                                                             plugin: restore it to
                                                             the state in the
                                                             lockfile or to a given
                                                             commit under the cursor

  :Lazy sync [plugins]      require("lazy").sync(opts?)      Run install, clean and
                                                             update

  :Lazy update [plugins]    require("lazy").update(opts?)    Update plugins. This
                                                             will also update the
                                                             lockfile
  ----------------------------------------------------------------------------------
Any command can have a **bang** to make the command wait till it finished. For
example, if you want to sync lazy from the cmdline, you can use:

>shell
    nvim --headless "+Lazy! sync" +qa
<

`opts` is a table with the following key-values:

- **wait**: when true, then the call will wait till the operation completed
- **show**: when false, the UI will not be shown
- **plugins**: a list of plugin names to run the operation on
- **concurrency**: limit the `number` of concurrently running tasks

Stats API (`require("lazy").stats()`):

>lua
    {
      -- startuptime in milliseconds till UIEnter
      startuptime = 0,
      -- when true, startuptime is the accurate cputime for the Neovim process. (Linux & macOS)
      -- this is more accurate than `nvim --startuptime`, and as such will be slightly higher
      -- when false, startuptime is calculated based on a delta with a timestamp when lazy started.
      real_cputime = false,
      count = 0, -- total number of plugins
      loaded = 0, -- number of loaded plugins
      ---@type table<string, number>
      times = {},
    }
<

**lazy.nvim** provides a statusline component that you can use to show the
number of pending updates. Make sure to enable `config.checker.enabled = true`
to make this work.

Example of configuring lualine.nvim ~

>lua
    require("lualine").setup({
      sections = {
        lualine_x = {
          {
            require("lazy.status").updates,
            cond = require("lazy.status").has_updates,
            color = { fg = "#ff9e64" },
          },
        },
      },
    })
<


📆 USER EVENTS                       *lazy.nvim-🚀-usage-📆-user-events*

The following user events will be triggered:

- **LazyDone**: when lazy has finished starting up and loaded your config
- **LazySync**: after running sync
- **LazyInstall**: after an install
- **LazyUpdate**: after an update
- **LazyClean**: after a clean
- **LazyCheck**: after checking for updates
- **LazyLog**: after running log
- **LazyLoad**: after loading a plugin. The `data` attribute will contain the plugin name.
- **LazySyncPre**: before running sync
- **LazyInstallPre**: before an install
- **LazyUpdatePre**: before an update
- **LazyCleanPre**: before a clean
- **LazyCheckPre**: before checking for updates
- **LazyLogPre**: before running log
- **LazyReload**: triggered by change detection after reloading plugin specs
- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands
- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated.
    Useful to update the startuptime on your dashboard.


❌ UNINSTALLING                       *lazy.nvim-🚀-usage-❌-uninstalling*

To uninstall **lazy.nvim**, you need to remove the following files and
directories:

- **data**: `~/.local/share/nvim/lazy`
- **state**: `~/.local/state/nvim/lazy`
- **lockfile**: `~/.config/nvim/lazy-lock.json`


  Paths can differ if you changed `XDG` environment variables.

🔒 LOCKFILE                             *lazy.nvim-🚀-usage-🔒-lockfile*

After every **update**, the local lockfile (`lazy-lock.json`) is updated with
the installed revisions. It is recommended to have this file under version
control.

If you use your Neovim config on multiple machines, using the lockfile, you can
ensure that the same version of every plugin is installed.

If you are on another machine, you can do `:Lazy restore`, to update all your
plugins to the version from the lockfile.


📦 MIGRATION GUIDE               *lazy.nvim-🚀-usage-📦-migration-guide*


PACKER.NVIM ~

- `setup` ➡️ `init`
- `requires` ➡️ `dependencies`
- `as` ➡️ `name`
- `opt` ➡️ `lazy`
- `run` ➡️ `build`
- `lock` ➡️ `pin`
- `disable=true` ➡️ `enabled = false`
- `tag='*'` ➡️ `version="*"`
- `after` is **not needed** for most use-cases. Use `dependencies` otherwise.
- `wants` is **not needed** for most use-cases. Use `dependencies` otherwise.
- `config` don’t support string type, use `fun(LazyPlugin)` instead.
- `module` is auto-loaded. No need to specify
- `keys` spec is |lazy.nvim-different|
- `rtp` can be accomplished with:

>lua
    config = function(plugin)
        vim.opt.rtp:append(plugin.dir .. "/custom-rtp")
    end
<

With packer `wants`, `requires` and `after` can be used to manage dependencies.
With lazy, this isn’t needed for most of the Lua dependencies. They can be
installed just like normal plugins (even with `lazy=true`) and will be loaded
when other plugins need them. The `dependencies` key can be used to group those
required plugins with the one that requires them. The plugins which are added
as `dependencies` will always be lazy-loaded and loaded when the plugin is
loaded.


PAQ-NVIM ~

- `as` ➡️ `name`
- `opt` ➡️ `lazy`
- `run` ➡️ `build`


⚡ PROFILING & DEBUG             *lazy.nvim-🚀-usage-⚡-profiling-&-debug*

Great care has been taken to make the startup code (`lazy.core`) as efficient
as possible. During startup, all Lua files used before `VimEnter` or
`BufReadPre` are byte-compiled and cached, similar to what impatient.nvim
<https://github.com/lewis6991/impatient.nvim> does.

My config for example loads in about `11ms` with `93` plugins. I do a lot of
lazy-loading though :)

**lazy.nvim** comes with an advanced profiler `:Lazy profile` to help you
improve performance. The profiling view shows you why and how long it took to
load your plugins.


🐛 DEBUG ~

See an overview of active lazy-loading handlers and what’s in the module
cache.


📂 STRUCTURING YOUR PLUGINS*lazy.nvim-🚀-usage-📂-structuring-your-plugins*

Some users may want to split their plugin specs in multiple files. Instead of
passing a spec table to `setup()`, you can use a Lua module. The specs from the
**module** and any top-level **sub-modules** will be merged together in the
final spec, so it is not needed to add `require` calls in your main plugin file
to the other files.

The benefits of using this approach:

- Simple to **add** new plugin specs. Just create a new file in your plugins module.
- Allows for **caching** of all your plugin specs. This becomes important if you have a lot of smaller plugin specs.
- Spec changes will automatically be **reloaded** when they’re updated, so the `:Lazy` UI is always up to date.

Example:

- `~/.config/nvim/init.lua`

>lua
    require("lazy").setup("plugins")
<

- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **(this file is optional)**

>lua
    return {
      "folke/neodev.nvim",
      "folke/which-key.nvim",
      { "folke/neoconf.nvim", cmd = "Neoconf" },
    }
<

- Any lua file in `~/.config/nvim/lua/plugins/*.lua` will be automatically merged in the main plugin spec

For a real-life example, you can check LazyVim
<https://github.com/LazyVim/LazyVim> and more specifically:

- lazyvim.plugins <https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins> contains all the plugin specs that will be loaded


↩️ IMPORTING SPECS, CONFIG & OPTS

As part of a spec, you can add `import` statements to import additional plugin
modules. Both of the `setup()` calls are equivalent:

>lua
    require("lazy").setup("plugins")
    
    -- Same as:
    require("lazy").setup({{import = "plugins"}})
<

To import multiple modules from a plugin, add additional specs for each import.
For example, to import LazyVim core plugins and an optional plugin:

>lua
    require("lazy").setup({
      spec = {
        { "LazyVim/LazyVim", import = "lazyvim.plugins" },
        { import = "lazyvim.plugins.extras.coding.copilot" },
      }
    })
<

When you import specs, you can override them by simply adding a spec for the
same plugin to your local specs, adding any keys you want to override / merge.

`opts`, `dependencies`, `cmd`, `event`, `ft` and `keys` are always merged with
the parent spec. Any other property will override the property from the parent
spec.


==============================================================================
8. 🔥 Developers                                 *lazy.nvim-🔥-developers*

To make it easier for users to install your plugin, you can include a package
spec </packages> in your repo.


BEST PRACTICES                      *lazy.nvim-🔥-developers-best-practices*

- If your plugin needs `setup()`, then create a simple `lazy.lua` file like this:
    >lua
          return { "me/my-plugin", opts = {} }
    <
- Plugins that are pure lua libraries should be lazy-loaded with `lazy = true`.
    >lua
        { "nvim-lua/plenary.nvim", lazy = true }
    <
- Always use `opts` instead of `config` when possible. `config` is almost never
    needed.
- Only use `dependencies` if a plugin needs the dep to be installed **AND**
    loaded. Lua plugins/libraries are automatically loaded when they are
    `require()`d, so they don’t need to be in `dependencies`.
- Inside a `build` function or `*.lua` build file, use
    `coroutine.yield(msg:string|LazyMsg)` to show progress.
- Don’t change the `cwd` in your build function, since builds run in parallel
    and changing the `cwd` will affect other builds.


BUILDING                                  *lazy.nvim-🔥-developers-building*

The spec **build** property can be one of the following:

- `fun(plugin: LazyPlugin)`: a function that builds the plugin.
- `*.lua`: a Lua file that builds the plugin (like `build.lua`)
- `":Command"`: a Neovim command
- `"rockspec"`: this will run `luarocks make` in the plugin’s directory
    This is automatically set by the `rockspec` package </packages> source.
- any other **string** will be run as a shell command
- a `list` of any of the above to run multiple build steps
- if no `build` is specified, but a `build.lua` file exists, that will be used instead.

Build functions and `*.lua` files run asynchronously in a coroutine. Use
`coroutine.yield(msg:string|LazyMsg)` to show progress.

Yielding will also schedule the next `coroutine.resume()` to run in the next
tick, so you can do long-running tasks without blocking Neovim.

>lua
    ---@class LazyMsg
    ---@field msg string
    ---@field level? number vim.log.levels.XXX
<

Use `vim.log.levels.TRACE` to only show the message as a **status** message for
the task.



MINIT (MINIMAL INIT)          *lazy.nvim-🔥-developers-minit-(minimal-init)*

**lazy.nvim** comes with some built-in functionality to help you create a
minimal init for your plugin.

I mainly use this for testing and for users to create a `repro.lua`.

When running in **headless** mode, **lazy.nvim** will log any messages to the
terminal. See `opts.headless` for more info.

**minit** will install/load all your specs and will always run an update as
well.


BOOTSTRAP ~

>lua
    -- setting this env will override all XDG paths
    vim.env.LAZY_STDPATH = ".tests"
    -- this will install lazy in your stdpath
    load(vim.fn.system("curl -s https://raw.githubusercontent.com/folke/lazy.nvim/main/bootstrap.lua"))()
<


TESTING WITH BUSTED ~

This will add `"lunarmodules/busted"`, configure `hererocks` and run `busted`.

Below is an example of how I use **minit** to run tests with busted
<https://olivinelabs.com/busted/> in **LazyVim**.

>lua
    #!/usr/bin/env -S nvim -l
    
    vim.env.LAZY_STDPATH = ".tests"
    load(vim.fn.system("curl -s https://raw.githubusercontent.com/folke/lazy.nvim/main/bootstrap.lua"))()
    
    -- Setup lazy.nvim
    require("lazy.minit").busted({
      spec = {
        "LazyVim/starter",
        "williamboman/mason-lspconfig.nvim",
        "williamboman/mason.nvim",
        "nvim-treesitter/nvim-treesitter",
      },
    })
<

To use this, you can run:

>sh
    nvim -l ./tests/busted.lua tests
<

If you want to inspect the test environment, run:

>sh
    nvim -u ./tests/busted.lua
<


REPRO.LUA ~

>lua
    vim.env.LAZY_STDPATH = ".repro"
    load(vim.fn.system("curl -s https://raw.githubusercontent.com/folke/lazy.nvim/main/bootstrap.lua"))()
    
    require("lazy.minit").repro({
      spec = {
        "stevearc/conform.nvim",
        "nvim-neotest/nvim-nio",
      },
    })
    
    -- do anything else you need to do to reproduce the issue
<

Then run it with:

>sh
    nvim -u repro.lua
<

==============================================================================
9. Links                                                     *lazy.nvim-links*

1. *image*: https://user-images.githubusercontent.com/292349/208301737-68fb279c-ba70-43ef-a369-8c3e8367d6b1.png
2. *image*: https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png
3. *image*: https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png

Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>

vim:tw=78:ts=8:noet:ft=help:norl: