+ Install + · + Configure + · + Docs +
+ + + + **lazy.nvim** is a modern plugin manager for Neovim. - + ## ✨ Features -- 📦 Manage all your Neovim plugins with a sleek and intuitive UI -- 🚀 Fast startup times thanks to automatic caching and bytecode compilation of lua modules. +- 📦 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. +- 🔌 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](https://devhints.io/semver) support - 📈 Statusline component to see the number of pending updates +- 🎨 Automatically lazy-loads colorschemes ## ⚡️ Requirements -- Neovim >= **0.8.0** +- Neovim >= **0.8.0** (needs to be built with **LuaJIT**) +- Git >= **2.19.0** (for partial clones support) +- a [Nerd Font](https://www.nerdfonts.com/) **_(optional)_** +- [luarocks](https://luarocks.org/) to install rockspecs. + You can remove `rockspec` from `opts.pkg.sources` to disable this feature. -## 📦 Installation +## 🚀 Getting Started -You can use the following Lua code to bootstrap **lazy.nvim** - -```lua - local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim" - if not vim.loop.fs_stat(lazypath) then - vim.fn.system({ - "git", - "clone", - "--filter=blob:none", - "--single-branch", - "https://github.com/folke/lazy.nvim.git", - lazypath, - }) - vim.opt.runtimepath:prepend(lazypath) - end -``` - -Next step is to add **lazy.nvim** to the top of your `init.lua` - -```lua --- You can use a lua module that contains your plugins. --- All sub modules of the lua module will also be automatically loaded --- This is the preferred setup so your plugin specs can be properly cached. -require("lazy").setup("config.plugins", { - -- add any optional configuration options here -}) - --- Alternatively you can specify a plugin list -require("lazy").setup({ - "folke/neodev.nvim", - "folke/which-key.nvim", - { "folke/neoconf.nvim", cmd = "Neoconf" }, - }, { - -- add any optional configuration options here -}) -``` - -## ⚙️ 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, - -- version = "*", -- enable this to try installing the latest stable versions of plugins - }, - lockfile = vim.fn.stdpath("config") .. "/lazy-lock.json", -- lockfile generated after running update. - concurrency = nil, ---@type number limit the maximum amount of concurrent tasks - git = { - -- defaults for the `Lazy log` command - -- log = { "-10" }, -- show the last 10 commits - log = { "--since=1 days ago" }, -- show commits from the last 3 days - timeout = 120, -- kill processes that take more than 2 minutes - url_format = "https://github.com/%s.git", - }, - dev = { - -- directory where you store your local plugin projects - path = vim.fn.expand("~/projects"), - ---@type string[] plugins that match these patterns will use your local versions instead of being fetched from GitHub - patterns = {}, -- For example {"folke"} - }, - install = { - -- install missing plugins on startup. This doesn't increase startup time. - missing = true, - -- try to load one of these colorschemes when starting an installation during startup - colorscheme = { "habamax" }, - }, - ui = { - -- The border to use for the UI window. Accepts same border values as |nvim_open_win()|. - border = "none", - icons = { - cmd = " ", - config = "", - event = "", - ft = " ", - init = " ", - keys = " ", - plugin = " ", - runtime = " ", - source = " ", - start = "", - task = "✔ ", - }, - throttle = 20, -- how frequently should the ui process render events - }, - checker = { - -- automcatilly 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 - }, - performance = { - cache = { - enabled = true, - path = vim.fn.stdpath("state") .. "/lazy.state", - -- Once one of the following events triggers, caching will be disabled. - -- To cache all modules, set this to `{}`, but that is not recommended. - -- The default is to disable on: - -- * VimEnter: not useful to cache anything else beyond startup - -- * BufReadPre: this will be triggered early when opening a file from the command line directly - disable_events = { "VimEnter", "BufReadPre" }, - }, - 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[] list any plugins you want to disable here - disabled_plugins = { - -- "gzip", - -- "matchit", - -- "matchparen", - -- "netrwPlugin", - -- "tarPlugin", - -- "tohtml", - -- "tutor", - -- "zipPlugin", - }, - }, - }, -} -``` - -## 🚀 Usage - -## 📊 Profiler - -The profiling view shows you why and how long it took to load your plugins. - - - -## 🪲 Debug - -See an overview of active lazy-loading handlers and what's in the module cache - - - -## 📦 Differences with Packer - -- **Plugin Spec**: - - - `setup` => `init` - - `requires` => `dependencies` - - `as` => `name` - - `opt` => `lazy` - - `run` => `build` - - `lock` => `pin` - - `module` is auto-loaded. No need to specify - -## 📦 Other Neovim Plugin Managers in Lua - -- [packer.nvim](https://github.com/wbthomason/packer.nvim) -- [paq-nvim](https://github.com/savq/paq-nvim) -- [neopm](https://github.com/ii14/neopm) -- [dep](https://github.com/chiyadev/dep) -- [optpack.nvim](https://github.com/notomo/optpack.nvim) -- [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/TODO.md b/TODO.md index 88eae3f..3d4da4e 100644 --- a/TODO.md +++ b/TODO.md @@ -1,4 +1,14 @@ -## ✅ TODO +# ✅ TODO + +- [x] progress bar? +- [x] options when opening file +- [x] lazy notify? not ideal when installing missing stuff +- [x] topmods? + +- [ ] better merging options? +- [ ] especially what to do with merging of handlers? +- [ ] overwriting keymaps probably doesn't work +- [ ] disabled deps? - [x] fancy UI to manage all your Neovim plugins - [x] auto lazy-loading of lua modules @@ -31,14 +41,39 @@ - [x] automatically reloads when config changes are detected - [x] handlers imply opt - [x] dependencies imply opt for deps -- [ ] show spec errors in health -- [ ] fix plugin details +- [x] show spec errors in health +- [x] fix plugin details - [ ] show disabled plugins (strikethrough?) - [ ] log file -- [ ] git tests -- [ ] Import specs from other plugin managers +- [x] git tests +- [x] Import specs from other plugin managers - [ ] [packspec](https://github.com/nvim-lua/nvim-package-specification) + - [ ] add support to specify `engines`, `os` and `cpu` like in `package.json` - [ ] semver merging. Should check if two or more semver ranges are compatible and calculate the union range - - default semver merging strategy: if no version matches all, then use highest version? + - default semver merging strategy: if no version matches all, then use the highest version? - [ ] package meta index (package.lua cache for all packages) + +- [x] document highlight groups +- [x] document user events +- [x] document API, like lazy.plugins() +- [x] icons + +- [x] check in cache if rtp files match +- [x] I think the installation section, specifically the loading part, could use an + extra sentence or two. I was confused on what `config.plugins` was initially. + Maybe a quick, "for example, if you have a lua file + `~/.config/nvim/lua/config/plugins.lua` that returns a table" or something it'd + remove most question marks I think. +- [x] When auto-installing the plugins the cursor isn't focused on the floating + window, but on the non-floating window in the background. +- [x] Doing `:Lazy clean` doesn't show which plugins were removed. +- [x] Shouldn't the "Versioning" section be in the "Lockfile" chapter? +- [x] Why are personal dotfiles used as examples? Dotfiles change all the time, + there's no guarantee this will be relevant or even exist in two years. +- [x] What's the difference between lazy-loading and verylazy-loading? +- [x] Most emojis in "Configuration" aren't shown for me. +- [x] add section on how to uninstall +- [x] add `:Packadd` command or something similar +- [x] headless install +- [x] better keys handling diff --git a/bootstrap.lua b/bootstrap.lua new file mode 100644 index 0000000..c934c48 --- /dev/null +++ b/bootstrap.lua @@ -0,0 +1,51 @@ +-- Lazy Bootstrapper +-- Usage: +-- ```lua +-- load(vim.fn.system("curl -s https://raw.githubusercontent.com/folke/lazy.nvim/main/bootstrap.lua"))() +-- ``` +local M = {} + +function M.setup() + local uv = vim.uv or vim.loop + if vim.env.LAZY_STDPATH then + local root = vim.fn.fnamemodify(vim.env.LAZY_STDPATH, ":p"):gsub("[\\/]$", "") + for _, name in ipairs({ "config", "data", "state", "cache" }) do + vim.env[("XDG_%s_HOME"):format(name:upper())] = root .. "/" .. name + end + end + + if vim.env.LAZY_PATH and not uv.fs_stat(vim.env.LAZY_PATH) then + vim.env.LAZY_PATH = nil + end + + local lazypath = vim.env.LAZY_PATH or vim.fn.stdpath("data") .. "/lazy/lazy.nvim" + if not vim.env.LAZY_PATH and not uv.fs_stat(lazypath) then + vim.api.nvim_echo({ + { + "Cloning lazy.nvim\n\n", + "DiagnosticInfo", + }, + }, true, {}) + local lazyrepo = "https://github.com/folke/lazy.nvim.git" + local ok, out = pcall(vim.fn.system, { + "git", + "clone", + "--filter=blob:none", + lazyrepo, + lazypath, + }) + if not ok or vim.v.shell_error ~= 0 then + vim.api.nvim_echo({ + { "Failed to clone lazy.nvim\n", "ErrorMsg" }, + { vim.trim(out or ""), "WarningMsg" }, + { "\nPress any key to exit...", "MoreMsg" }, + }, true, {}) + vim.fn.getchar() + os.exit(1) + end + end + vim.opt.rtp:prepend(lazypath) +end +M.setup() + +return M 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 42467f8..2ae3b36 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -1,122 +1,689 @@ -*lazy.nvim.txt* For NVIM v0.5.0 Last change: 2022 December 14 +*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-features| - - Requirements |lazy.nvim-requirements| - - Installation |lazy.nvim-installation| - - Configuration |lazy.nvim-configuration| - - Usage |lazy.nvim-usage| - - Profiler |lazy.nvim-profiler| - - 🪲 Debug |lazy.nvim-🪲-debug| - - Differences with Packer |lazy.nvim-differences-with-packer| - - Other Neovim Plugin Managers in Lua|lazy.nvim-other-neovim-plugin-managers-in-lua| +1. 📰 What’s new? |lazy.nvim-📰-what’s-new?| + - 11.x |lazy.nvim-📰-what’s-new?-11.x| +2. 🚀 Getting Started |lazy.nvim-🚀-getting-started| + - ✨ Features |lazy.nvim-🚀-getting-started-✨-features| + - ⚡️ Requirements |lazy.nvim-🚀-getting-started-⚡️-requirements| +3. 🛠️ Installation |lazy.nvim-🛠️-installation| + - Structured Setup |lazy.nvim-🛠️-installation-structured-setup| + - Single File Setup |lazy.nvim-🛠️-installation-single-file-setup| +4. 🔌 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| +5. 📦 Packages |lazy.nvim-📦-packages| + - Lazy |lazy.nvim-📦-packages-lazy| + - Rockspec |lazy.nvim-📦-packages-rockspec| + - Packspec |lazy.nvim-📦-packages-packspec| +6. ⚙️ Configuration |lazy.nvim-⚙️-configuration| + - 🌈 Highlight Groups|lazy.nvim-⚙️-configuration-🌈-highlight-groups| +7. 🚀 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| +8. 🔥 Developers |lazy.nvim-🔥-developers| + - Best Practices |lazy.nvim-🔥-developers-best-practices| + - Building |lazy.nvim-🔥-developers-building| + - Minit (Minimal Init) |lazy.nvim-🔥-developers-minit-(minimal-init)| +9. Links |lazy.nvim-links| ============================================================================== -1. lazy.nvim *lazy.nvim-lazy.nvim* +1. 📰 What’s new? *lazy.nvim-📰-what’s-new?* + + +11.X *lazy.nvim-📰-what’s-new?-11.x* + +- **New Website**: There’s a whole new website with a fresh look and improved + documentation. Check it out at
+ 
+ 
+ 
+ 
+ 
+ 
+
-
-
-FEATURES *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
-image
-
-
-
+ LazyButtonActive Visual
-🪲 DEBUG *lazy.nvim-🪲-debug*
+ 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
+
+ LazyError DiagnosticError task errors
+
+ LazyH1 IncSearch home button
+
+ LazyH2 Bold titles
+
+ LazyInfo DiagnosticInfo task errors
+
+ LazyItalic { italic = true }
+
+ 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
+
+ LazyTaskOutput MsgArea task output
+
+ LazyUrl @markup.link url
+
+ LazyValue @string value of a property
+
+ LazyWarning DiagnosticWarn task errors
+ -----------------------------------------------------------------------
+
+==============================================================================
+7. 🚀 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.
+
+You can press `
-image
-
-
-
-
-DIFFERENCES WITH PACKER *lazy.nvim-differences-with-packer*
+cache.
-- **Plugin Spec**:
- - `setup` => `init`
- - `requires` => `dependencies`
- - `as` => `name`
- - `opt` => `lazy`
- - `run` => `build`
- - `lock` => `pin`
- - `module` is auto-loaded. No need to specify
+📂 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
+**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
+
-image
-