From 183f59e2e85dea0c38ed7d16c7c7e543c0b739c7 Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Sun, 23 Jun 2024 21:07:44 +0200 Subject: [PATCH] feat!: new docs for v11.0 --- .github/workflows/ci.yml | 21 - README.md | 845 ++--------------------------- doc/.keep | 0 doc/lazy.nvim.txt | 1101 ++++++++++++++++++++++---------------- lua/lazy/core/config.lua | 7 +- 5 files changed, 674 insertions(+), 1300 deletions(-) create mode 100644 doc/.keep diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c7d3156..05b9111 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -26,31 +26,10 @@ jobs: nvim --version [ ! -d tests ] && exit 0 nvim --headless -u tests/init.lua -c "PlenaryBustedDirectory tests/ {minimal_init = 'tests/init.lua', sequential = true}" - docs: - runs-on: ubuntu-latest - needs: tests - if: ${{ github.ref == 'refs/heads/main' }} - steps: - - uses: actions/checkout@v4 - - name: panvimdoc - uses: kdheepak/panvimdoc@main - with: - vimdoc: lazy.nvim - version: "Neovim >= 0.8.0" - demojify: true - treesitter: true - - name: Push changes - uses: stefanzweifel/git-auto-commit-action@v5 - with: - commit_message: "chore(build): auto-generate vimdoc" - commit_user_name: "github-actions[bot]" - commit_user_email: "github-actions[bot]@users.noreply.github.com" - commit_author: "github-actions[bot] " release: name: release if: ${{ github.ref == 'refs/heads/main' }} needs: - - docs - tests runs-on: ubuntu-latest steps: diff --git a/README.md b/README.md index 9bde4f9..a950b94 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,36 @@ -# πŸ’€ lazy.nvim +

+ Install + Β· + Configure + Β· + Docs +

+ +

+ + Latest release + + + Last commit + + + License + + + Stars + + + Issues + + + Repo Size + + + follow on Twitter + +

