diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt index c2c9695..476bdf7 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -1,130 +1,61 @@ -*lazy.nvim.txt* A modern plugin manager for Neovim +*lazy.nvim.txt* For Neovim Last change: 2024 July 08 ============================================================================== 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?* + - Features |lazy.nvim-features| + - Requirements |lazy.nvim-requirements| + - Getting Started |lazy.nvim-getting-started| +1. Links |lazy.nvim-links| +Install +Β· +Configure +Β· +Docs + + + + + + + + + + + + + + -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-πŸš€-getting-started-✨-features* +FEATURES *lazy.nvim-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-πŸš€-getting-started-⚑️-requirements* +REQUIREMENTS *lazy.nvim-requirements* - Neovim >= **0.8.0** (needs to be built with **LuaJIT**) - Git >= **2.19.0** (for partial clones support) @@ -133,1251 +64,14 @@ Table of Contents *lazy.nvim-table-of-contents* 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 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 }, - }) -< +GETTING STARTED *lazy.nvim-getting-started* +Check the documentation website for more information. ============================================================================== -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 startup. 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. 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