From b0aa5348d8c5547a23f276251fcc3aa676f41d27 Mon Sep 17 00:00:00 2001
From: Folke Lemaitre <folke.lemaitre@gmail.com>
Date: Tue, 23 May 2023 08:57:53 +0200
Subject: [PATCH] docs: added docs on optional

---
 README.md                |  1 +
 lua/lazy/core/plugin.lua | 23 ++++++++++++++---------
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7292e4a..9ce2c59 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,7 @@ require("lazy").setup({
 | **keys**         | `string?` or `string[]` or `LazyKeys[]` or `fun(self:LazyPlugin, keys:string[]):(string \| 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.                                                                                                                                                      |
+| **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
 
diff --git a/lua/lazy/core/plugin.lua b/lua/lazy/core/plugin.lua
index 00e5ecf..76b245d 100644
--- a/lua/lazy/core/plugin.lua
+++ b/lua/lazy/core/plugin.lua
@@ -12,16 +12,19 @@ M.loading = false
 ---@field modules string[]
 ---@field notifs {msg:string, level:number, file?:string}[]
 ---@field importing? string
+---@field optional? boolean
 local Spec = {}
 M.Spec = Spec
 
 ---@param spec? LazySpec
-function Spec.new(spec)
+---@param opts? {optional?:boolean}
+function Spec.new(spec, opts)
   local self = setmetatable({}, { __index = Spec })
   self.plugins = {}
   self.disabled = {}
   self.modules = {}
   self.notifs = {}
+  self.optional = opts and opts.optional
   if spec then
     self:parse(spec)
   end
@@ -141,15 +144,17 @@ function Spec:warn(msg)
 end
 
 function Spec:fix_disabled()
-  ---@param plugin LazyPlugin
-  local function all_optional(plugin)
-    return (not plugin) or (rawget(plugin, "optional") and all_optional(plugin._.super))
-  end
+  if not self.optional then
+    ---@param plugin LazyPlugin
+    local function all_optional(plugin)
+      return (not plugin) or (rawget(plugin, "optional") and all_optional(plugin._.super))
+    end
 
-  -- handle optional plugins
-  for _, plugin in pairs(self.plugins) do
-    if plugin.optional and all_optional(plugin) then
-      self.plugins[plugin.name] = nil
+    -- handle optional plugins
+    for _, plugin in pairs(self.plugins) do
+      if plugin.optional and all_optional(plugin) then
+        self.plugins[plugin.name] = nil
+      end
     end
   end