mirror of
https://github.com/folke/lazy.nvim.git
synced 2025-04-19 21:06:46 +00:00
docs: updated
This commit is contained in:
Folke Lemaitre
parent
ae4d912e16
commit
3d77e4514e
16 changed files with 565 additions and 268 deletions
|
|
@ -3,6 +3,23 @@ sidebar_position: 6
|
|||
---
|
||||
# 🚀 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](https://neovim.io/doc/user/starting.html#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
|
||||
|
||||
Plugins are managed with the `:Lazy` command.
|
||||
Open the help with `<?>` to see all the key mappings.
|
||||
|
||||
|
|
@ -17,24 +34,24 @@ Any operation can be started from the UI, with a sub command or an API function:
|
|||
|
||||
<!-- commands:start -->
|
||||
|
||||
| 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!!) |
|
||||
| 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 |
|
||||
| `: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 |
|
||||
|
||||
<!-- commands:end -->
|
||||
|
||||
|
|
@ -96,7 +113,7 @@ require("lualine").setup({
|
|||
|
||||
</details>
|
||||
|
||||
### 📆 User Events
|
||||
## 📆 User Events
|
||||
|
||||
The following user events will be triggered:
|
||||
|
||||
|
|
@ -119,94 +136,6 @@ The following user events will be triggered:
|
|||
- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated.
|
||||
Useful to update the startuptime on your dashboard.
|
||||
|
||||
## 🐛 Debug
|
||||
|
||||
See an overview of active lazy-loading handlers and what's in the module cache.
|
||||
|
||||
|
||||
|
||||
## ▶️ 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](https://neovim.io/doc/user/starting.html#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.
|
||||
|
||||
## 📂 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](https://github.com/LazyVim/LazyVim) and more specifically:
|
||||
|
||||
- [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`
|
||||
|
||||
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.
|
||||
|
||||
## ❌ Uninstalling
|
||||
|
||||
To uninstall **lazy.nvim**, you need to remove the following files and directories:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 🔒 Lockfile `lazy-lock.json`
|
||||
# 🔒 Lockfile
|
||||
|
||||
After every **update**, the local lockfile is updated with the installed revisions.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
# ⚡ Profiling
|
||||
# ⚡ 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,
|
||||
|
|
@ -10,3 +10,9 @@ My config for example loads in about `11ms` with `93` plugins. I do a lot of laz
|
|||
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.
|
||||
|
||||
|
||||
|
|
|
|||
66
docs/usage/structuring.md
Normal file
66
docs/usage/structuring.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# 📂 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](https://github.com/LazyVim/LazyVim) and more specifically:
|
||||
|
||||
- [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`
|
||||
|
||||
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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue