lazy.nvim/doc/lazy.nvim.txt

695 lines
31 KiB
Plaintext
Raw Normal View History

2022-12-23 06:49:37 +00:00
*lazy.nvim.txt* For Neovim >= 0.8.0 Last change: 2022 December 23
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-18 13:34:41 +00:00
- Lockfile `lazy-lock.json` |lazy.nvim-lockfile-`lazy-lock.json`|
2022-12-20 09:56:46 +00:00
- Performance |lazy.nvim-performance|
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-12-19 20:06:18 +00:00
- Structuring Your Plugins |lazy.nvim-structuring-your-plugins|
2022-12-20 09:25:55 +00:00
- Migration Guide |lazy.nvim-migration-guide|
2022-12-19 13:31:18 +00:00
- Uninstalling |lazy.nvim-uninstalling|
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-18 13:48:03 +00:00
<img src="https://user-images.githubusercontent.com/292349/208301737-68fb279c-ba70-43ef-a369-8c3e8367d6b1.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-19 20:06:18 +00:00
- Manage all your Neovim plugins with a powerful UI
2022-12-19 20:28:48 +00:00
- 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-19 20:28:48 +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 dont have vimdocs
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-22 12:50:12 +00:00
- Automatically lazy-loads colorschemes
2022-12-14 20:05:17 +00:00
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**)
- Git >= **2.19.0** (for partial clones support)
2022-12-19 18:10:49 +00:00
- a Nerd Font <https://www.nerdfonts.com/> **_(optional)_**
2022-12-14 20:42:10 +00:00
INSTALLATION *lazy.nvim-installation*
2022-12-20 20:16:27 +00:00
You can add the following Lua code to your `init.lua` to bootstrap
**lazy.nvim**
2022-12-14 20:42:10 +00:00
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"
2022-12-21 10:43:46 +00:00
if not vim.loop.fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"--single-branch",
"https://github.com/folke/lazy.nvim.git",
lazypath,
})
end
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-19 20:06:18 +00:00
require("lazy").setup(plugins, opts)
2022-12-14 20:55:03 +00:00
<
2022-12-18 13:50:01 +00:00
2022-12-19 20:06:18 +00:00
- **plugins**: this should be a `table` or a `string`
- `table`: a list with your |lazy.nvim-plugin-spec|
- `string`: a Lua module name that contains your |lazy.nvim-plugin-spec|. See |lazy.nvim-structuring-your-plugins|
- **opts**: see |lazy.nvim-configuration| **_(optional)_**
>lua
-- example using a list of specs with the default options
2022-12-20 20:16:27 +00:00
vim.g.mapleader = " " -- make sure to set `mapleader` before lazy so your mappings are correct
2022-12-19 20:06:18 +00:00
require("lazy").setup({
"folke/which-key.nvim",
{ "folke/neoconf.nvim", cmd = "Neoconf" },
"folke/neodev.nvim",
})
<
2022-12-18 13:50:01 +00:00
2022-12-19 20:06:18 +00:00
It is recommended to run `:checkhealth lazy` after installation
2022-12-18 13:50:01 +00:00
2022-12-14 23:23:54 +00:00
PLUGIN SPEC *lazy.nvim-plugin-spec*
2022-12-23 06:51:44 +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 display 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 lazy-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) or true or table │config is executed when the plugin loads. You can also set to true or pass a table, that will be passed to require("plugin").setup(opts) │
│**build** │fun(LazyPlugin) or string │build is executed when a plugin is installed or updated. If its a string it will be ran as a shell command. When prefixed with : it is a Neovim command. │
│**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[] or LazyKeys[] │Lazy-load on key mapping │
│**module** │false? │Do not automatically load this Lua module when its required somewhere │
2022-12-14 23:30:02 +00:00
2022-12-18 13:29:46 +00:00
LAZY LOADING ~
**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to
specify `module=...` everywhere in your plugin specification. This mean 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.
2022-12-19 13:57:32 +00:00
If you dont want this behavior for a certain plugin, you can specify that
with `module=false`. You can then manually load the plugin with `:Lazy load
foobar.nvim`.
2022-12-22 12:50:12 +00:00
Colorscheme plugins can be configured with `lazy=true`. The plugin will
automagically load when doing `colorscheme foobar`.
2022-12-19 20:06:18 +00:00
You can configure **lazy.nvim** to lazy-load all plugins by default with
`config.defaults.lazy = true`.
2022-12-18 13:29:46 +00:00
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
2022-12-21 18:49:36 +00:00
- it has an `event`, `cmd`, `ft` or `keys` key
2022-12-18 13:29:46 +00:00
- `config.defaults.lazy == true`
2022-12-22 09:33:10 +00:00
*lazy.nvim-Lazy-Key-Mappings*
Lazy Key Mappings The `keys` property can be a `string` or
`string[]` for simple normal-mode
mappings, or it can be a `LazyKeys`
table with the following key-value
pairs:
- **[1]**: (`string`) lhs **_(required)_**
- **[2]**: (`string|fun()`) rhs **_(optional)_**
- **mode**: (`string|string[]`) mode **_(optional, defaults to `"n"`)_**
- any other option valid for `vim.keymap.set`
Key mappings will load the plugin the first time they get executed.
When `[2]` is `nil`, then the real mapping has to be created by the `config()`
function.
>lua
-- Example for neo-tree.nvim
{
"nvim-neo-tree/neo-tree.nvim",
keys = {
{ "<leader>ft", "<cmd>Neotree toggle<cr>", desc = "NeoTree" },
},
config = function()
require("neo-tree").setup()
end,
}
<
2022-12-18 13:29:46 +00:00
VERSIONING ~
If you want to install a specific revision of a plugin, you can use `commit`,
`tag`, `branch`, `version`.
2022-12-19 20:06:18 +00:00
The `version` property supports Semver <https://semver.org/> ranges.
Click to see some examples
2022-12-18 13:29:46 +00:00
- :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
2022-12-19 20:06:18 +00:00
You can set `config.defaults.version = ""` to install the latest stable version
of plugins that support Semver.
2022-12-18 13:29:46 +00:00
EXAMPLES ~
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,
},
2022-12-22 21:50:05 +00:00
-- the above could also be written as
{
"nvim-neorg/neorg",
ft = "norg",
config = true, -- run require("norg").setup()
},
-- or set custom config
{
"nvim-neorg/neorg",
ft = "norg",
config = { foo = "bar" }, -- run require("norg").setup({foo = "bar"})
},
2022-12-14 23:23:54 +00:00
{
"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
2022-12-20 09:27:34 +00:00
-- load later and are not important for the initial UI
{ "stevearc/dressing.nvim", event = "VeryLazy" },
2022-12-14 23:23:54 +00:00
{
"cshuaimin/ssr.nvim",
-- init is always executed during startup, but doesn't load the plugin yet.
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
2022-12-23 18:04:19 +00:00
-- mode is `n` by default. For more advanced options, check the section on key mappings
keys = { "<C-a>", { "<C-x>", mode = "n" } },
2022-12-14 23:23:54 +00:00
},
2022-12-19 12:38:06 +00:00
-- local plugins need to be explicitly configured with dir
2022-12-14 23:23:54 +00:00
{ 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.
2022-12-20 13:02:51 +00:00
-- This will use {config.dev.path}/noice.nvim/ instead of fetching it from Github
2022-12-14 23:23:54 +00:00
-- 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
2022-12-20 13:14:47 +00:00
log = { "--since=3 days ago" }, -- show commits from the last 3 days
2022-12-14 20:55:03 +00:00
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
2022-12-20 09:27:34 +00:00
path = "~/projects",
2022-12-14 20:55:03 +00:00
---@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 = {
2022-12-20 18:30:15 +00:00
-- a number <1 is a percentage., >1 is a fixed size
size = { width = 0.8, height = 0.8 },
2022-12-14 20:55:03 +00:00
-- 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 = {
2022-12-19 12:38:06 +00:00
-- automatically check for plugin updates
2022-12-14 20:55:03 +00:00
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
},
2022-12-20 18:39:54 +00:00
change_detection = {
-- automatically check for config file changes and reload the ui
enabled = true,
notify = true, -- get a notification when changes are found
},
2022-12-14 20:55:03 +00:00
performance = {
2022-12-14 20:59:50 +00:00
cache = {
enabled = true,
2022-12-23 11:27:29 +00:00
path = vim.fn.stdpath("cache") .. "/lazy/cache",
2022-12-14 20:59:50 +00:00
-- 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
2022-12-21 14:19:58 +00:00
---@type string[]
paths = {}, -- add any custom paths here that you want to indluce in the rtp
2022-12-14 20:55:03 +00:00
---@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-19 18:10:49 +00:00
If you dont 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 = "",
source = "",
start = "",
task = "",
},
},
}
<
2022-12-14 20:58:18 +00:00
USAGE *lazy.nvim-usage*
2022-12-19 20:06:18 +00:00
Plugins are managed with the `:Lazy` command. Open the help with `<?>` to see
all the key mappings.
You can press `<CR>` on a plugin to show its details. Most properties can be
2022-12-20 09:56:46 +00:00
hovered with `<K>` to open links, help files, readmes, git commits and git
issues.
2022-12-19 20:06:18 +00:00
2022-12-20 18:44:49 +00:00
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:
2022-12-18 10:44:05 +00:00
2022-12-21 21:28:58 +00:00
│ Command │ Lua │ Description │
│: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 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 │
│:Lazy log [plugins] │require("lazy").log(opts?) │Show recent updates for all plugins │
│:Lazy profile │require("lazy").profile() │Show detailed profiling │
│:Lazy restore [plugins] │require("lazy").restore(opts?) │Updates all plugins to the state in the lockfile │
│:Lazy sync [plugins] │require("lazy").sync(opts?) │Run install, clean and update │
│:Lazy update [plugins] │require("lazy").update(opts?) │Update all 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:
>lua
$ 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
2022-12-18 10:44:05 +00:00
2022-12-20 10:40:52 +00:00
If you want to display the number of plugins on your dashboard, you can use
this simple API:
>lua
local plugins = require("lazy").stats().count
<
**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 <a href="https://github.com/nvim-lualine/lualine.nvim">lualine.nvim</a>
>lua
require("lualine").setup({
sections = {
lualine_x = {
{
require("lazy.status").updates,
cond = require("lazy.status").has_updates,
color = { fg = "ff9e64" },
},
},
},
})
<
2022-12-18 13:34:41 +00:00
LOCKFILE `LAZY-LOCK.JSON` *lazy.nvim-lockfile-`lazy-lock.json`*
After every **update**, the local lockfile 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.
2022-12-23 06:51:44 +00:00
If you are on another machine, you can do `:Lazy restore`, to update all your
plugins to the version from the lockfile.
2022-12-18 13:34:41 +00:00
2022-12-20 09:56:46 +00:00
PERFORMANCE *lazy.nvim-performance*
2022-12-14 20:07:51 +00:00
2022-12-20 09:56:46 +00:00
Great care has been taken to make the startup code (`lazy.core`) as efficient
2022-12-23 06:51:44 +00:00
as possible. During startup, all Lua files used before `VimEnter` or
2022-12-20 09:56:46 +00:00
`BufReadPre` are byte-compiled and cached, similar to what impatient.nvim
<https://github.com/lewis6991/impatient.nvim> does.
2022-12-20 10:40:52 +00:00
My config for example loads in about `11ms` with `93` plugins. I do a lot of
lazy-loading though :)
2022-12-20 09:56:46 +00:00
**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.
2022-12-14 20:11:48 +00:00
2022-12-14 20:07:51 +00:00
<div class="figure">
2022-12-18 13:48:03 +00:00
<img src="https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png" title="fig:"/>
2022-12-14 20:07:51 +00:00
<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 whats in the module
cache
2022-12-14 20:09:17 +00:00
<div class="figure">
2022-12-18 13:48:03 +00:00
<img src="https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png" title="fig:"/>
2022-12-14 20:09:17 +00:00
<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:
2022-12-22 17:48:24 +00:00
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 you rtp are sourced (excluding `/after`)
4. all `/after/plugin` files are sourced (this inludes `/after` from plugins)
2022-12-18 10:44:05 +00:00
Files from runtime directories are always sourced in alphabetical order.
2022-12-16 14:11:06 +00:00
2022-12-19 20:06:18 +00:00
STRUCTURING YOUR PLUGINS *lazy.nvim-structuring-your-plugins*
Some users may want to split their plugin specs in multiple files. Instead of
2022-12-23 06:51:44 +00:00
passing a spec table to `setup()`, you can use a Lua module. The specs from the
2022-12-19 20:06:18 +00:00
**module** and any **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 theyre updated, so the `:Lazy` UI is always up to date
Example:
- `~/.config/nvim/init.lua`
>lua
require("lazy").setup("plugins")
<
2022-12-21 08:04:42 +00:00
- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **_(this file is optional)_**
2022-12-19 20:06:18 +00:00
>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
2022-12-20 10:03:19 +00:00
For a real-life example, you can check my personal dots:
- init.lua <https://github.com/folke/dot/blob/master/config/nvim/init.lua> where I require `config.lazy`
- config.lazy <https://github.com/folke/dot/blob/master/config/nvim/lua/config/lazy.lua> where I bootstrap and setup **lazy.nvim**
- config.plugins <https://github.com/folke/dot/blob/master/config/nvim/lua/config/plugins.lua> is my main plugin config module
- Any submodule of config.plugins (submodules) <https://github.com/folke/dot/tree/master/config/nvim/lua/config/plugins> will be automatically loaded as well.
2022-12-20 09:56:46 +00:00
2022-12-20 09:25:55 +00:00
MIGRATION GUIDE *lazy.nvim-migration-guide*
2022-11-29 14:42:57 +00:00
2022-12-20 09:25:55 +00:00
PACKER.NVIM <HTTPS://GITHUB.COM/WBTHOMASON/PACKER.NVIM> ~
2022-11-29 14:42:57 +00:00
2022-12-20 09:25:55 +00:00
- `setup` `init`
- `requires` `dependencies`
- `as` `name`
- `opt` `lazy`
- `run` `build`
- `lock` `pin`
2022-12-22 20:08:10 +00:00
- `disable=true` `enabled = false`
- `tag=''` `version=""`
2022-12-23 18:04:19 +00:00
- `after` **_not needed_** for most use-cases. Use `dependencies` otherwise.
- `wants` **_not needed_** for most use-cases. Use `dependencies` otherwise.
2022-12-20 09:25:55 +00:00
- `module` is auto-loaded. No need to specify
2022-12-23 11:27:29 +00:00
- `keys` spec is |lazy.nvim-different|
2022-12-20 09:25:55 +00:00
2022-12-23 18:52:21 +00:00
With packer `wants`, `requires` and `after` can be used to manage dependencies.
With most of the lua dependencies this isnt necessary. 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.
2022-12-20 09:25:55 +00:00
PAQ-NVIM <HTTPS://GITHUB.COM/SAVQ/PAQ-NVIM> ~
- `as` `name`
- `opt` `lazy`
- `run` `build`
2022-11-29 14:42:57 +00:00
2022-12-19 13:31:18 +00:00
UNINSTALLING *lazy.nvim-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.
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: