zuqini · Oct 30, 2026 · Oct 25, 2026 · Oct 26, 2026 · Oct 29, 2026 · Oct 30, 2026
diff --git a/doc/zpack.txt b/doc/zpack.txt
@@ -612,6 +612,7 @@ parent's lazy trigger fires.
       -- Plugin configuration
       opts = {},                            -- Options passed to setup()
       -- opts = function(plugin, opts) return {} end,
+      opts_extend = { "ensure_installed" }, -- Concatenate these opts lists
 
       -- Lifecycle hooks
       init = function(plugin) end,          -- Runs before load
@@ -706,7 +707,10 @@ dependencies    (string|string[]|zpack.Spec|zpack.Spec[], optional)
                 Can be a string (a `[1]` value, see |zpack-Spec|), array
                 of strings, inline spec, or array of specs. Dependency
                 specs can have their own configuration (opts, config, etc.)
-                and nested dependencies.
+                and nested dependencies. When the parent is disabled or
+                skipped as `optional`, its dependency specs are dropped with
+                it (lazy.nvim parity), including their configuration of a
+                plugin that other specs keep enabled.
 
                                                          *zpack-Spec.enabled*
 enabled         (boolean|function, optional)
@@ -748,6 +752,52 @@ opts            (table|function(plugin, opts), optional)
                 `opts` is passed as the second argument, but you are
                 responsible for calling `setup()` yourself.
 
+                Each opts function, `config` and `setup()` get their own copy
+                of the plain tables in opts, so editing opts in place never
+                reaches your specs. Tables with a metatable (other than
+                |vim.empty_dict()|'s) are not copied.
+
+                                                     *zpack-Spec.opts_extend*
+opts_extend     (string|string[], optional)
+                Keys in `opts` whose lists get appended to instead of
+                replaced when several specs for the same plugin set `opts`.
+                Use dots for nested keys, e.g. `"sources.default"`.
+                Duplicates are kept, and nil holes in a list are dropped
+                when specs merge. A table with named keys at that path,
+                such as which-key's `{ mode = 'v', { ... } }`, is appended
+                as one entry, so its keys only apply to its own entries.
+                Two dicts at that path deep-merge as usual.
+
+                `opts_extend` from all specs of the plugin is combined, so
+                it only needs to be set on one of them, and no spec can
+                turn it off. To replace an extended list, use function-form
+                opts, e.g. `function(_, o) o.ensure_installed = { 'x' } end`.
+                Lists are appended in merge order: specs pulled in as
+                `dependencies` first, then top-level specs in import order.
+                Specs listed under the `dependencies` of a plugin that is
+                disabled or skipped as `optional` are left out, as in
+                lazy.nvim. lazy.nvim differs:
+                - Each spec uses the nearest `opts_extend` at or before it.
+                  A spec with none in effect replaces the lists before it,
+                  so of the lists set before the first `opts_extend`, only
+                  the last is kept, and a later `opts_extend` that leaves a
+                  key out stops that key from appending.
+                - It keeps only the list entries of a table at that path,
+                  so named keys are dropped and a dict there becomes an
+                  empty list.
+                - It appends in import order, without putting
+                  `dependencies` specs first.
+>lua
+                -- plugins/treesitter.lua
+                { 'nvim-treesitter/nvim-treesitter',
+                  opts_extend = { 'ensure_installed' },
+                  opts = { ensure_installed = { 'bash', 'c' } } }
+                -- plugins/rust.lua
+                { 'nvim-treesitter/nvim-treesitter',
+                  opts = { ensure_installed = { 'rust' } } }
+                -- ensure_installed ends up with bash, c and rust
+<
+
                                                             *zpack-Spec.init*
 init            (function(plugin), optional)
                 Runs before the plugin loads. Receives |zpack.Plugin|.

diff --git a/docs/spec.md b/docs/spec.md
@@ -28,6 +28,7 @@
   -- Plugin configuration
   opts = {},                            -- Options passed to setup(), triggers auto-setup
   -- opts = function(plugin, opts) return {} end, -- Can also be a function
+  opts_extend = { "ensure_installed" }, -- Opts keys whose lists are appended across specs, not replaced
 
   -- Lifecycle hooks
   init = function(plugin) end,          -- Runs before plugin loads, useful for certain vim plugins

diff --git a/docs/tips.md b/docs/tips.md
@@ -17,6 +17,7 @@ Most of your lazy.nvim plugin specs will work as-is with zpack. However, zpack f
 - **profiling**: Use `nvim --startuptime startuptime.log`. Also refer to example [Neovim Profiler script](https://gist.github.com/zuqini/35993710f81983fbfa6baca67bdb32ed)
 - **default lazy plugins**: lazy.nvim's community specs silently default top-level specs for utility libraries like `plenary.nvim` to `lazy = true`, even without lazy triggers or a lazy parent. zpack respects your specs as-written, so set `lazy = true` explicitly on such specs if you want the same default — or set `defaults.lazy = true` in [`setup()`](../README.md#configurations) to apply it to every spec
 - **`enabled` vs `cond`**: lazy.nvim collapses both to a single "disabled" state. zpack splits them: `enabled = false` skips install entirely (the plugin is never cloned), while `cond = false` installs the plugin but skips its load (so it still shows up under `vim.pack`'s data dir). Use `enabled` when you want lazy.nvim's "don't install at all" behavior
+- **`opts_extend`**: in lazy.nvim each spec uses the nearest `opts_extend` at or before it, and a spec with none in effect replaces the lists before it, so of the lists set before the first `opts_extend` only the last is kept, and a later `opts_extend` that leaves a key out stops that key from appending. lazy.nvim also keeps only the list entries of a table at an `opts_extend` key, dropping its named keys. zpack combines `opts_extend` from all specs of a plugin, so it can be set on any of them, and appends a table with named keys (such as which-key's `{ mode = 'v', ... }`) as one entry. zpack appends `dependencies` specs' lists before top-level ones, while lazy.nvim appends in import order, so with plain lists the two match when only the plugin's first spec sets `opts_extend` (LazyVim does this) and no `dependencies` entry adds to the list
 
 ## Gotchas
 

diff --git a/lua/zpack/import.lua b/lua/zpack/import.lua
@@ -239,6 +239,8 @@ local register_dependencies = function(spec, src, ctx)
         state.reverse_dependency_graph[dep_src] = state.reverse_dependency_graph[dep_src] or {}
         state.reverse_dependency_graph[dep_src][src] = true
       end
+      dep_spec._parent_specs = dep_spec._parent_specs or {}
+      dep_spec._parent_specs[spec] = true
       M.import_specs(dep_spec, dep_ctx)
     end
   end