2022-12-18 10:44:05 +00:00
*lazy.nvim.txt* For Neovim >= 0.8.0 Last change: 2022 December 18
2022-11-29 14:42:57 +00:00
==============================================================================
Table of Contents *lazy.nvim-table-of-contents*
1. lazy.nvim |lazy.nvim-lazy.nvim|
- Features |lazy.nvim-features|
2022-12-14 20:42:10 +00:00
- Requirements |lazy.nvim-requirements|
- Installation |lazy.nvim-installation|
2022-12-14 23:23:54 +00:00
- Plugin Spec |lazy.nvim-plugin-spec|
2022-12-14 20:55:03 +00:00
- Configuration |lazy.nvim-configuration|
2022-12-14 20:58:18 +00:00
- Usage |lazy.nvim-usage|
2022-12-14 20:07:51 +00:00
- Profiler |lazy.nvim-profiler|
2022-12-14 20:58:18 +00:00
- 🪲 Debug |lazy.nvim-🪲-debug|
2022-12-16 14:11:06 +00:00
- Startup Sequence |lazy.nvim-startup-sequence|
2022-11-29 14:42:57 +00:00
- Differences with Packer |lazy.nvim-differences-with-packer|
2022-11-30 22:16:15 +00:00
- Other Neovim Plugin Managers in Lua|lazy.nvim-other-neovim-plugin-managers-in-lua|
2022-11-29 14:42:57 +00:00
==============================================================================
1. lazy.nvim *lazy.nvim-lazy.nvim*
2022-12-14 21:11:38 +00:00
**lazy.nvim** is a modern plugin manager for Neovim.
2022-12-14 20:05:17 +00:00
2022-12-14 20:06:06 +00:00
<div class="figure">
2022-12-14 20:18:23 +00:00
<img src="https://user-images.githubusercontent.com/292349/207705153-077e183e-ae5f-4cbe-b1d8-07b7bf86026e.png" title="fig:"/>
2022-12-14 20:06:06 +00:00
<p class="caption">image</p>
</div>
2022-11-29 14:42:57 +00:00
FEATURES *lazy.nvim-features*
2022-12-14 20:05:17 +00:00
2022-12-14 21:11:38 +00:00
- Manage all your Neovim plugins with a sleek and intuitive UI
- Fast startup times thanks to automatic caching and bytecode compilation of lua modules.
2022-12-14 20:05:17 +00:00
- Partial clones instead of shallow clones
2022-12-14 21:11:38 +00:00
- 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.
2022-12-14 20:05:17 +00:00
- Async execution for improved performance
- No need to manually compile plugins
- Correct sequencing of dependencies
- Configurable in multiple files
2022-12-15 13:36:25 +00:00
- Generates helptags of the headings in `README.md` files for plugins that don’
2022-12-14 21:11:38 +00:00
- Dev options and patterns for using local plugins
2022-12-14 20:05:17 +00:00
- Profiling tools to optimize performance
2022-12-14 21:11:38 +00:00
- Lockfile `lazy-lock.json` to keep track of installed plugins
2022-12-14 20:05:17 +00:00
- Automatically check for updates
- Commit, branch, tag, version, and full Semver <https://devhints.io/semver> support
- Statusline component to see the number of pending updates
2022-12-14 20:42:10 +00:00
REQUIREMENTS *lazy.nvim-requirements*
2022-12-18 10:59:37 +00:00
- Neovim >= **0.8.0** (needs to be built with **LuaJIT**)
2022-12-18 10:44:05 +00:00
- Built for **Linux** and **MacOS**
2022-12-18 10:59:37 +00:00
- Git >= **2.19.0** (for partial clones support)
2022-12-14 20:42:10 +00:00
INSTALLATION *lazy.nvim-installation*
You can use the following Lua code to bootstrap **lazy.nvim**
2022-12-15 08:07:46 +00:00
>lua
2022-12-14 23:23:54 +00:00
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"--single-branch",
2022-12-16 14:11:06 +00:00
"git@github.com:folke/lazy.nvim.git",
2022-12-14 23:23:54 +00:00
lazypath,
})
end
2022-12-16 14:11:06 +00:00
vim.opt.runtimepath:prepend(lazypath)
2022-12-14 20:42:10 +00:00
<
2022-12-14 20:58:18 +00:00
Next step is to add **lazy.nvim** to the top of your `init.lua`
2022-12-14 20:55:03 +00:00
2022-12-15 08:07:46 +00:00
>lua
2022-12-14 20:55:03 +00:00
-- You can use a lua module that contains your plugins.
-- All sub modules of the lua module will also be automatically loaded
-- This is the preferred setup so your plugin specs can be properly cached.
require("lazy").setup("config.plugins", {
2022-12-14 23:30:02 +00:00
-- add any optional configuration here
2022-12-14 20:55:03 +00:00
})
-- Alternatively you can specify a plugin list
require("lazy").setup({
"folke/neodev.nvim",
"folke/which-key.nvim",
{ "folke/neoconf.nvim", cmd = "Neoconf" },
}, {
2022-12-14 23:30:02 +00:00
-- add any optional configuration here
2022-12-14 20:55:03 +00:00
})
<
2022-12-14 23:23:54 +00:00
PLUGIN SPEC *lazy.nvim-plugin-spec*
2022-12-15 07:48:04 +00:00
│ Property │ Type │ Description │
│[1] │string? │Short plugin url. Will be expanded using config.git.url_format │
│**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 dispay name │
│**dev** │boolean? │When true, a local plugin directory will be used instead. See config.dev │
│**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 laz-loading handlers triggers │
│**enabled** │boolean? or fun():boolean │When false, or if the function returns false, then this plugin will not be used │
│**dependencies**│LazySpec[] │A list of plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise │
│**init** │fun(LazyPlugin) │init functions are always executed during startup │
│**config** │fun(LazyPlugin) │config is executed when the plugin loads │
│**build** │fun(LazyPlugin) │build is executed when a plugin is installed or updated │
│**branch** │string? │Branch of the repository │
│**tag** │string? │Tag of the repository │
│**commit** │string? │Commit of the repository │
│**version** │string? │Version to use from the repository. Full Semver <https://devhints.io/semver> ranges are supported │
│**pin** │boolean? │When true, this plugin will not be included in updates │
│**event** │string? or string[] │Lazy-load on event │
│**cmd** │string? or string[] │Lazy-load on command │
│**ft** │string? or string[] │Lazy-load on filetype │
│**keys** │string? or string[] │Lazy-load on key mapping │
2022-12-14 23:30:02 +00:00
2022-12-15 08:07:46 +00:00
>lua
2022-12-14 23:23:54 +00:00
return {
-- the colorscheme should be available when starting Neovim
"folke/tokyonight.nvim",
-- 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",
-- custom config that will be executed when loading the plugin
config = function()
require("neorg").setup()
end,
},
{
"dstein64/vim-startuptime",
-- lazy-load on a command
cmd = "StartupTime",
},
{
"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,
},
-- 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" },
{
"cshuaimin/ssr.nvim",
-- init is always executed during startup, but doesn't load the plugin yet.
-- init implies lazy loading
init = function()
vim.keymap.set({ "n", "x" }, "<leader>cR", function()
-- this require will automatically load the plugin
require("ssr").open()
end, { desc = "Structural Replace" })
end,
},
{
"monaqa/dial.nvim",
-- lazy-load on keys
keys = { "<C-a>", "<C-x>" },
},
-- local plugins need to be explicitely 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 configure with the dev option.
-- This will use ~/projects/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 },
}
<
2022-12-14 20:55:03 +00:00
CONFIGURATION *lazy.nvim-configuration*
**lazy.nvim** comes with the following defaults:
2022-12-15 08:07:46 +00:00
>lua
2022-12-14 20:55:03 +00:00
{
root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed
defaults = {
lazy = false, -- should plugins be lazy-loaded?
version = nil,
-- version = "", -- enable this to try installing the latest stable versions of plugins
},
lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update.
concurrency = nil, ---@type number limit the maximum amount of concurrent tasks
git = {
-- defaults for the `Lazy log` command
-- log = { "-10" }, -- show the last 10 commits
log = { "--since=1 days ago" }, -- show commits from the last 3 days
timeout = 120, -- kill processes that take more than 2 minutes
url_format = "https://github.com/%s.git",
},
dev = {
-- directory where you store your local plugin projects
path = vim.fn.expand("~/projects"),
---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub
patterns = {}, -- For example {"folke"}
},
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 = {
-- The border to use for the UI window. Accepts same border values as |nvim_open_win()|.
border = "none",
icons = {
cmd = " ",
config = "",
event = "",
ft = " ",
init = " ",
keys = " ",
plugin = " ",
runtime = " ",
source = " ",
start = "",
task = " ",
},
throttle = 20, -- how frequently should the ui process render events
},
checker = {
-- automcatilly 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
},
performance = {
2022-12-14 20:59:50 +00:00
cache = {
enabled = true,
path = vim.fn.stdpath("state") .. "/lazy.state",
-- Once one of the following events triggers, caching will be disabled.
-- To cache all modules, set this to `{}`, but that is not recommended.
-- The default is to disable on:
-- VimEnter: not useful to cache anything else beyond startup
-- BufReadPre: this will be triggered early when opening a file from the command line directly
disable_events = { "VimEnter", "BufReadPre" },
},
2022-12-14 20:55:03 +00:00
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[] list any plugins you want to disable here
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
2022-12-15 13:44:45 +00:00
-- 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 = {
root = vim.fn.stdpath("state") .. "/lazy/readme",
files = { "README.md" },
-- only generate markdown helptags for plugins that dont have docs
skip_if_doc_exists = true,
},
2022-12-14 20:55:03 +00:00
}
<
2022-12-14 20:58:18 +00:00
USAGE *lazy.nvim-usage*
2022-12-18 10:44:05 +00:00
You can manage all your plugins with the main `:Lazy` command. Alternatively
you can start any operation with a specific command, sub command or API
function:
│ Command │ Lua │Key Mapping│ Description │
│:Lazy home or :LazyHome │require("lazy").home() │<H> │Go back to plugin list │
│:Lazy install or :LazyInstall │require("lazy").install() │<I> │Install missing plugins │
│:Lazy update or :LazyUpdate │require("lazy").update() │<U> │Update all plugins. This will also update the lockfile│
│:Lazy sync or :LazySync │require("lazy").sync() │<S> │Run install, clean and update │
│:Lazy clean or :LazyClean │require("lazy").clean() │<X> │Clean plugins that are no longer needed │
│:Lazy check or :LazyCheck │require("lazy").check() │<C> │Check for updates and show the log (git fetch) │
│:Lazy log or :LazyLog │require("lazy").log() │<L> │Show recent updates for all plugins │
│:Lazy restore or :LazyRestore │require("lazy").restore() │<R> │Updates all plugins to the state in the lockfile │
│:Lazy profile or :LazyProfile │require("lazy").profile() │<P> │Show detailed profiling │
│:Lazy debug or :LazyDebug │require("lazy").debug() │<D> │Show debug information │
│:Lazy help or :LazyHelp │require("lazy").help() │<?> │Toggle this help page │
│:Lazy clear or :LazyClear │require("lazy").clear() │ │Clear finished tasks │
2022-12-14 20:07:51 +00:00
PROFILER *lazy.nvim-profiler*
2022-12-14 20:11:48 +00:00
The profiling view shows you why and how long it took to load your plugins.
2022-12-14 20:07:51 +00:00
<div class="figure">
<img src="https://user-images.githubusercontent.com/292349/207703263-3b38ca45-9779-482b-b684-4f8c3b3e76d0.png" title="fig:"/>
<p class="caption">image</p>
</div>
2022-12-14 20:58:18 +00:00
🪲 DEBUG *lazy.nvim-🪲-debug*
2022-12-14 20:11:48 +00:00
See an overview of active lazy-loading handlers and what’
cache
2022-12-14 20:09:17 +00:00
<div class="figure">
<img src="https://user-images.githubusercontent.com/292349/207703522-8bb20678-bb4c-4424-80e4-add3219711c3.png" title="fig:"/>
<p class="caption">image</p>
</div>
2022-12-16 14:11:06 +00:00
STARTUP SEQUENCE *lazy.nvim-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.
2022-12-18 10:44:05 +00:00
In practice this means that step 10 of |Neovim Initialization| is done by Lazy:
1. all files from `/plugin` and `/ftdetect` directories in you rtp are sourced (excluding `/after`)
2. all plugins with `lazy=false` are loaded. This includes sourcing `/plugin` and `/ftdetect` files. (`/after` will not be sourced yet)
3. all plugins’
4. all `/after/plugin` files from the original rtp are sourced
5. all the plugins’
Files from runtime directories are always sourced in alphabetical order.
2022-12-16 14:11:06 +00:00
2022-11-29 14:42:57 +00:00
DIFFERENCES WITH PACKER *lazy.nvim-differences-with-packer*
- **Plugin Spec**:
- `setup` => `init`
- `requires` => `dependencies`
- `as` => `name`
2022-12-01 10:33:48 +00:00
- `opt` => `lazy`
2022-12-01 12:34:59 +00:00
- `run` => `build`
2022-12-02 08:26:19 +00:00
- `lock` => `pin`
- `module` is auto-loaded. No need to specify
2022-11-29 14:42:57 +00:00
2022-11-30 22:16:15 +00:00
OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-other-neovim-plugin-managers-in-lua*
- packer.nvim <https://github.com/wbthomason/packer.nvim>
- paq-nvim <https://github.com/savq/paq-nvim>
- neopm <https://github.com/ii14/neopm>
- dep <https://github.com/chiyadev/dep>
- optpack.nvim <https://github.com/notomo/optpack.nvim>
2022-12-03 16:47:26 +00:00
- pact.nvim <https://github.com/rktjmp/pact.nvim>
2022-11-30 22:16:15 +00:00
2022-11-29 14:42:57 +00:00
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
vim:tw=78:ts=8:noet:ft=help:norl:
