From 93c9a3f872153247cef14f095d2d037b7c93704f Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Sun, 7 Jul 2024 15:14:44 +0000 Subject: [PATCH] chore(build): auto-generate docs --- doc/lazy.nvim.txt | 1398 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 1352 insertions(+), 46 deletions(-) diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt index b3fad77..73bd0ae 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -1,61 +1,130 @@ -*lazy.nvim.txt* For Neovim Last change: 2024 July 07 +*lazy.nvim.txt* A modern plugin manager for Neovim ============================================================================== Table of Contents *lazy.nvim-table-of-contents* - - Features |lazy.nvim-features| - - Requirements |lazy.nvim-requirements| - - Getting Started |lazy.nvim-getting-started| -1. Links |lazy.nvim-links| -Install -Β· -Configure -Β· -Docs - - - - - - - - - - - - - - +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 . 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 can now specify their dependencies + and configuration using one of: + - **Lazy**: `lazy.lua` file + - **Rockspec**: luarocks `*-scm-1.rockspec` file + - **Packspec**: `pkg.json` (experimental, since the format 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 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-features* +✨ 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 support -- Statusline component to see the number of pending updates -- Automatically lazy-loads colorschemes +- πŸ“¦ 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 support +- πŸ“ˆ Statusline component to see the number of pending updates +- 🎨 Automatically lazy-loads colorschemes -REQUIREMENTS *lazy.nvim-requirements* +⚑️ REQUIREMENTS *lazy.nvim-πŸš€-getting-started-⚑️-requirements* - Neovim >= **0.8.0** (needs to be built with **LuaJIT**) - Git >= **2.19.0** (for partial clones support) @@ -64,14 +133,1251 @@ REQUIREMENTS *lazy.nvim-requirements* You can remove `rockspec` from `opts.pkg.sources` to disable this feature. -GETTING STARTED *lazy.nvim-getting-started* +============================================================================== +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 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 + + +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 }, + }) +< -Check the documentation website for more information. ============================================================================== -1. Links *lazy.nvim-links* +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", "TSJToggle", 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 = { "", { "", 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 = { + { "ft", "Neotree toggle", 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 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 `*-scm-1.rockspec` file +- **Packspec**: `pkg.json` (experimental, since the format is not quite there yet) + +You can enable/disable package sources with `config.pkg.sources` +. 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 + 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. + + ["l"] = { + function(plugin) + require("lazy.util").float_term({ "lazygit", "log" }, { + cwd = plugin.dir, + }) + end, + desc = "Open lazygit log", + }, + + ["t"] = { + function(plugin) + require("lazy.util").float_term(nil, { + cwd = plugin.dir, + }) + end, + desc = "Open terminal in plugin dir", + }, + }, + }, + diff = { + -- diff command can be one of: + -- * browser: opens the github compare view. Note that this is always mapped to as well, + -- so you can have a different command for diff + -- * 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 `` on a plugin to show its details. Most properties can be +hovered with `` 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 + 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 + 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 + and more specifically: + +- 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 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 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 + 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