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

docs: updated

This commit is contained in:
Folke Lemaitre 2024-06-23 10:09:41 +02:00
parent ae4d912e16
commit 3d77e4514e
No known key found for this signature in database
GPG Key ID: 41F8B1FBACAE2040
16 changed files with 565 additions and 268 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.markdownlint.yaml Normal file
View File

@ -0,0 +1,14 @@
MD013:
line_length: 120
tables: false
MD033:
allowed_elements:
- "Tabs"
- "TabItem"
- "details"
- "summary"
- "b"
- "table"
- "tr"
- "td"
- "a"

14
docs/configuration/index.md
View File

@ -35,6 +35,20 @@ sidebar_position: 5
-- increase downloads a lot. -- increase downloads a lot.
filter = true, filter = true,
}, },
pkg = {
enabled = true,
cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua",
versions = true, -- Honor versions in pkg sources
sources = {
"lazy",
"rockspec",
"packspec",
},
},
rocks = {
root = vim.fn.stdpath("data") .. "/lazy-rocks",
server = "https://nvim-neorocks.github.io/rocks-binaries/",
},
dev = { dev = {
---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects
path = "~/projects", path = "~/projects",

7
docs/developers.md
View File

@ -3,8 +3,11 @@ sidebar_position: 7
--- ---
# 📚 Plugin Developers # 📚 Plugin Developers
If your plugin needs a build step, you can create a file `build.lua` or `build/init.lua` To make it easier for users to install your plugin, you can include a [package spec](/packages) in your repo.
in the root of your repo. This file will be loaded when the plugin is installed or updated.
If your plugin needs a build step, you can specify this in your **package file**,
or create a file `build.lua` or `build/init.lua` in the root of your repo.
This file will be loaded when the plugin is installed or updated.
This makes it easier for users, as they no longer need to specify a `build` command. This makes it easier for users, as they no longer need to specify a `build` command.

51
docs/installation.md
View File

@ -1,51 +0,0 @@
---
sidebar_position: 2
---
# 🔥 Installation
You can add the following Lua code to your `init.lua` to bootstrap **lazy.nvim**:
<!-- bootstrap:start -->
```lua title="lua/config/lazy.lua"
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
vim.fn.system({
"git",
"clone",
"--filter=blob:none",
"https://github.com/folke/lazy.nvim.git",
"--branch=stable", -- latest stable release
lazypath,
})
end
vim.opt.rtp:prepend(lazypath)
```
<!-- bootstrap:end -->
Next step is to add **lazy.nvim** below the code added in the prior step in `init.lua`:
```lua
require("lazy").setup(plugins, opts)
```
- **plugins**: this should be a `table` or a `string`
- `table`: a list with your [Plugin Spec](#-plugin-spec)
- `string`: a Lua module name that contains your [Plugin Spec](#-plugin-spec). See [Structuring Your Plugins](#-structuring-your-plugins)
- **opts**: see [Configuration](#%EF%B8%8F-configuration) **_(optional)_**
```lua
-- Example using a list of specs with the default options
vim.g.mapleader = " " -- Make sure to set `mapleader` before lazy so your mappings are correct
vim.g.maplocalleader = "\\" -- Same for `maplocalleader`
require("lazy").setup({
"folke/which-key.nvim",
{ "folke/neoconf.nvim", cmd = "Neoconf" },
"folke/neodev.nvim",
})
```
ℹ️ It is recommended to run `:checkhealth lazy` after installation.

169
docs/installation.mdx Normal file
View File

@ -0,0 +1,169 @@
---
sidebar_position: 2
---
# 🛠️ Installation
import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
There are multiple ways to install **lazy.nvim**.
The **Structured Setup** is the recommended way, but you can also use the **Single File Setup**
if you prefer to keep everything in your `init.lua`.
Please refer to the [Configuration](/configuration) section for an overview of all available options.
:::tip
It is recommended to run `:checkhealth lazy` after installation.
:::
:::note
In what follows `~/.config/nvim` is your Neovim configuration directory.
To know the correct path for your system, run `:echo stdpath('config')`.
:::
<Tabs>
<TabItem value="multiple" label="Structured Setup">
```lua title="~/.config/nvim/init.lua"
require("config.lazy")
```
<!-- install_multi:start -->
```lua title="~/.config/nvim/lua/config/lazy.lua"
-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
local lazyrepo = "https://github.com/folke/lazy.nvim.git"
vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
end
vim.opt.rtp:prepend(lazypath)
-- Make sure to setup `mapleader` before loading lazy.nvim
-- This is also a good place to setup other settings (vim.opt)
vim.g.mapleader = " " -- Make sure to set `mapleader` before lazy so your mappings are correct
vim.g.maplocalleader = "\\" -- Same for `maplocalleader`
-- Setup lazy.nvim
require("lazy").setup({
-- highlight-start
spec = {
-- import your plugins
{ import = "plugins" },
},
-- highlight-end
defaults = {
-- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup.
-- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default.
lazy = false,
-- It's recommended to leave version=false for now, since a lot the plugin that support versioning,
-- have outdated releases, which may break your Neovim install.
version = false, -- always use the latest git commit
-- version = "*", -- try installing the latest stable version for plugins that support semver
},
-- colorscheme that will be used when installing plugins.
install = { colorscheme = { "habamax" } },
checker = { enabled = true }, -- automatically check for plugin updates
performance = {
rtp = {
-- uncomment the below to disable some rtp plugins
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
})
```
<!-- install_multi:end -->
You can then create your plugin specs in `lua/plugins`.
Each file should return a table with the plugins you want to install.
For more info see [Structuring Your Plugins](/usage/structuring)
<!-- prettier-ignore-start -->
<pre>
~/.config/nvim
├── lua
│   ├── config
│   │   └── lazy.lua
│   └── plugins
│   ├── spec1.lua
│   ├── **
│   └── spec2.lua
└── init.lua
</pre>
<!-- prettier-ignore-end -->
</TabItem>
<TabItem value="single" label="Single File Setup">
<!-- install_single:start -->
```lua title="~/.config/nvim/init.lua"
-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
local lazyrepo = "https://github.com/folke/lazy.nvim.git"
vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
end
vim.opt.rtp:prepend(lazypath)
-- Make sure to setup `mapleader` before loading lazy.nvim
-- This is also a good place to setup other settings (vim.opt)
vim.g.mapleader = " " -- Make sure to set `mapleader` before lazy so your mappings are correct
vim.g.maplocalleader = "\\" -- Same for `maplocalleader`
-- Setup lazy.nvim
require("lazy").setup({
-- highlight-start
spec = {
-- add your plugins here
},
-- highlight-end
defaults = {
-- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup.
-- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default.
lazy = false,
-- It's recommended to leave version=false for now, since a lot the plugin that support versioning,
-- have outdated releases, which may break your Neovim install.
version = false, -- always use the latest git commit
-- version = "*", -- try installing the latest stable version for plugins that support semver
},
-- colorscheme that will be used when installing plugins.
install = { colorscheme = { "habamax" } },
checker = { enabled = true }, -- automatically check for plugin updates
performance = {
rtp = {
-- uncomment the below to disable some rtp plugins
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
})
```
<!-- install_single:end -->
</TabItem>
</Tabs>

28
docs/packages.md
View File

@ -3,3 +3,31 @@ sidebar_position: 4
--- ---
# 📦 Packages # 📦 Packages
**lazy.nvim** supports three ways for plugins to define their dependencies and configuration.
- **Lazy**: `.lazy.lua` file
- **Rockspec**: [luarocks](https://luarocks.org/) `*-scm-1.rockspec` [file](https://github.com/luarocks/luarocks/wiki/Rockspec-format)
- **Packspec**: `pkg.json` (experimental, since the [format](https://github.com/neovim/packspec/issues/41) is not quite there yet)
:::info
Package specs are always loaded in the scope of the plugin (using [specs](/spec#advanced)),
so that when the plugin is disabled, none of the specs are loaded.
:::
## Lazy
Using a `.lazy.lua` file is the recommended way to define your plugin dependencies and configuration.
Syntax is the same as any plugin spec.
## Rockspec
When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will automatically load its [`rocks`](/spec#setup) dependencies.
## Packspec
Supports the [pkg.json](https://github.com/nvim-lua/nvim-package-specification/issues/41) format,
with a lazy extension in `lazy`.
`lazy` can contain any valid lazy spec fields. They will be added to the plugin's spec.

62
docs/spec/index.md
View File

@ -3,33 +3,69 @@ sidebar_position: 3
--- ---
# 🔌 Plugin Spec # 🔌 Plugin Spec
## Source
| Property | Type | Description | | Property | Type | Description |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| **[1]** | `string?` | Short plugin url. Will be expanded using `config.git.url_format` | | **\[1\]** | `string?` | Short plugin url. Will be expanded using [`config.git.url_format`](../configuration/). Can also be a `url` or `dir`. |
| **dir** | `string?` | A directory pointing to a local plugin | | **dir** | `string?` | A directory pointing to a local plugin |
| **url** | `string?` | A custom git url where the plugin is hosted | | **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 | | **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` | | **dev** | `boolean?` | When `true`, a local plugin directory will be used instead. See [`config.dev`](../configuration/) |
| **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 | A valid spec should define one of `[1]`, `dir` or `url`.
| **cond** | `boolean?` or `fun(LazyPlugin):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. |
## Loading
| Property | Type | Description |
| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. | | **dependencies** | `LazySpec[]` | A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. |
| **enabled** | `boolean?` or `fun():boolean` | When `false`, or if the `function` returns false, then this plugin will not be included in the spec |
| **cond** | `boolean?` or `fun(LazyPlugin):boolean` | Behaves the same as `enabled`, but won't uninstall the plugin when the condition is `false`. Useful to disable some plugins in vscode, or firenvim for example. |
| **priority** | `number?` | Only useful for **start** plugins (`lazy=false`) to force loading certain plugins first. Default priority is `50`. It's recommended to set this to a high number for colorschemes. |
## Setup
| Property | Type | Description |
| ---------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **init** | `fun(LazyPlugin)` | `init` functions are always executed during startup | | **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()` | | **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(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. | | **config** | `fun(LazyPlugin, opts:table)` or `true` | `config` is executed when the plugin loads. The default implementation will automatically run `require(MAIN).setup(opts)` if `opts` or `config = true` is set. Lazy uses several heuristics to determine the plugin's `MAIN` module automatically based on the plugin's **name**. See also `opts`. To use the default implementation without `opts` set `config` to `true`. |
| **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` | | **main** | `string?` | You can specify the `main` module to use for `config()` and `opts()`, in case it can not be determined automatically. See `config()` |
| **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. Before running `build`, a plugin is first loaded. If it's a string it will be run as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands. Some plugins provide their own `build.lua` which is automatically used by lazy. So no need to specify a build step for those plugins. | | **build** | `fun(LazyPlugin)` or `string` or a list of build commands | `build` is executed when a plugin is installed or updated. Before running `build`, a plugin is first loaded. If it's a string it will be run as a shell command. When prefixed with `:` it is a Neovim command. You can also specify a list to executed multiple build commands. Some plugins provide their own `build.lua` which is automatically used by lazy. So no need to specify a build step for those plugins. |
| **rocks** | `string[]?` | Add any [luarocks](https://luarocks.org/) dependencies. |
## Lazy Loading
| Property | Type | Description |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **lazy** | `boolean?` | When `true`, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are `required`, or when one of the lazy-loading handlers triggers |
| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event:string[]):string[]` or `{event:string[]\|string, pattern?: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 `LazyKeysSpec[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[]` | Lazy-load on [key mapping](/spec/lazy_loading#%EF%B8%8F-lazy-key-mappings) |
Refer to the [Lazy Loading](./lazy_loading.md) section for more information.
## Versioning
| Property | Type | Description |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **branch** | `string?` | Branch of the repository | | **branch** | `string?` | Branch of the repository |
| **tag** | `string?` | Tag of the repository | | **tag** | `string?` | Tag of the repository |
| **commit** | `string?` | Commit of the repository | | **commit** | `string?` | Commit of the repository |
| **version** | `string?` or `false` to override the default | Version to use from the repository. Full [Semver](https://devhints.io/semver) ranges are supported | | **version** | `string?` or `false` to override the default | 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 | | **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` | | **submodules** | `boolean?` | When false, git submodules will not be fetched. Defaults to `true` |
| **event** | `string?` or `string[]` or `fun(self:LazyPlugin, event:string[]):string[]` or `{event:string[]\|string, pattern?: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 | Refer to the [Versioning](./versioning.md) section for more information.
| **ft** | `string?` or `string[]` or `fun(self:LazyPlugin, ft:string[]):string[]` | Lazy-load on filetype |
| **keys** | `string?` or `string[]` or `LazyKeysSpec[]` or `fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[]` | Lazy-load on key mapping | ## Advanced
| **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 |
| **optional** | `boolean?` | When a spec is tagged optional, it will only be included in the final spec, when the same plugin has been specified at least once somewhere else without `optional`. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins | | ------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **optional** | `boolean?` | When a spec is tagged optional, it will only be included in the final spec, when the same plugin has been specified at least once somewhere else without `optional`. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. |
| **specs** | `LazySpec` | A list of plugin specs defined in the scope of the plugin. This is mainly useful for Neovim distros, to allow setting options on plugins that may/may not be part of the user's plugins. When the plugin is disabled, none of the scoped specs will be included in the final spec. Similar to `dependencies` without the automatic loading of the specs. |
| **module** | `false?` | Do not automatically load this Lua module when it's required somewhere |
| **import** | `string?` | Import the given spec module. |

20
docs/spec/lazy_loading.md
View File

@ -1,14 +1,16 @@
# Lazy Loading # Lazy Loading
**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to **lazy.nvim** automagically lazy-loads Lua modules. This means that if
specify `module=...` everywhere in your plugin specification. This means that if
you have a plugin `A` that is lazy-loaded and a plugin `B` that requires a 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. module of plugin `A`, then plugin `A` will be loaded on demand as expected.
If you don't want this behavior for a certain plugin, you can specify that with `module=false`. :::tip
You can then manually load the plugin with `:Lazy load foobar.nvim`.
You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`. You can configure **lazy.nvim** to lazy-load all plugins by default with `config.defaults.lazy = true`.
Make sure you've configured lazy-loading, for your plugins to avoid unexpected behavior.
Only do this if you know what you are doing, as it can lead to unexpected behavior.
:::
Additionally, you can also lazy-load on **events**, **commands**, Additionally, you can also lazy-load on **events**, **commands**,
**file types** and **key mappings**. **file types** and **key mappings**.
@ -24,9 +26,13 @@ Plugins will be lazy-loaded when one of the following is `true`:
Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load Colorscheme plugins can be configured with `lazy=true`. The plugin will automagically load
when doing `colorscheme foobar`. when doing `colorscheme foobar`.
> **NOTE:** since **start** plugins can possibly change existing highlight groups, :::warning
> 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 examples)_** since **start** plugins can possibly change existing highlight 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 [examples](./examples.md))_**
:::
## ⌨️ Lazy Key Mappings ## ⌨️ Lazy Key Mappings

109
docs/usage/index.md
View File

@ -3,6 +3,23 @@ sidebar_position: 6
--- ---
# 🚀 Usage # 🚀 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. Plugins are managed with the `:Lazy` command.
Open the help with `<?>` to see all the key mappings. Open the help with `<?>` to see all the key mappings.
@ -18,7 +35,7 @@ Any operation can be started from the UI, with a sub command or an API function:
<!-- commands:start --> <!-- commands:start -->
| Command | Lua | Description | | Command | Lua | Description |
| --- | --- | --- | | ------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `:Lazy build {plugins}` | `require("lazy").build(opts)` | Rebuild a plugin | | `: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 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 clean [plugins]` | `require("lazy").clean(opts?)` | Clean plugins that are no longer needed |
@ -96,7 +113,7 @@ require("lualine").setup({
</details> </details>
### 📆 User Events ## 📆 User Events
The following user events will be triggered: 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. - **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.
## 🐛 Debug
See an overview of active lazy-loading handlers and what's in the module cache.
![image](https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png)
## ▶️ 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 ## ❌ Uninstalling
To uninstall **lazy.nvim**, you need to remove the following files and directories: To uninstall **lazy.nvim**, you need to remove the following files and directories:

4
docs/usage/lockfile.md
View File

@ -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. It is recommended to have this file under version control.
If you use your Neovim config on multiple machines, using the lockfile, you can If you use your Neovim config on multiple machines, using the lockfile, you can

8
docs/usage/profiling.md
View File

@ -1,4 +1,4 @@
# ⚡ Profiling # ⚡ Profiling & Debug
Great care has been taken to make the startup code (`lazy.core`) as efficient as possible. 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, 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. The profiling view shows you why and how long it took to load your plugins.
![image](https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png) ![image](https://user-images.githubusercontent.com/292349/208301766-5c400561-83c3-4811-9667-1ec4bb3c43b8.png)
## 🐛 Debug
See an overview of active lazy-loading handlers and what's in the module cache.
![image](https://user-images.githubusercontent.com/292349/208301790-7eedbfa5-d202-4e70-852e-de68aa47233b.png)

66
docs/usage/structuring.md Normal file
View 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.

37
lua/build.lua
View File

@ -10,12 +10,6 @@ local function dir(path)
end end
M.extract = { M.extract = {
installation = {
bootstrap = {
lang = 'lua title="lua/config/lazy.lua"',
content = Docs.extract(dir("lazy.nvim/lua/lazy/init.lua"), "function M%.bootstrap%(%)\n(.-)\nend"),
},
},
["configuration/index"] = { ["configuration/index"] = {
config = Docs.extract(dir("lazy.nvim/lua/lazy/core/config.lua"), "\nM%.defaults = ({.-\n})") config = Docs.extract(dir("lazy.nvim/lua/lazy/core/config.lua"), "\nM%.defaults = ({.-\n})")
:gsub("%s*debug = false.\n", "\n"), :gsub("%s*debug = false.\n", "\n"),
@ -44,9 +38,40 @@ function M.themes()
exec("cp -r .nvim/plugins/tokyonight.nvim/extras/prism src/themes/prism") exec("cp -r .nvim/plugins/tokyonight.nvim/extras/prism src/themes/prism")
end end
function M.installation()
local install = Util.read_file("lua/tpl/install.lua")
local install_multi = install:gsub(
"spec = {}",
[[spec = {
-- import your plugins
{ import = "plugins" },
}]]
)
local install_single = install:gsub(
"spec = {}",
[[spec = {
-- add your plugins here
}]]
)
return {
install_single = {
content = install_single,
lang = 'lua title="~/.config/nvim/init.lua"',
},
install_multi = {
content = install_multi,
lang = 'lua title="~/.config/nvim/lua/config/lazy.lua"',
},
}
end
function M.docs() function M.docs()
M.extract.installation = M.installation()
for name, data in pairs(M.extract) do for name, data in pairs(M.extract) do
local md = "docs/" .. name .. ".md" local md = "docs/" .. name .. ".md"
if vim.uv.fs_stat(md .. "x") then
md = md .. "x"
end
print("Building " .. md) print("Building " .. md)
Docs.save(data, md) Docs.save(data, md)
end end

46
lua/tpl/install.lua Normal file
View File

@ -0,0 +1,46 @@
-- Bootstrap lazy.nvim
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not (vim.uv or vim.loop).fs_stat(lazypath) then
local lazyrepo = "https://github.com/folke/lazy.nvim.git"
vim.fn.system({ "git", "clone", "--filter=blob:none", "--branch=stable", lazyrepo, lazypath })
end
vim.opt.rtp:prepend(lazypath)
-- Make sure to setup `mapleader` before loading lazy.nvim
-- This is also a good place to setup other settings (vim.opt)
vim.g.mapleader = " " -- Make sure to set `mapleader` before lazy so your mappings are correct
vim.g.maplocalleader = "\\" -- Same for `maplocalleader`
-- Setup lazy.nvim
require("lazy").setup({
-- highlight-start
spec = {},
-- highlight-end
defaults = {
-- By default, only LazyVim plugins will be lazy-loaded. Your custom plugins will load during startup.
-- If you know what you're doing, you can set this to `true` to have all your custom plugins lazy-loaded by default.
lazy = false,
-- It's recommended to leave version=false for now, since a lot the plugin that support versioning,
-- have outdated releases, which may break your Neovim install.
version = false, -- always use the latest git commit
-- version = "*", -- try installing the latest stable version for plugins that support semver
},
-- colorscheme that will be used when installing plugins.
install = { colorscheme = { "habamax" } },
checker = { enabled = true }, -- automatically check for plugin updates
performance = {
rtp = {
-- uncomment the below to disable some rtp plugins
disabled_plugins = {
-- "gzip",
-- "matchit",
-- "matchparen",
-- "netrwPlugin",
-- "tarPlugin",
-- "tohtml",
-- "tutor",
-- "zipPlugin",
},
},
},
})

6
stylua.toml Normal file
View File

@ -0,0 +1,6 @@
indent_type = "Spaces"
indent_width = 2
column_width = 120
[sort_requires]
enabled = true