From 3e83f7bec7789fe584cd939e4a60f270a4c626ff Mon Sep 17 00:00:00 2001
From: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Thu, 8 Jan 2026 04:43:55 +0200
Subject: [PATCH] docs: drop vim.pack WIP note, add example code #37229

---
 runtime/doc/pack.txt     | 13 ++++++++++---
 runtime/lua/vim/pack.lua | 14 +++++++++++---
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
index 9c2a8da109..96809efe42 100644
--- a/runtime/doc/pack.txt
+++ b/runtime/doc/pack.txt
@@ -207,8 +207,8 @@ sourcing the plugins.
 ==============================================================================
 Plugin manager                                                      *vim.pack*
 
-WORK IN PROGRESS built-in plugin manager! Early testing of existing features
-is appreciated, but expect breaking changes without notice.
+Install, update, and delete external plugins. WARNING: It is still considered
+experimental, yet should be stable enough for daily use.
 
 Manages plugins only in a dedicated *vim.pack-directory* (see |packages|):
 `$XDG_DATA_HOME/nvim/site/pack/core/opt`. `$XDG_DATA_HOME/nvim/site` needs to
@@ -342,7 +342,13 @@ Remove plugins from disk ~
 • Remove plugin specs from |vim.pack.add()| calls in 'init.lua' or they will
   be reinstalled later.
 • |:restart|.
-• Use |vim.pack.del()| with a list of plugin names to remove.
+• Use |vim.pack.del()| with a list of plugin names to remove. Use
+  |vim.pack.get()| to get all non-active plugins: >lua
+    vim.iter(vim.pack.get())
+     :filter(function(x) return not x.active end)
+     :map(function(x) return x.spec.name end)
+     :totable()
+<
 
                                                              *vim.pack-events*
 • *PackChangedPre* - before trying to change plugin's state.
@@ -363,6 +369,7 @@ These events can be used to execute plugin hooks. For example: >lua
 
       -- Run build script after plugin's code has changed
       if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+        -- Append `:wait()` if you need synchronous execution
         vim.system({ 'make' }, { cwd = ev.data.path })
       end
 
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
index a2c19b4a5c..13a97fa334 100644
--- a/runtime/lua/vim/pack.lua
+++ b/runtime/lua/vim/pack.lua
@@ -1,7 +1,7 @@
 --- @brief
 ---
----WORK IN PROGRESS built-in plugin manager! Early testing of existing features
----is appreciated, but expect breaking changes without notice.
+--- Install, update, and delete external plugins. WARNING: It is still considered
+--- experimental, yet should be stable enough for daily use.
 ---
 ---Manages plugins only in a dedicated [vim.pack-directory]() (see |packages|):
 ---`$XDG_DATA_HOME/nvim/site/pack/core/opt`. `$XDG_DATA_HOME/nvim/site` needs to
@@ -149,7 +149,14 @@
 ---- Remove plugin specs from |vim.pack.add()| calls in 'init.lua' or they will be
 ---  reinstalled later.
 ---- |:restart|.
----- Use |vim.pack.del()| with a list of plugin names to remove.
+---- Use |vim.pack.del()| with a list of plugin names to remove. Use |vim.pack.get()|
+---  to get all non-active plugins:
+---```lua
+---vim.iter(vim.pack.get())
+---  :filter(function(x) return not x.active end)
+---  :map(function(x) return x.spec.name end)
+---  :totable()
+---```
 ---
 ---[vim.pack-events]()
 ---
@@ -172,6 +179,7 @@
 ---
 ---   -- Run build script after plugin's code has changed
 ---   if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+---     -- Append `:wait()` if you need synchronous execution
 ---     vim.system({ 'make' }, { cwd = ev.data.path })
 ---   end
 ---