+ + **lazy.nvim** is a modern plugin manager for Neovim. @@ -30,813 +62,6 @@ - Git >= **2.19.0** (for partial clones support) - a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** -## πŸ“¦ Installation +## πŸš€ Getting Started -You can add the following Lua code to your `init.lua` to bootstrap **lazy.nvim**: - - - -```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) -``` - - - -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. - -## πŸ”Œ Plugin Spec - -| 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(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. | -| **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(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()` | -| **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. | -| **branch** | `string?` | Branch of the repository | -| **tag** | `string?` | Tag 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 | -| **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[]` 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 | -| **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. | -| **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 | - -### Lazy Loading - -**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to -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 -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`. -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`. - -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 -- It has an `event`, `cmd`, `ft` or `keys` key -- `config.defaults.lazy == true` - -#### 🌈 Colorschemes - -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 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)_** - -#### ⌨️ Lazy Key Mappings - -The `keys` property can be a `string` or `string[]` for simple normal-mode mappings, or it -can be a `LazyKeysSpec` table with the following key-value pairs: - -- **[1]**: (`string`) lhs **_(required)_** -- **[2]**: (`string|fun()`) rhs **_(optional)_** -- **mode**: (`string|string[]`) mode **_(optional, defaults to `"n"`)_** -- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **_(optional)_** -- 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 = { - { "ft", "Neotree toggle", desc = "NeoTree" }, - }, - config = function() - require("neo-tree").setup() - end, -} -``` - -### Versioning - -If you want to install a specific revision of a plugin, you can use `commit`, -`tag`, `branch`, `version`. - -The `version` property supports [Semver](https://semver.org/) ranges. - -
-Click to see some examples - -- `*`: 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 - -
- -You can set `config.defaults.version = "*"` to install the latest stable -version of plugins that support Semver. - -### Examples - - - -```lua -return { - -- the colorscheme should be available when starting Neovim - { - "folke/tokyonight.nvim", - lazy = false, -- make sure we load this during startup if it is your main colorscheme - priority = 1000, -- make sure to load this before all the other start plugins - config = function() - -- load the colorscheme here - vim.cmd([[colorscheme tokyonight]]) - end, - }, - - -- 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", - -- options for neorg. This will automatically call `require("neorg").setup(opts)` - opts = { - load = { - ["core.defaults"] = {}, - }, - }, - }, - - { - "dstein64/vim-startuptime", - -- lazy-load on a command - cmd = "StartupTime", - -- init is called during startup. Configuration for vim plugins typically should be set in an init function - init = function() - vim.g.startuptime_tries = 10 - end, - }, - - { - "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, - }, - - -- if some code requires a module from an unloaded plugin, it will be automatically loaded. - -- So for api plugins like devicons, we can always set lazy=true - { "nvim-tree/nvim-web-devicons", lazy = true }, - - -- you can use the VeryLazy event for things that can - -- load later and are not important for the initial UI - { "stevearc/dressing.nvim", event = "VeryLazy" }, - - { - "Wansmer/treesj", - keys = { - { "J", "TSJToggle", desc = "Join Toggle" }, - }, - opts = { use_default_keymaps = false, max_join_length = 150 }, - }, - - { - "monaqa/dial.nvim", - -- lazy-load on keys - -- mode is `n` by default. For more advanced options, check the section on key mappings - keys = { "", { "", mode = "n" } }, - }, - - -- local plugins need to be explicitly configured with dir - { dir = "~/projects/secret.nvim" }, - - -- you can use a custom url to fetch a plugin - { url = "git@github.com:folke/noice.nvim.git" }, - - -- local plugins can also be configured with the dev option. - -- This will use {config.dev.path}/noice.nvim/ instead of fetching it from GitHub - -- With the dev option, you can easily switch between the local and installed version of a plugin - { "folke/noice.nvim", dev = true }, -} -``` - - - -## βš™οΈ Configuration - -**lazy.nvim** comes with the following defaults: - - - -```lua -{ - root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed - defaults = { - lazy = false, -- should plugins be lazy-loaded? - version = nil, - -- default `cond` you can use to globally disable a lot of plugins - -- when running inside vscode for example - cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil - -- version = "*", -- enable this to try installing the latest stable versions of plugins - }, - -- leave nil when passing the spec as the first argument to setup() - spec = nil, ---@type LazySpec - local_spec = true, -- load project specific .lazy.lua spec files. They will be added at the end of the spec. - lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update. - ---@type number? limit the maximum amount of concurrent tasks - concurrency = jit.os:find("Windows") and (vim.uv.available_parallelism() * 2) or nil, - git = { - -- defaults for the `Lazy log` command - -- log = { "--since=3 days ago" }, -- show commits from the last 3 days - log = { "-8" }, -- show the last 8 commits - timeout = 120, -- kill processes that take more than 2 minutes - url_format = "https://github.com/%s.git", - -- lazy.nvim requires git >=2.19.0. If you really want to use lazy with an older version, - -- then set the below to false. This should work, but is NOT supported and will - -- increase downloads a lot. - filter = true, - }, - dev = { - ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects - path = "~/projects", - ---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub - patterns = {}, -- For example {"folke"} - fallback = false, -- Fallback to git when local plugin doesn't exist - }, - 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 = { - -- a number <1 is a percentage., >1 is a fixed size - size = { width = 0.8, height = 0.8 }, - wrap = true, -- wrap the lines in the ui - -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. - border = "none", - -- The backdrop opacity. 0 is fully opaque, 100 is fully transparent. - backdrop = 60, - title = nil, ---@type string only works when border is not "none" - title_pos = "center", ---@type "center" | "left" | "right" - -- Show pills on top of the Lazy window - pills = true, ---@type boolean - icons = { - cmd = "ξ―‡ ", - config = "", - event = "ξͺ† ", - ft = "ο€– ", - init = " ", - import = " ", - keys = "ο„œ ", - lazy = "σ°’² ", - loaded = "●", - not_loaded = "β—‹", - plugin = "ο’‡ ", - runtime = "ξŸ… ", - require = "σ°’± ", - source = "ο„‘ ", - start = "ξ«“ ", - task = "βœ” ", - list = { - "●", - "➜", - "β˜…", - "β€’", - }, - }, - -- leave nil, to automatically select a browser depending on your OS. - -- If you want to use a specific browser, you can define it here - browser = nil, ---@type string? - throttle = 20, -- how frequently should the ui process render events - custom_keys = { - -- You can define custom key maps here. If present, the description will - -- be shown in the help menu. - -- To disable one of the defaults, set it to false. - - ["l"] = { - function(plugin) - require("lazy.util").float_term({ "lazygit", "log" }, { - cwd = plugin.dir, - }) - end, - desc = "Open lazygit log", - }, - - ["t"] = { - function(plugin) - require("lazy.util").float_term(nil, { - cwd = plugin.dir, - }) - end, - desc = "Open terminal in plugin dir", - }, - }, - }, - diff = { - -- diff command can be one of: - -- * browser: opens the github compare view. Note that this is always mapped to as well, - -- so you can have a different command for diff - -- * git: will run git diff and open a buffer with filetype git - -- * terminal_git: will open a pseudo terminal with git diff - -- * diffview.nvim: will open Diffview to show the diff - cmd = "git", - }, - checker = { - -- automatically check for plugin updates - enabled = false, - concurrency = nil, ---@type number? set to 1 to check for updates very slowly - notify = true, -- get a notification when new updates are found - frequency = 3600, -- check for updates every hour - check_pinned = false, -- check for pinned packages that can't be updated - }, - change_detection = { - -- automatically check for config file changes and reload the ui - enabled = true, - notify = true, -- get a notification when changes are found - }, - performance = { - cache = { - enabled = true, - }, - reset_packpath = true, -- reset the package path to improve startup time - rtp = { - reset = true, -- reset the runtime path to $VIMRUNTIME and your config directory - ---@type string[] - paths = {}, -- add any custom paths here that you want to includes in the rtp - ---@type string[] list any plugins you want to disable here - disabled_plugins = { - -- "gzip", - -- "matchit", - -- "matchparen", - -- "netrwPlugin", - -- "tarPlugin", - -- "tohtml", - -- "tutor", - -- "zipPlugin", - }, - }, - }, - -- 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 = { - enabled = true, - root = vim.fn.stdpath("state") .. "/lazy/readme", - files = { "README.md", "lua/**/README.md" }, - -- only generate markdown helptags for plugins that dont have docs - skip_if_doc_exists = true, - }, - state = vim.fn.stdpath("state") .. "/lazy/state.json", -- state info for checker and other things - build = { - -- Plugins can provide a `build.lua` file that will be executed when the plugin is installed - -- or updated. When the plugin spec also has a `build` command, the plugin's `build.lua` not be - -- executed. In this case, a warning message will be shown. - warn_on_override = true, - }, - -- Enable profiling of lazy.nvim. This will add some overhead, - -- so only enable this when you are debugging lazy.nvim - profiling = { - -- Enables extra stats on the debug tab related to the loader cache. - -- Additionally gathers stats about all package.loaders - loader = false, - -- Track each new require in the Lazy profiling tab - require = false, - }, -} -``` - - - -
-If you don't 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 = "πŸ’»", - require = "πŸŒ™", - source = "πŸ“„", - start = "πŸš€", - task = "πŸ“Œ", - lazy = "πŸ’€ ", - }, - }, -} -``` - -
- -## πŸš€ Usage - -Plugins are managed with the `:Lazy` command. -Open the help with `` to see all the key mappings. - -You can press `` on a plugin to show its details. Most properties -can be hovered with `` to open links, help files, readmes, -git commits and git issues. - -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: - - - -| 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 | - - - -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: - -```shell -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 - -Stats API (`require("lazy").stats()`): - - - -```lua -{ - -- startuptime in milliseconds till UIEnter - startuptime = 0, - -- when true, startuptime is the accurate cputime for the Neovim process. (Linux & macOS) - -- this is more accurate than `nvim --startuptime`, and as such will be slightly higher - -- when false, startuptime is calculated based on a delta with a timestamp when lazy started. - real_cputime = false, - count = 0, -- total number of plugins - loaded = 0, -- number of loaded plugins - ---@type table - times = {}, -} -``` - - - -**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 lualine.nvim - -```lua -require("lualine").setup({ - sections = { - lualine_x = { - { - require("lazy.status").updates, - cond = require("lazy.status").has_updates, - color = { fg = "#ff9e64" }, - }, - }, - }, -}) - -``` - -
- -### πŸ“† User Events - -The following user events will be triggered: - -- **LazyDone**: when lazy has finished starting up and loaded your config -- **LazySync**: after running sync -- **LazyInstall**: after an install -- **LazyUpdate**: after an update -- **LazyClean**: after a clean -- **LazyCheck**: after checking for updates -- **LazyLog**: after running log -- **LazyLoad**: after loading a plugin. The `data` attribute will contain the plugin name. -- **LazySyncPre**: before running sync -- **LazyInstallPre**: before an install -- **LazyUpdatePre**: before an update -- **LazyCleanPre**: before a clean -- **LazyCheckPre**: before checking for updates -- **LazyLogPre**: before running log -- **LazyReload**: triggered by change detection after reloading plugin specs -- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands -- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. - Useful to update the startuptime on your dashboard. - -## πŸ”’ 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. - -If you are on another machine, you can do `:Lazy restore`, to update all your plugins to -the version from the lockfile. - -## ⚑ Performance - -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, -similar to what [impatient.nvim](https://github.com/lewis6991/impatient.nvim) does. - -My config for example loads in about `11ms` with `93` plugins. I do a lot of lazy-loading though :) - -**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. - -![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) - -## ▢️ 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. - -## πŸ“¦ Migration Guide - -### [packer.nvim](https://github.com/wbthomason/packer.nvim) - -- `setup` ➑️ `init` -- `requires` ➑️ `dependencies` -- `as` ➑️ `name` -- `opt` ➑️ `lazy` -- `run` ➑️ `build` -- `lock` ➑️ `pin` -- `disable=true` ➑️ `enabled = false` -- `tag='*'` ➑️ `version="*"` -- `after` is **_not needed_** for most use-cases. Use `dependencies` otherwise. -- `wants` is **_not needed_** for most use-cases. Use `dependencies` otherwise. -- `config` don't support string type, use `fun(LazyPlugin)` instead. -- `module` is auto-loaded. No need to specify -- `keys` spec is [different](#%EF%B8%8F-lazy-key-mappings) -- `rtp` can be accomplished with: - -```lua -config = function(plugin) - vim.opt.rtp:append(plugin.dir .. "/custom-rtp") -end -``` - -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 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. - -### [paq-nvim](https://github.com/savq/paq-nvim) - -- `as` ➑️ `name` -- `opt` ➑️ `lazy` -- `run` ➑️ `build` - -## ❌ 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. - -## 🌈 Highlight Groups - -
-Click to see all highlight groups - - - -| Highlight Group | Default Group | Description | -| --------------------- | -------------------------- | --------------------------------------------------- | -| **LazyButton** | **_CursorLine_** | | -| **LazyButtonActive** | **_Visual_** | | -| **LazyComment** | **_Comment_** | | -| **LazyCommit** | **_@variable.builtin_** | commit ref | -| **LazyCommitIssue** | **_Number_** | | -| **LazyCommitScope** | **_Italic_** | conventional commit scope | -| **LazyCommitType** | **_Title_** | conventional commit type | -| **LazyDimmed** | **_Conceal_** | property | -| **LazyDir** | **_@markup.link_** | directory | -| **LazyH1** | **_IncSearch_** | home button | -| **LazyH2** | **_Bold_** | titles | -| **LazyLocal** | **_Constant_** | | -| **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_** | | -| **LazyReasonRequire** | **_@variable.parameter_** | | -| **LazyReasonRuntime** | **_@macro_** | | -| **LazyReasonSource** | **_Character_** | | -| **LazyReasonStart** | **_@variable.member_** | | -| **LazySpecial** | **_@punctuation.special_** | | -| **LazyTaskError** | **_ErrorMsg_** | task errors | -| **LazyTaskOutput** | **_MsgArea_** | task output | -| **LazyUrl** | **_@markup.link_** | url | -| **LazyValue** | **_@string_** | value of a property | - - - -
- -## πŸ“š Plugin Authors - -If your plugin needs a build step, you can 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. - -## πŸ“¦ Other Neovim Plugin Managers in Lua - -- [pckr.nvim](https://github.com/lewis6991/pckr.nvim) -- [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) -- [pact.nvim](https://github.com/rktjmp/pact.nvim) +Check the [documentation website](https://lazy.folke.io/) for more information. \ No newline at end of file diff --git a/doc/.keep b/doc/.keep new file mode 100644 index 0000000..e69de29 diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt index 876ea0a..14d4a16 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -1,307 +1,324 @@ -*lazy.nvim.txt* For Neovim >= 0.8.0 Last change: 2024 June 23 +*lazy.nvim.txt* A modern plugin manager for Neovim ============================================================================== Table of Contents *lazy.nvim-table-of-contents* -1. lazy.nvim |lazy.nvim-lazy.nvim| - - Features |lazy.nvim-lazy.nvim-features| - - Requirements |lazy.nvim-lazy.nvim-requirements| - - Installation |lazy.nvim-lazy.nvim-installation| - - Plugin Spec |lazy.nvim-lazy.nvim-plugin-spec| - - Configuration |lazy.nvim-lazy.nvim-configuration| - - Usage |lazy.nvim-lazy.nvim-usage| - - Lockfile lazy-lock.json |lazy.nvim-lazy.nvim-lockfile-lazy-lock.json| - - Performance |lazy.nvim-lazy.nvim-performance| - - Debug |lazy.nvim-lazy.nvim-debug| - - Startup Sequence |lazy.nvim-lazy.nvim-startup-sequence| - - Structuring Your Plugins |lazy.nvim-lazy.nvim-structuring-your-plugins| - - Migration Guide |lazy.nvim-lazy.nvim-migration-guide| - - Uninstalling |lazy.nvim-lazy.nvim-uninstalling| - - Highlight Groups |lazy.nvim-lazy.nvim-highlight-groups| - - Plugin Authors |lazy.nvim-lazy.nvim-plugin-authors| - - Other Neovim Plugin Managers in Lua|lazy.nvim-lazy.nvim-other-neovim-plugin-managers-in-lua| -2. Links |lazy.nvim-links| +1. πŸš€ Getting Started |lazy.nvim-πŸš€-getting-started| + - ✨ Features |lazy.nvim-πŸš€-getting-started-✨-features| + - ⚑️ Requirements |lazy.nvim-πŸš€-getting-started-⚑️-requirements| +2. πŸ› οΈ Installation |lazy.nvim-πŸ› οΈ-installation| + - Structured Setup |lazy.nvim-πŸ› οΈ-installation-structured-setup| + - Single File Setup |lazy.nvim-πŸ› οΈ-installation-single-file-setup| +3. πŸ”Œ Plugin Spec |lazy.nvim-πŸ”Œ-plugin-spec| + - Spec Source |lazy.nvim-πŸ”Œ-plugin-spec-spec-source| + - Spec Loading |lazy.nvim-πŸ”Œ-plugin-spec-spec-loading| + - Spec Setup |lazy.nvim-πŸ”Œ-plugin-spec-spec-setup| + - Spec Lazy Loading |lazy.nvim-πŸ”Œ-plugin-spec-spec-lazy-loading| + - Spec Versioning |lazy.nvim-πŸ”Œ-plugin-spec-spec-versioning| + - Spec Advanced |lazy.nvim-πŸ”Œ-plugin-spec-spec-advanced| + - Examples |lazy.nvim-πŸ”Œ-plugin-spec-examples| + - Lazy Loading |lazy.nvim-πŸ”Œ-plugin-spec-lazy-loading| + - Versioning |lazy.nvim-πŸ”Œ-plugin-spec-versioning| +4. πŸ“¦ Packages |lazy.nvim-πŸ“¦-packages| + - Lazy |lazy.nvim-πŸ“¦-packages-lazy| + - Rockspec |lazy.nvim-πŸ“¦-packages-rockspec| + - Packspec |lazy.nvim-πŸ“¦-packages-packspec| +5. βš™οΈ Configuration |lazy.nvim-βš™οΈ-configuration| + - 🌈 Highlight Groups|lazy.nvim-βš™οΈ-configuration-🌈-highlight-groups| +6. πŸš€ Usage |lazy.nvim-πŸš€-usage| + - ▢️ Startup Sequence |lazy.nvim-πŸš€-usage-▢️-startup-sequence| + - πŸš€ Commands |lazy.nvim-πŸš€-usage-πŸš€-commands| + - πŸ“† User Events |lazy.nvim-πŸš€-usage-πŸ“†-user-events| + - ❌ Uninstalling |lazy.nvim-πŸš€-usage-❌-uninstalling| + - πŸ”’ Lockfile |lazy.nvim-πŸš€-usage-πŸ”’-lockfile| + - πŸ“¦ Migration Guide |lazy.nvim-πŸš€-usage-πŸ“¦-migration-guide| + - ⚑ Profiling & Debug |lazy.nvim-πŸš€-usage-⚑-profiling-&-debug| + - πŸ“‚ Structuring Your Plugins|lazy.nvim-πŸš€-usage-πŸ“‚-structuring-your-plugins| +7. πŸ“š Plugin Developers |lazy.nvim-πŸ“š-plugin-developers| +8. Links |lazy.nvim-links| ============================================================================== -1. lazy.nvim *lazy.nvim-lazy.nvim* +1. πŸš€ Getting Started *lazy.nvim-πŸš€-getting-started* **lazy.nvim** is a modern plugin manager for Neovim. -FEATURES *lazy.nvim-lazy.nvim-features* +✨ FEATURES *lazy.nvim-πŸš€-getting-started-✨-features* -- Manage all your Neovim plugins with a powerful UI -- Fast startup times thanks to automatic caching and bytecode compilation of Lua modules -- Partial clones instead of shallow clones -- 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 -- Async execution for improved performance -- No need to manually compile plugins -- Correct sequencing of dependencies -- Configurable in multiple files -- Generates helptags of the headings in `README.md` files for plugins that don’t have vimdocs -- Dev options and patterns for using local plugins -- Profiling tools to optimize performance -- Lockfile `lazy-lock.json` to keep track of installed plugins -- Automatically check for updates -- Commit, branch, tag, version, and full Semver support -- Statusline component to see the number of pending updates -- Automatically lazy-loads colorschemes +- πŸ“¦ Manage all your Neovim plugins with a powerful UI +- πŸš€ Fast startup times thanks to automatic caching and bytecode compilation of Lua modules +- πŸ’Ύ Partial clones instead of shallow clones +- πŸ”Œ 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 +- πŸ’ͺ Async execution for improved performance +- πŸ› οΈ No need to manually compile plugins +- πŸ§ͺ Correct sequencing of dependencies +- πŸ“ Configurable in multiple files +- πŸ“š Generates helptags of the headings in `README.md` files for plugins that don’t have vimdocs +- πŸ’» Dev options and patterns for using local plugins +- πŸ“Š Profiling tools to optimize performance +- πŸ”’ Lockfile `lazy-lock.json` to keep track of installed plugins +- πŸ”Ž Automatically check for updates +- πŸ“‹ Commit, branch, tag, version, and full Semver support +- πŸ“ˆ Statusline component to see the number of pending updates +- 🎨 Automatically lazy-loads colorschemes -REQUIREMENTS *lazy.nvim-lazy.nvim-requirements* +⚑️ REQUIREMENTS *lazy.nvim-πŸš€-getting-started-⚑️-requirements* - Neovim >= **0.8.0** (needs to be built with **LuaJIT**) - Git >= **2.19.0** (for partial clones support) - a Nerd Font **(optional)** -INSTALLATION *lazy.nvim-lazy.nvim-installation* +============================================================================== +2. πŸ› οΈ Installation *lazy.nvim-πŸ› οΈ-installation* -You can add the following Lua code to your `init.lua` to bootstrap -**lazy.nvim** +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 section for an overview of +all available options. + + + + +STRUCTURED SETUP *lazy.nvim-πŸ› οΈ-installation-structured-setup* >lua + require("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 - vim.fn.system({ - "git", - "clone", - "--filter=blob:none", - "https://github.com/folke/lazy.nvim.git", - "--branch=stable", -- latest stable release - lazypath, - }) + 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) -< - -Nextstep 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 |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 - vim.g.mapleader = " " -- Make sure to set `mapleader` before lazy so your mappings are correct - vim.g.maplocalleader = "\\" -- Same for `maplocalleader` + -- Make sure to setup `mapleader` and `maplocalleader` before + -- loading lazy.nvim so that mappings are correct. + -- This is also a good place to setup other settings (vim.opt) + vim.g.mapleader = " " + vim.g.maplocalleader = "\\" + + -- Setup lazy.nvim require("lazy").setup({ - "folke/which-key.nvim", - { "folke/neoconf.nvim", cmd = "Neoconf" }, - "folke/neodev.nvim", + -- highlight-start + spec = { + -- import your plugins + { import = "plugins" }, + }, + -- highlight-end + -- Configure any other settings here. See the documentation for more details. + -- colorscheme that will be used when installing plugins. + install = { colorscheme = { "habamax" } }, + -- automatically check for plugin updates + checker = { enabled = true }, }) < -It is recommended to run `:checkhealth lazy` after installation. +You can then create your plugin specs in `~/.config/nvim/lua/plugins/`. Each +file should return a table with the plugins you want to install. + +For more info see Structuring Your Plugins -PLUGIN SPEC *lazy.nvim-lazy.nvim-plugin-spec* - - ------------------------------------------------------------------------------------------------------------------------------------ - 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(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. - - 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(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() - - 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. - - branch string? Branch of the repository - - tag string? Tag 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 - 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[] or BufEnter or with a pattern like BufEnter *.lua - {event:string[]\|string, pattern?:string[]\|string} - - 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 LazyKeysSpec[] or Lazy-load on key mapping - fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[] - - 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. - - 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 - ------------------------------------------------------------------------------------------------------------------------------------ - -LAZY LOADING ~ - -**lazy.nvim** automagically lazy-loads Lua modules, so it is not needed to -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 -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`. 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`. - -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` - -- Theplugin only exists as a dependency in your spec -- It has an `event`, `cmd`, `ft` or `keys` key -- `config.defaults.lazy == true` - - -COLORSCHEMES - -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 - 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)** - -LAZY KEY MAPPINGS - -The `keys` property can be a `string` or `string[]` for simple normal-mode -mappings, or it can be a `LazyKeysSpec` table with the following key-value -pairs: - -- **[1]**(`string`) lhs **(required)** -- **[2]**(`string|fun()`) rhs **(optional)** -- **mode**(`string|string[]`) mode **(optional, defaults to "n")** -- **ft**(`string|string[]`) `filetype` for buffer-local keymaps **(optional)** -- 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. +SINGLE FILE SETUP *lazy.nvim-πŸ› οΈ-installation-single-file-setup* >lua - -- Example for neo-tree.nvim - { - "nvim-neo-tree/neo-tree.nvim", - keys = { - { "ft", "Neotree toggle", desc = "NeoTree" }, - }, - config = function() - require("neo-tree").setup() - end, - } + -- 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` and `maplocalleader` before + -- loading lazy.nvim so that mappings are correct. + -- This is also a good place to setup other settings (vim.opt) + vim.g.mapleader = " " + vim.g.maplocalleader = "\\" + + -- Setup lazy.nvim + require("lazy").setup({ + -- highlight-start + spec = { + -- add your plugins here + }, + -- highlight-end + -- Configure any other settings here. See the documentation for more details. + -- colorscheme that will be used when installing plugins. + install = { colorscheme = { "habamax" } }, + -- automatically check for plugin updates + checker = { enabled = true }, + }) < -VERSIONING ~ - -If you want to install a specific revision of a plugin, you can use `commit`, -`tag`, `branch`, `version`. - -The `version` property supports Semver ranges. - -Click to see some examples ~ - -- `*`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 - -You can set `config.defaults.version = "*"` to install the latest stable -version of plugins that support Semver. +============================================================================== +3. πŸ”Œ Plugin Spec *lazy.nvim-πŸ”Œ-plugin-spec* -EXAMPLES ~ +SPEC SOURCE *lazy.nvim-πŸ”Œ-plugin-spec-spec-source* + + ----------------------------------------------------------------------------------- + Property Type Description + ---------- ---------- ------------------------------------------------------------- + [1] string? Short plugin url. Will be expanded using + config.git.url_format. Can also be a url or dir. + + 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 + ----------------------------------------------------------------------------------- +A valid spec should define one of `[1]`, `dir` or `url`. + + +SPEC LOADING *lazy.nvim-πŸ”Œ-plugin-spec-spec-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. + + 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 Behaves the same as enabled, but won’t uninstall the + fun(LazyPlugin):boolean 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. + -------------------------------------------------------------------------------------------------- + +SPEC SETUP *lazy.nvim-πŸ”Œ-plugin-spec-spec-setup* + + ----------------------------------------------------------------------------------------------------- + Property Type Description + ---------- ----------------------------- ------------------------------------------------------------ + init fun(LazyPlugin) init functions are always executed during startup + + opts table or opts should be a table (will be merged with parent specs), + fun(LazyPlugin, opts:table) 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) config is executed when the plugin loads. The default + or true 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() + + build fun(LazyPlugin) or string or build is executed when a plugin is installed or updated. + a list of build commands 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 dependencies. + ----------------------------------------------------------------------------------------------------- + +SPEC LAZY LOADING *lazy.nvim-πŸ”Œ-plugin-spec-spec-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 Lazy-load on event. Events can be + fun(self:LazyPlugin, event:string[]):string[] or specified as BufEnter or with a pattern + {event:string[]\|string, pattern?:string[]\|string} 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 LazyKeysSpec[] or Lazy-load on key mapping + fun(self:LazyPlugin, keys:string[]):(string \| LazyKeysSpec)[] + -------------------------------------------------------------------------------------------------------------------- +Refer to the Lazy Loading <./lazy_loading.md> section for more information. + + +SPEC VERSIONING *lazy.nvim-πŸ”Œ-plugin-spec-spec-versioning* + + ------------------------------------------------------------------------------ + Property Type Description + ------------ -------------------- -------------------------------------------- + branch string? Branch of the repository + + tag string? Tag of the repository + + commit string? Commit of the repository + + version string? or false to Version to use from the repository. Full + override the default 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 + ------------------------------------------------------------------------------ +Refer to the Versioning <./versioning.md> section for more information. + + +SPEC ADVANCED *lazy.nvim-πŸ”Œ-plugin-spec-spec-advanced* + + ---------------------------------------------------------------------------------------- + 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. + + 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. + ---------------------------------------------------------------------------------------- + +EXAMPLES *lazy.nvim-πŸ”Œ-plugin-spec-examples* >lua return { @@ -394,7 +411,120 @@ EXAMPLES ~ < -CONFIGURATION *lazy.nvim-lazy.nvim-configuration* +LAZY LOADING *lazy.nvim-πŸ”Œ-plugin-spec-lazy-loading* + +**lazy.nvim** automagically lazy-loads Lua modules. This means 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. + + +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 +- It has an `event`, `cmd`, `ft` or `keys` key +- `config.defaults.lazy == true` + + +🌈 COLORSCHEMES ~ + +Colorscheme plugins can be configured with `lazy=true`. The plugin will +automagically load when doing `colorscheme foobar`. + + + +⌨️ LAZY KEY MAPPINGS ~ + +The `keys` property can be a `string` or `string[]` for simple normal-mode +mappings, or it can be a `LazyKeysSpec` table with the following key-value +pairs: + +- **[1]**: (`string`) lhs **(required)** +- **[2]**: (`string|fun()`) rhs **(optional)** +- **mode**: (`string|string[]`) mode **(optional, defaults to "n")** +- **ft**: (`string|string[]`) `filetype` for buffer-local keymaps **(optional)** +- 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 = { + { "ft", "Neotree toggle", desc = "NeoTree" }, + }, + config = function() + require("neo-tree").setup() + end, + } +< + + +VERSIONING *lazy.nvim-πŸ”Œ-plugin-spec-versioning* + +If you want to install a specific revision of a plugin, you can use `commit`, +`tag`, `branch`, `version`. + +The `version` property supports Semver ranges. + + + +EXAMPLES ~ + +- `*`: 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 + + +============================================================================== +4. πŸ“¦ Packages *lazy.nvim-πŸ“¦-packages* + +**lazy.nvim** supports three ways for plugins to define their dependencies and +configuration. + +- **Lazy**: `lazy.lua` file +- **Rockspec**: luarocks `*-scm-1.rockspec` file +- **Packspec**: `pkg.json` (experimental, since the format is not quite there yet) + +You can enable/disable package sources with `config.pkg.sources` +. The order of sources is important, as the first source that +finds a package will be used. + + + +LAZY *lazy.nvim-πŸ“¦-packages-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 *lazy.nvim-πŸ“¦-packages-rockspec* + +When a plugin contains a `*-scm-1.rockspec` file, **lazy.nvim** will +automatically load its `rocks` dependencies. + + +PACKSPEC *lazy.nvim-πŸ“¦-packages-packspec* + +Supports the pkg.json + format, with +a lazy extension in `lazy`. `lazy` can contain any valid lazy spec fields. They +will be added to the plugin’s spec. + + +============================================================================== +5. βš™οΈ Configuration *lazy.nvim-βš™οΈ-configuration* **lazy.nvim** comes with the following defaults: @@ -402,8 +532,13 @@ CONFIGURATION *lazy.nvim-lazy.nvim-configuration* { root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed 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, -- should plugins be lazy-loaded? - version = nil, + -- 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 = nil, -- always use the latest git commit + -- version = "*", -- try installing the latest stable version for plugins that support semver -- default `cond` you can use to globally disable a lot of plugins -- when running inside vscode for example cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil @@ -426,6 +561,21 @@ CONFIGURATION *lazy.nvim-lazy.nvim-configuration* -- increase downloads a lot. filter = true, }, + pkg = { + enabled = true, + cache = vim.fn.stdpath("state") .. "/lazy/pkg-cache.lua", + versions = true, -- Honor versions in pkg sources + -- the first package source that is found for a plugin will be used. + sources = { + "lazy", + "rockspec", + "packspec", + }, + }, + rocks = { + root = vim.fn.stdpath("data") .. "/lazy-rocks", + server = "https://nvim-neorocks.github.io/rocks-binaries/", + }, dev = { ---@type string | fun(plugin: LazyPlugin): string directory where you store your local plugin projects path = "~/projects", @@ -455,6 +605,7 @@ CONFIGURATION *lazy.nvim-lazy.nvim-configuration* cmd = "ξ―‡ ", config = "", event = "ξͺ† ", + favorite = "ο€… ", ft = "ο€– ", init = " ", import = " ", @@ -601,7 +752,101 @@ If you don’t want to use a Nerd Font, you can replace the icons with Unicode s < -USAGE *lazy.nvim-lazy.nvim-usage* +🌈 HIGHLIGHT GROUPS *lazy.nvim-βš™οΈ-configuration-🌈-highlight-groups* + + ----------------------------------------------------------------------- + Highlight Group Default Group Description + ----------------------- ----------------------- ----------------------- + LazyButton CursorLine + + LazyButtonActive Visual + + LazyComment Comment + + LazyCommit @variable.builtin commit ref + + LazyCommitIssue Number + + LazyCommitScope Italic conventional commit + scope + + LazyCommitType Title conventional commit + type + + LazyDimmed Conceal property + + LazyDir @markup.link directory + + LazyH1 IncSearch home button + + LazyH2 Bold titles + + LazyLocal Constant + + 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 + + LazyReasonRequire @variable.parameter + + LazyReasonRuntime @macro + + LazyReasonSource Character + + LazyReasonStart @variable.member + + LazySpecial @punctuation.special + + LazyTaskError ErrorMsg task errors + + LazyTaskOutput MsgArea task output + + LazyUrl @markup.link url + + LazyValue @string value of a property + ----------------------------------------------------------------------- + +============================================================================== +6. πŸš€ Usage *lazy.nvim-πŸš€-usage* + + +▢️ STARTUP SEQUENCE *lazy.nvim-πŸš€-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| 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 *lazy.nvim-πŸš€-usage-πŸš€-commands* Plugins are managed with the `:Lazy` command. Open the help with `` to see all the key mappings. @@ -616,14 +861,17 @@ enabled with `config.checker.enabled = true`. Any operation can be started from the UI, with a sub command or an API function: - -------------------------------------------------------------------------------------------------------------- + ---------------------------------------------------------------------------------- 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 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 :Lazy clear require("lazy").clear() Clear finished tasks @@ -637,24 +885,36 @@ function: :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 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 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 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 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 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 example, if you want to sync lazy from the cmdline, you can use: @@ -664,10 +924,10 @@ example, if you want to sync lazy from the cmdline, you can use: `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 +- **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 Stats API (`require("lazy").stats()`): @@ -707,34 +967,47 @@ Example of configuring lualine.nvim ~ < -USER EVENTS ~ +πŸ“† USER EVENTS *lazy.nvim-πŸš€-usage-πŸ“†-user-events* The following user events will be triggered: -- **LazyDone**when lazy has finished starting up and loaded your config -- **LazySync**after running sync -- **LazyInstall**after an install -- **LazyUpdate**after an update -- **LazyClean**after a clean -- **LazyCheck**after checking for updates -- **LazyLog**after running log -- **LazyLoad**after loading a plugin. The `data` attribute will contain the plugin name. -- **LazySyncPre**before running sync -- **LazyInstallPre**before an install -- **LazyUpdatePre**before an update -- **LazyCleanPre**before a clean -- **LazyCheckPre**before checking for updates -- **LazyLogPre**before running log -- **LazyReload**triggered by change detection after reloading plugin specs -- **VeryLazy**triggered after `LazyDone` and processing `VimEnter` auto commands -- **LazyVimStarted**triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. +- **LazyDone**: when lazy has finished starting up and loaded your config +- **LazySync**: after running sync +- **LazyInstall**: after an install +- **LazyUpdate**: after an update +- **LazyClean**: after a clean +- **LazyCheck**: after checking for updates +- **LazyLog**: after running log +- **LazyLoad**: after loading a plugin. The `data` attribute will contain the plugin name. +- **LazySyncPre**: before running sync +- **LazyInstallPre**: before an install +- **LazyUpdatePre**: before an update +- **LazyCleanPre**: before a clean +- **LazyCheckPre**: before checking for updates +- **LazyLogPre**: before running log +- **LazyReload**: triggered by change detection after reloading plugin specs +- **VeryLazy**: triggered after `LazyDone` and processing `VimEnter` auto commands +- **LazyVimStarted**: triggered after `UIEnter` when `require("lazy").stats().startuptime` has been calculated. Useful to update the startuptime on your dashboard. -LOCKFILE LAZY-LOCK.JSON *lazy.nvim-lazy.nvim-lockfile-lazy-lock.json* +❌ UNINSTALLING *lazy.nvim-πŸš€-usage-❌-uninstalling* -After every **update**, the local lockfile is updated with the installed -revisions. It is recommended to have this file under version control. +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. + +πŸ”’ LOCKFILE *lazy.nvim-πŸš€-usage-πŸ”’-lockfile* + +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 ensure that the same version of every plugin is installed. @@ -743,7 +1016,49 @@ If you are on another machine, you can do `:Lazy restore`, to update all your plugins to the version from the lockfile. -PERFORMANCE *lazy.nvim-lazy.nvim-performance* +πŸ“¦ MIGRATION GUIDE *lazy.nvim-πŸš€-usage-πŸ“¦-migration-guide* + + +PACKER.NVIM ~ + +- `setup` ➑️ `init` +- `requires` ➑️ `dependencies` +- `as` ➑️ `name` +- `opt` ➑️ `lazy` +- `run` ➑️ `build` +- `lock` ➑️ `pin` +- `disable=true` ➑️ `enabled = false` +- `tag='*'` ➑️ `version="*"` +- `after` is **not needed** for most use-cases. Use `dependencies` otherwise. +- `wants` is **not needed** for most use-cases. Use `dependencies` otherwise. +- `config` don’t support string type, use `fun(LazyPlugin)` instead. +- `module` is auto-loaded. No need to specify +- `keys` spec is |lazy.nvim-different| +- `rtp` can be accomplished with: + +>lua + config = function(plugin) + vim.opt.rtp:append(plugin.dir .. "/custom-rtp") + end +< + +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 +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. + + +PAQ-NVIM ~ + +- `as` ➑️ `name` +- `opt` ➑️ `lazy` +- `run` ➑️ `build` + + +⚑ PROFILING & DEBUG *lazy.nvim-πŸš€-usage-⚑-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 @@ -758,29 +1073,13 @@ improve performance. The profiling view shows you why and how long it took to load your plugins. -DEBUG *lazy.nvim-lazy.nvim-debug* +πŸ› DEBUG ~ See an overview of active lazy-loading handlers and what’s in the module cache. -STARTUP SEQUENCE *lazy.nvim-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. - -In practice this means that step 10 of |Neovim 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 *lazy.nvim-lazy.nvim-structuring-your-plugins* +πŸ“‚ STRUCTURING YOUR PLUGINS*lazy.nvim-πŸš€-usage-πŸ“‚-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 @@ -820,7 +1119,7 @@ For a real-life example, you can check LazyVim - 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 modules. Both of the `setup()` calls are equivalent: @@ -852,155 +1151,21 @@ the parent spec. Any other property will override the property from the parent spec. -MIGRATION GUIDE *lazy.nvim-lazy.nvim-migration-guide* +============================================================================== +7. πŸ“š Plugin Developers *lazy.nvim-πŸ“š-plugin-developers* +To make it easier for users to install your plugin, you can include a package +spec in your repo. -PACKER.NVIM ~ - -- `setup` `init` -- `requires` `dependencies` -- `as` `name` -- `opt` `lazy` -- `run` `build` -- `lock` `pin` -- `disable=true` `enabled = false` -- `tag='*'` `version="*"` -- `after` is **not needed** for most use-cases. Use `dependencies` otherwise. -- `wants` is **not needed** for most use-cases. Use `dependencies` otherwise. -- `config` don’t support string type, use `fun(LazyPlugin)` instead. -- `module` is auto-loaded. No need to specify -- `keys` spec is |lazy.nvim-different| -- `rtp` can be accomplished with: - ->lua - config = function(plugin) - vim.opt.rtp:append(plugin.dir .. "/custom-rtp") - end -< - -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 -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. - - -PAQ-NVIM ~ - -- `as` `name` -- `opt` `lazy` -- `run` `build` - - -UNINSTALLING *lazy.nvim-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. - -HIGHLIGHT GROUPS *lazy.nvim-lazy.nvim-highlight-groups* - -Click to see all highlight groups ~ - - --------------------------------------------------------------------------------- - Highlight Group Default Group Description - ------------------- ------------------------ ------------------------------------ - LazyButton CursorLine - - LazyButtonActive Visual - - LazyComment Comment - - LazyCommit _@variable.builtin_ commitref - - LazyCommitIssue Number - - LazyCommitScope Italic conventional commit scope - - LazyCommitType Title conventional commit type - - LazyDimmed Conceal property - - LazyDir _@markup.link_ directory - - LazyH1 IncSearch homebutton - - LazyH2 Bold titles - - LazyLocal Constant - - 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 - - LazyReasonRequire _@variable.parameter_ - - LazyReasonRuntime _@macro_ - - LazyReasonSource Character - - LazyReasonStart _@variable.member_ - - LazySpecial _@punctuation.special_ - - LazyTaskError ErrorMsg taskerrors - - LazyTaskOutput MsgArea task output - - LazyUrl _@markup.link_ url - - LazyValue _@string_ valueof a property - --------------------------------------------------------------------------------- - -PLUGIN AUTHORS *lazy.nvim-lazy.nvim-plugin-authors* - -If your plugin needs a build step, you can 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. +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. - -OTHER NEOVIM PLUGIN MANAGERS IN LUA*lazy.nvim-lazy.nvim-other-neovim-plugin-managers-in-lua* - -- pckr.nvim -- packer.nvim -- paq-nvim -- neopm -- dep -- optpack.nvim -- pact.nvim - ============================================================================== -2. Links *lazy.nvim-links* +8. 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 diff --git a/lua/lazy/core/config.lua b/lua/lazy/core/config.lua index 46fbfd5..1b5d734 100644 --- a/lua/lazy/core/config.lua +++ b/lua/lazy/core/config.lua @@ -7,8 +7,13 @@ local M = {} M.defaults = { root = vim.fn.stdpath("data") .. "/lazy", -- directory where plugins will be installed 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, -- should plugins be lazy-loaded? - version = nil, + -- 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 = nil, -- always use the latest git commit + -- version = "*", -- try installing the latest stable version for plugins that support semver -- default `cond` you can use to globally disable a lot of plugins -- when running inside vscode for example cond = nil, ---@type boolean|fun(self:LazyPlugin):boolean|nil