subcrip
/
lazy.nvim
mirror of https://github.com/folke/lazy.nvim.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore(build): auto-generate vimdoc

This commit is contained in:
github-actions[bot] 2023-02-20 07:31:46 +00:00
parent 43496fa82c
commit 8d5553d11b
1 changed files with 285 additions and 203 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

488
doc/lazy.nvim.txt
View File

@ -1,36 +1,32 @@
*lazy.nvim.txt* For Neovim >= 0.8.0 Last change: 2023 February 17 *lazy.nvim.txt* For Neovim >= 0.8.0 Last change: 2023 February 20
============================================================================== ==============================================================================
Table of Contents *lazy.nvim-table-of-contents* Table of Contents *lazy.nvim-table-of-contents*
1. lazy.nvim |lazy.nvim-lazy.nvim| 1. lazy.nvim |lazy.nvim-lazy.nvim|
- Features |lazy.nvim-features| - Features |lazy.nvim-lazy.nvim-features|
- Requirements |lazy.nvim-requirements| - Requirements |lazy.nvim-lazy.nvim-requirements|
- Installation |lazy.nvim-installation| - Installation |lazy.nvim-lazy.nvim-installation|
- Plugin Spec |lazy.nvim-plugin-spec| - Plugin Spec |lazy.nvim-lazy.nvim-plugin-spec|
- Configuration |lazy.nvim-configuration| - Configuration |lazy.nvim-lazy.nvim-configuration|
- Usage |lazy.nvim-usage| - Usage |lazy.nvim-lazy.nvim-usage|
- Lockfile `lazy-lock.json` |lazy.nvim-lockfile-`lazy-lock.json`| - Lockfile lazy-lock.json |lazy.nvim-lazy.nvim-lockfile-lazy-lock.json|
- Performance |lazy.nvim-performance| - Performance |lazy.nvim-lazy.nvim-performance|
- Debug |lazy.nvim-debug| - Debug |lazy.nvim-lazy.nvim-debug|
- Startup Sequence |lazy.nvim-startup-sequence| - Startup Sequence |lazy.nvim-lazy.nvim-startup-sequence|
- Structuring Your Plugins |lazy.nvim-structuring-your-plugins| - Structuring Your Plugins |lazy.nvim-lazy.nvim-structuring-your-plugins|
- Migration Guide |lazy.nvim-migration-guide| - Migration Guide |lazy.nvim-lazy.nvim-migration-guide|
- Uninstalling |lazy.nvim-uninstalling| - Uninstalling |lazy.nvim-lazy.nvim-uninstalling|
- Highlight Groups |lazy.nvim-highlight-groups| - Highlight Groups |lazy.nvim-lazy.nvim-highlight-groups|
- Other Neovim Plugin Managers in Lua|lazy.nvim-other-neovim-plugin-managers-in-lua| - Other Neovim Plugin Managers in Lua|lazy.nvim-lazy.nvim-other-neovim-plugin-managers-in-lua|
============================================================================== ==============================================================================
1. lazy.nvim *lazy.nvim-lazy.nvim* 1. lazy.nvim *lazy.nvim-lazy.nvim*
**lazy.nvim** is a modern plugin manager for Neovim. **lazy.nvim** is a modern plugin manager for Neovim.
<div class="figure">
<img src="https://user-images.githubusercontent.com/292349/208301737-68fb279c-ba70-43ef-a369-8c3e8367d6b1.png" title="fig:"/>
<p class="caption">image</p>
</div>
FEATURES *lazy.nvim-features* FEATURES *lazy.nvim-lazy.nvim-features*
- Manage all your Neovim plugins with a powerful UI - Manage all your Neovim plugins with a powerful UI
@ -52,15 +48,15 @@ FEATURES *lazy.nvim-features*
- Automatically lazy-loads colorschemes - Automatically lazy-loads colorschemes
REQUIREMENTS *lazy.nvim-requirements* REQUIREMENTS *lazy.nvim-lazy.nvim-requirements*
- Neovim >= **0.8.0** (needs to be built with **LuaJIT**) - Neovim >= **0.8.0** (needs to be built with **LuaJIT**)
- Git >= **2.19.0** (for partial clones support) - Git >= **2.19.0** (for partial clones support)
- a Nerd Font <https://www.nerdfonts.com/> **_(optional)_** - a Nerd Font <https://www.nerdfonts.com/> **(optional)**
INSTALLATION *lazy.nvim-installation* INSTALLATION *lazy.nvim-lazy.nvim-installation*
You can add the following Lua code to your `init.lua` to bootstrap You can add the following Lua code to your `init.lua` to bootstrap
**lazy.nvim** **lazy.nvim**
@ -80,7 +76,6 @@ You can add the following Lua code to your `init.lua` to bootstrap
vim.opt.rtp:prepend(lazypath) vim.opt.rtp:prepend(lazypath)
< <
Next step is to add **lazy.nvim** below the code added in the last step in Next step is to add **lazy.nvim** below the code added in the last step in
`init.lua` `init.lua`
@ -89,12 +84,10 @@ Next step is to add **lazy.nvim** below the code added in the last step in
< <
- **plugins**this should be a `table` or a `string`
- **plugins**: this should be a `table` or a `string` - `table`a list with your |lazy.nvim-plugin-spec|
- `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|
- `string`: a Lua module name that contains your |lazy.nvim-plugin-spec|. See |lazy.nvim-structuring-your-plugins| - **opts**see |lazy.nvim-configuration| **(optional)**
- **opts**: see |lazy.nvim-configuration| **_(optional)_**
>lua >lua
-- example using a list of specs with the default options -- example using a list of specs with the default options
@ -107,38 +100,102 @@ Next step is to add **lazy.nvim** below the code added in the last step in
}) })
< <
It is recommended to run `:checkhealth lazy` after installation It is recommended to run `:checkhealth lazy` after installation
PLUGIN SPEC *lazy.nvim-plugin-spec*
│ Property │ Type │ Description │ PLUGIN SPEC *lazy.nvim-lazy.nvim-plugin-spec*
│[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 included in the spec │
│**cond** │boolean? or fun():boolean │When false, or if the function returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. │
│**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. │
│**init** │fun(LazyPlugin) │init functions are always executed during startup │
│**opts** │table or fun(LazyPlugin, opts:table) │opts should be a table (will be merged with parent 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) or true │config is executed when the plugin loads. The default implementation will automatically run require("plugin").setup(opts). "plugin" will default to name if specified, otherwise lazy.nvim will do its best to guess the correct plugin name. See also opts. To use the default implementation without opts set config to true. │
│**build** │fun(LazyPlugin) or string or a list of build commands │build is executed when a plugin is installed or updated. If it’s a string it will be ran as a shell command. When prefixed with : it is a Neovim command. You can also specify a list to executed multiple build commands │
│**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 │
│submodules │boolean? │When false, git submodules will not be fetched. Defaults to true │
│**event** │string? or string[] or fun(self:LazyPlugin, event:string[]):string[] │Lazy-load on event. Events can be specified as BufEnter or with a pattern like BufEnter .lua │
│**cmd** │string? or string[] or fun(self:LazyPlugin, cmd:string[]):string[] │Lazy-load on command │
│**ft** │string? or string[] or fun(self:LazyPlugin, ft:string[]):string[] │Lazy-load on filetype │
│**keys** │string? or string[] or LazyKeys[] or fun(self:LazyPlugin, keys:string[]):(string \| LazyKeys)[] │Lazy-load on key mapping │
│**module** │false? │Do not automatically load this Lua module when it’s required somewhere │
│**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. │
--------------------------------------------------------------------------------------------------------------------------------
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 included in the spec
cond boolean? or fun():boolean When false, or if the function returns false, then
this plugin will not be loaded. Useful to disable
some plugins in vscode, or firenvim for example.
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.
init fun(LazyPlugin) init functions are always executed during startup
opts table or fun(LazyPlugin, opts:table) opts should be a table (will be merged with parent
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) or true config is executed when the plugin loads. The
default implementation will automatically run
require("plugin").setup(opts). "plugin" will default
to name if specified, otherwise lazy.nvim will do
its best to guess the correct plugin name. See also
opts. To use the default implementation without opts
set config to true.
build fun(LazyPlugin) or string or a list of build commands build is executed when a plugin is installed or
updated. If it’s a string it will be ran as a shell
command. When prefixed with it is a Neovim command.
You can also specify a list to executed multiple
build commands
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
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
event string? or string[] or Lazy-load on event. Events can be specified as
fun(self:LazyPlugin, event:string[]):string[] BufEnter or with a pattern 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 LazyKeys[] or Lazy-load on key mapping
fun(self:LazyPlugin, keys:string[]):(string \| LazyKeys)[]
module false? Do not automatically load this Lua module when it’s
required somewhere
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.
--------------------------------------------------------------------------------------------------------------------------------
LAZY LOADING ~ LAZY LOADING ~
@ -157,45 +214,36 @@ You can configure **lazy.nvim** to lazy-load all plugins by default with
Additionally, you can also lazy-load on **events**, **commands**, **file Additionally, you can also lazy-load on **events**, **commands**, **file
types** and **key mappings**. types** and **key mappings**.
Plugins will be lazy-loaded when one of the following is `true`: Plugins will be lazy-loaded when one of the following is `true`
- the plugin only exists as a dependency in your spec - theplugin only exists as a dependency in your spec
- it has an `event`, `cmd`, `ft` or `keys` key - it has an `event`, `cmd`, `ft` or `keys` key
- `config.defaults.lazy == true` - `config.defaults.lazy == true`
*lazy.nvim-Colorschemes* COLORSCHEMES
Colorschemes Colorscheme plugins can be configured
with `lazy=true`. The plugin will
automagically load when doing
`colorscheme foobar`.
Colorscheme plugins can be configured with `lazy=true`. The plugin will
automagically load when doing `colorscheme foobar`.
**NOTE:** since **start** plugins can possibly change existing highlight **NOTE:** since **start** plugins can possibly change existing highlight
groups, it’s important to make sure that your main **colorscheme** is loaded groups, it’s important to make sure that your main **colorscheme** is loaded
first. To ensure this you can use the `priority=1000` field. **_(see the first. To ensure this you can use the `priority=1000` field. **(see the
examples)_** examples)**
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:
*lazy.nvim-Lazy-Key-Mappings* - **[1]**(`string`) lhs **(required)**
- **[2]**(`string|fun()`) rhs **(optional)**
Lazy Key Mappings The `keys` property can be a `string` or - **mode**(`string|string[]`) mode **(optional, defaults to "n")**
`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` - any other option valid for `vim.keymap.set`
Key mappings will load the plugin the first time they get executed. 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()` When `[2]` is `nil`, then the real mapping has to be created by the `config()`
@ -222,22 +270,22 @@ If you want to install a specific revision of a plugin, you can use `commit`,
The `version` property supports Semver <https://semver.org/> ranges. The `version` property supports Semver <https://semver.org/> ranges.
Click to see some examples Click to see some examples ~
- :latest stable version (this excludes pre-release versions) - 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.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.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 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 `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 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 `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 - `<=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
You can set `config.defaults.version = ""` to install the latest stable version You can set `config.defaults.version = ""` to install the latest stable version
of plugins that support Semver. of plugins that support Semver.
EXAMPLES ~ EXAMPLES ~
>lua >lua
@ -338,7 +386,7 @@ EXAMPLES ~
< <
CONFIGURATION *lazy.nvim-configuration* CONFIGURATION *lazy.nvim-lazy.nvim-configuration*
**lazy.nvim** comes with the following defaults: **lazy.nvim** comes with the following defaults:
@ -486,8 +534,7 @@ CONFIGURATION *lazy.nvim-configuration*
} }
< <
If you don’t want to use a Nerd Font, you can replace the icons with Unicode symbols. ~
If you don’t want to use a Nerd Font, you can replace the icons with Unicode symbols.
>lua >lua
{ {
@ -511,7 +558,7 @@ If you don’t want to use a Nerd Font, you can replace the icons with Unicode s
< <
USAGE *lazy.nvim-usage* USAGE *lazy.nvim-lazy.nvim-usage*
Plugins are managed with the `:Lazy` command. Open the help with `<?>` to see Plugins are managed with the `:Lazy` command. Open the help with `<?>` to see
all the key mappings. all the key mappings.
@ -526,24 +573,43 @@ enabled with `config.checker.enabled = true`.
Any operation can be started from the UI, with a sub command or an API Any operation can be started from the UI, with a sub command or an API
function: function:
│ Command │ Lua │ Description │ --------------------------------------------------------------------------------------------------------------
│:Lazy build {plugins} │require("lazy").build(opts) │Rebuild a plugin │ 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 build {plugins} require("lazy").build(opts) Rebuild a plugin
│: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 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 │
: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 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 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: example, if you want to sync lazy from the cmdline, you can use:
@ -551,15 +617,13 @@ example, if you want to sync lazy from the cmdline, you can use:
$ nvim --headless "+Lazy! sync" +qa $ nvim --headless "+Lazy! sync" +qa
< <
`opts` is a table with the following key-values: `opts` is a table with the following key-values:
- **wait**: when true, then the call will wait till the operation completed - **wait**when true, then the call will wait till the operation completed
- **show**: when false, the UI will not be shown - **show**when false, the UI will not be shown
- **plugins**: a list of plugin names to run the operation on - **plugins**a list of plugin names to run the operation on
- **concurrency**: limit the `number` of concurrently running tasks - **concurrency**limit the `number` of concurrently running tasks
Stats API (`require("lazy").stats()`): Stats API (`require("lazy").stats()`):
@ -578,12 +642,11 @@ Stats API (`require("lazy").stats()`):
} }
< <
**lazy.nvim** provides a statusline component that you can use to show the **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` number of pending updates. Make sure to enable `config.checker.enabled = true`
to make this work. to make this work.
Example of configuring <a href="https://github.com/nvim-lualine/lualine.nvim">lualine.nvim</a> Example of configuring lualine.nvim ~
>lua >lua
require("lualine").setup({ require("lualine").setup({
@ -605,20 +668,20 @@ USER EVENTS ~
The following user events will be triggered: The following user events will be triggered:
- **LazyDone**: when lazy has finished starting up and loaded your config - **LazyDone**when lazy has finished starting up and loaded your config
- **LazySync**: after running sync - **LazySync**after running sync
- **LazyInstall**: after an install - **LazyInstall**after an install
- **LazyUpdate**: after an update - **LazyUpdate**after an update
- **LazyClean**: after a clean - **LazyClean**after a clean
- **LazyCheck**: after checking for updates - **LazyCheck**after checking for updates
- **LazyLog**: after running log - **LazyLog**after running log
- **LazyReload**: triggered by change detection after reloading plugin specs - **LazyReload**triggered by change detection after reloading plugin specs
- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands - **VeryLazy**triggered after `LazyDone` and processing `VimEnter` auto commands
- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. - **LazyVimStarted**triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated.
Useful to update the startuptime on your dashboard. Useful to update the startuptime on your dashboard.
LOCKFILE `LAZY-LOCK.JSON` *lazy.nvim-lockfile-`lazy-lock.json`* LOCKFILE LAZY-LOCK.JSON *lazy.nvim-lazy.nvim-lockfile-lazy-lock.json*
After every **update**, the local lockfile is updated with the installed After every **update**, the local lockfile is updated with the installed
revisions. It is recommended to have this file under version control. revisions. It is recommended to have this file under version control.
@ -629,7 +692,8 @@ 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 If you are on another machine, you can do `:Lazy restore`, to update all your
plugins to the version from the lockfile. plugins to the version from the lockfile.
PERFORMANCE *lazy.nvim-performance*
PERFORMANCE *lazy.nvim-lazy.nvim-performance*
Great care has been taken to make the startup code (`lazy.core`) as efficient 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 as possible. During startup, all Lua files used before `VimEnter` or
@ -643,22 +707,14 @@ lazy-loading though :)
improve performance. The profiling view shows you why and how long it took to improve performance. The profiling view shows you why and how long it took to
load your plugins. load your plugins.
<div class="figure">
<img src="https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png" title="fig:"/>
<p class="caption">image</p>
</div>
DEBUG *lazy.nvim-debug* DEBUG *lazy.nvim-lazy.nvim-debug*
See an overview of active lazy-loading handlers and what’s in the module See an overview of active lazy-loading handlers and what’s in the module
cache cache
<div class="figure">
<img src="https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png" title="fig:"/>
<p class="caption">image</p>
</div>
STARTUP SEQUENCE *lazy.nvim-startup-sequence* STARTUP SEQUENCE *lazy.nvim-lazy.nvim-startup-sequence*
**lazy.nvim** does **NOT** use Neovim packages and even disables plugin loading **lazy.nvim** does **NOT** use Neovim packages and even disables plugin loading
completely (`vim.go.loadplugins = false`). It takes over the complete startup completely (`vim.go.loadplugins = false`). It takes over the complete startup
@ -667,15 +723,12 @@ sequence for more flexibility and better performance.
In practice this means that step 10 of |Neovim Initialization| is done by Lazy: In practice this means that step 10 of |Neovim Initialization| is done by Lazy:
1. all the plugins’ `init()` functions are executed 1. all the plugins’ `init()` functions are executed2. 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 includes `/after` from plugins)
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 includes `/after` from plugins)
Files from runtime directories are always sourced in alphabetical order. Files from runtime directories are always sourced in alphabetical order.
STRUCTURING YOUR PLUGINS *lazy.nvim-structuring-your-plugins*
STRUCTURING YOUR PLUGINS *lazy.nvim-lazy.nvim-structuring-your-plugins*
Some users may want to split their plugin specs in multiple files. Instead of 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 passing a spec table to `setup()`, you can use a Lua module. The specs from the
@ -690,21 +743,17 @@ The benefits of using this approach:
- allows for **caching** of all your plugin specs. This becomes important if you have a lot of smaller plugin specs. - 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 - spec changes will automatically be **reloaded** when they’re updated, so the `:Lazy` UI is always up to date
Example: Example:
- `~/.config/nvim/init.lua` - `~/.config/nvim/init.lua`
>lua >lua
require("lazy").setup("plugins") require("lazy").setup("plugins")
< <
- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **(this file is optional)**
- `~/.config/nvim/lua/plugins.lua` or `~/.config/nvim/lua/plugins/init.lua` **_(this file is optional)_**
>lua >lua
return { return {
@ -715,10 +764,8 @@ Example:
< <
- any lua file in `~/.config/nvim/lua/plugins/.lua` will be automatically merged in the main plugin spec - 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 For a real-life example, you can check LazyVim
<https://github.com/LazyVim/LazyVim> and more specifically: <https://github.com/LazyVim/LazyVim> and more specifically:
@ -726,7 +773,7 @@ For a real-life example, you can check LazyVim
- lazyvim.plugins <https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins> contains all the plugin specs that will be loaded - lazyvim.plugins <https://github.com/LazyVim/LazyVim/tree/main/lua/lazyvim/plugins> contains all the plugin specs that will be loaded
IMPORTING SPECS, `CONFIG` & `OPTS` ~ IMPORTING SPECS, CONFIG & OPTS ~
As part of a spec, you can add `import` statements to import additional plugin As part of a spec, you can add `import` statements to import additional plugin
modules. Both of the `setup()` calls are equivalent: modules. Both of the `setup()` calls are equivalent:
@ -738,7 +785,6 @@ modules. Both of the `setup()` calls are equivalent:
require("lazy").setup({{import = "plugins"}}) require("lazy").setup({{import = "plugins"}})
< <
When you import specs, you can override them by simply adding a spec for the 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. same plugin to your local specs, adding any keys you want to override / merge.
@ -746,9 +792,11 @@ same plugin to your local specs, adding any keys you want to override / merge.
the parent spec. Any other property will override the property from the parent the parent spec. Any other property will override the property from the parent
spec. spec.
MIGRATION GUIDE *lazy.nvim-migration-guide*
PACKER.NVIM <HTTPS://GITHUB.COM/WBTHOMASON/PACKER.NVIM> ~ MIGRATION GUIDE *lazy.nvim-lazy.nvim-migration-guide*
PACKER.NVIM ~
- `setup` `init` - `setup` `init`
@ -759,21 +807,19 @@ PACKER.NVIM <HTTPS://GITHUB.COM/WBTHOMASON/PACKER.NVIM> ~
- `lock` `pin` - `lock` `pin`
- `disable=true` `enabled = false` - `disable=true` `enabled = false`
- `tag=''` `version=""` - `tag=''` `version=""`
- `after` **_not needed_** for most use-cases. Use `dependencies` otherwise. - `after` **not needed** for most use-cases. Use `dependencies` otherwise.
- `wants` **_not needed_** for most use-cases. Use `dependencies` otherwise. - `wants` **not needed** for most use-cases. Use `dependencies` otherwise.
- `config` don’t support string type, use `fun(LazyPlugin)` instead. - `config` don’t support string type, use `fun(LazyPlugin)` instead.
- `module` is auto-loaded. No need to specify - `module` is auto-loaded. No need to specify
- `keys` spec is |lazy.nvim-different| - `keys` spec is |lazy.nvim-different|
- `rtp` can be accomplished with: - `rtp` can be accomplished with:
>lua >lua
config = function(plugin) config = function(plugin)
vim.opt.rtp:append(plugin.dir .. "/custom-rtp") vim.opt.rtp:append(plugin.dir .. "/custom-rtp")
end end
< <
With packer `wants`, `requires` and `after` can be used to manage dependencies. 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 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 installed just like normal plugins (even with `lazy=true`) and will be loaded
@ -782,7 +828,8 @@ 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 as `dependencies` will always be lazy-loaded and loaded when the plugin is
loaded. loaded.
PAQ-NVIM <HTTPS://GITHUB.COM/SAVQ/PAQ-NVIM> ~
PAQ-NVIM ~
- `as` `name` - `as` `name`
@ -790,58 +837,87 @@ PAQ-NVIM <HTTPS://GITHUB.COM/SAVQ/PAQ-NVIM> ~
- `run` `build` - `run` `build`
UNINSTALLING *lazy.nvim-uninstalling* UNINSTALLING *lazy.nvim-lazy.nvim-uninstalling*
To uninstall **lazy.nvim**, you need to remove the following files and To uninstall **lazy.nvim**, you need to remove the following files and
directories: directories:
- **data**: `~/.local/share/nvim/lazy` - **data**`~/.local/share/nvim/lazy`
- **state**: `~/.local/state/nvim/lazy` - **state**`~/.local/state/nvim/lazy`
- **lockfile**: `~/.config/nvim/lazy-lock.json` - **lockfile**`~/.config/nvim/lazy-lock.json`
paths can differ if you changed `XDG` environment variables. paths can differ if you changed `XDG` environment variables.
HIGHLIGHT GROUPS *lazy.nvim-lazy.nvim-highlight-groups*
HIGHLIGHT GROUPS *lazy.nvim-highlight-groups* Click to see all highlight groups ~
Click to see all highlight groups ---------------------------------------------------------------------------------
Highlight Group Default Group Description
------------------- ------------------------ ------------------------------------
LazyButton CursorLine
│ Highlight Group │ Default Group │ Description │ LazyButtonActive Visual
│**LazyButton** │**_CursorLine_** │ │
│**LazyButtonActive** │**_Visual_** │ │
│**LazyComment** │**_Comment_** │ │
│**LazyCommit** │_variable.builtin │commitref │
│**LazyCommitIssue** │**_Number_** │ │
│**LazyCommitScope** │**_Italic_** │conventional commit scope │
│**LazyCommitType** │**_Title_** │conventional commit type │
│**LazyDir** │_text.reference │directory │
│**LazyH1** │**_IncSearch_** │homebutton │
│**LazyH2** │**_Bold_** │titles │
│**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_** │ │
│**LazyReasonRuntime**│_macro │ │
│**LazyReasonSource** │**_Character_** │ │
│**LazyReasonStart** │_field │ │
│**LazySpecial** │_punctuation.special│ │
│**LazyTaskError** │**_ErrorMsg_** │taskerrors │
│**LazyTaskOutput** │**_MsgArea_** │task output │
│**LazyUrl** │_text.reference │url │
│**LazyValue** │_string │valueof a property │
LazyComment Comment
OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-other-neovim-plugin-managers-in-lua* LazyCommit _@variable.builtin_ commitref
LazyCommitIssue Number
LazyCommitScope Italic conventional commit scope
LazyCommitType Title conventional commit type
LazyDir _@text.reference_ directory
LazyH1 IncSearch homebutton
LazyH2 Bold titles
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
LazyReasonRuntime _@macro_
LazyReasonSource Character
LazyReasonStart _@field_
LazySpecial _@punctuation.special_
LazyTaskError ErrorMsg taskerrors
LazyTaskOutput MsgArea task output
LazyUrl _@text.reference_ url
LazyValue _@string_ valueof a property
---------------------------------------------------------------------------------
OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-lazy.nvim-other-neovim-plugin-managers-in-lua*
- packer.nvim <https://github.com/wbthomason/packer.nvim> - packer.nvim <https://github.com/wbthomason/packer.nvim>
@ -851,6 +927,12 @@ OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-other-neovim-plugin-managers-in-lu
- optpack.nvim <https://github.com/notomo/optpack.nvim> - optpack.nvim <https://github.com/notomo/optpack.nvim>
- pact.nvim <https://github.com/rktjmp/pact.nvim> - pact.nvim <https://github.com/rktjmp/pact.nvim>
==============================================================================
2. Links *lazy.nvim-links*
1. *image*: https://user-images.githubusercontent.com/292349/208301737-68fb279c-ba70-43ef-a369-8c3e8367d6b1.png
2. *image*: https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png
3. *image*: https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc> Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>