diff --git a/doc/lazy.nvim.txt b/doc/lazy.nvim.txt index 0ff1888..c9b3d98 100644 --- a/doc/lazy.nvim.txt +++ b/doc/lazy.nvim.txt @@ -111,30 +111,31 @@ It is recommended to run `:checkhealth lazy` after installation PLUGIN SPEC *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():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 │ -│**config** │fun(LazyPlugin) or true or table │config is executed when the plugin loads. You can also set to true or pass a table, that will be passed to require("plugin").setup(opts) │ -│**build** │fun(LazyPlugin) or string or a list of build commands │build is executed when a plugin is installed or updated. If it’s a string it will be ran as a shell command. When prefixed with : it is a Neovim command. You can also specify a list to executed multiple build commands │ -│**branch** │string? │Branch of the repository │ -│**tag** │string? │Tag of the repository │ -│**commit** │string? │Commit of the repository │ -│**version** │string? │Version to use from the repository. Full Semver ranges are supported │ -│**pin** │boolean? │When true, this plugin will not be included in updates │ -│**event** │string? or string[] │Lazy-load on event. Events can be specified as BufEnter or with a pattern like BufEnter .lua │ -│**cmd** │string? or string[] │Lazy-load on command │ -│**ft** │string? or string[] │Lazy-load on filetype │ -│**keys** │string? or string[] or LazyKeys[] │Lazy-load on key mapping │ -│**module** │false? │Do not automatically load this Lua module when it’s required somewhere │ -│**priority** │number? │Only useful for **start** plugins (lazy=false) to force loading certain plugins first. Default priority is 50. It’s recommended to set this to a high number for colorschemes. │ +│ Property │ Type │ Description │ +│[1] │string? │Short plugin url. Will be expanded using config.git.url_format │ +│**dir** │string? │A directory pointing to a local plugin │ +│**url** │string? │A custom git url where the plugin is hosted │ +│**name** │string? │A custom name for the plugin used for the local plugin directory and as the display name │ +│**dev** │boolean? │When true, a local plugin directory will be used instead. See config.dev │ +│**lazy** │boolean? │When true, the plugin will only be loaded when needed. Lazy-loaded plugins are automatically loaded when their Lua modules are required, or when one of the lazy-loading handlers triggers │ +│**enabled** │boolean? or fun():boolean │When false, or if the function returns false, then this plugin will not be included in the spec │ +│**cond** │boolean? or fun():boolean │When false, or if the function returns false, then this plugin will not be loaded. Useful to disable some plugins in vscode, or firenvim for example. │ +│**dependencies**│LazySpec[] │A list of plugin names or plugin specs that should be loaded when the plugin loads. Dependencies are always lazy-loaded unless specified otherwise. When specifying a name, make sure the plugin spec has been defined somewhere else. │ +│**init** │fun(LazyPlugin) │init functions are always executed during startup │ +│**config** │fun(LazyPlugin, opts:table) or true │config is executed when the plugin loads. You can also set it to true, to automatically run require("plugin").setup(opts). See also opts. │ +│**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() │ +│**build** │fun(LazyPlugin) or string or a list of build commands │build is executed when a plugin is installed or updated. If it’s a string it will be ran as a shell command. When prefixed with : it is a Neovim command. You can also specify a list to executed multiple build commands │ +│**branch** │string? │Branch of the repository │ +│**tag** │string? │Tag of the repository │ +│**commit** │string? │Commit of the repository │ +│**version** │string? │Version to use from the repository. Full Semver ranges are supported │ +│**pin** │boolean? │When true, this plugin will not be included in updates │ +│**event** │string? or string[] │Lazy-load on event. Events can be specified as BufEnter or with a pattern like BufEnter .lua │ +│**cmd** │string? or string[] │Lazy-load on command │ +│**ft** │string? or string[] │Lazy-load on filetype │ +│**keys** │string? or string[] or LazyKeys[] │Lazy-load on key mapping │ +│**module** │false? │Do not automatically load this Lua module when it’s required somewhere │ +│**priority** │number? │Only useful for **start** plugins (lazy=false) to force loading certain plugins first. Default priority is 50. It’s recommended to set this to a high number for colorschemes. │ LAZY LOADING ~ @@ -271,11 +272,11 @@ EXAMPLES ~ config = true, -- run require("neorg").setup() }, - -- or set a custom config: + -- or set custom options: { "nvim-neorg/neorg", ft = "norg", - config = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) + opts = { foo = "bar" }, -- run require("neorg").setup({foo = "bar"}) }, { @@ -724,6 +725,26 @@ For a real-life example, you can check LazyVim - 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"}}) +< + + +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 *lazy.nvim-migration-guide* PACKER.NVIM ~