commit 83f7d9851835d4ac5b92ddf689ad720914735712
parent 16a6559ec6e18d053f161755684656551a3c3b83
Author: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Thu, 23 Oct 2025 20:26:54 +0300
docs(pack): add plugin hooks example
Problem: No examples of how to use `PackChanged[Pre]` for plugin hooks.
Solution: Add examples of creating plugin hooks.
Diffstat:
2 files changed, 64 insertions(+), 11 deletions(-)
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -301,11 +301,37 @@ Available events to hook into ~
Each event populates the following |event-data| fields:
• `active` - whether plugin was added via |vim.pack.add()| to current session.
-• `kind` - one of "install" (install on disk), "update" (update existing
- plugin), "delete" (delete from disk).
+• `kind` - one of "install" (install on disk; before loading), "update"
+ (update already installed plugin; might be not loaded), "delete" (delete
+ from disk).
• `spec` - plugin's specification with defaults made explicit.
• `path` - full path to plugin's directory.
+These events can be used to execute plugin hooks. For example: >lua
+ local hooks = function(ev)
+ -- Use available |event-data|
+ local name, kind = ev.data.spec.name, ev.data.kind
+
+ -- Run build script after plugin's code has changed
+ if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+ vim.system({ 'make' }, { cwd = ev.data.path })
+ end
+
+ -- If action relies on code from the plugin (like user command or
+ -- Lua code), make sure to explicitly load it first
+ if name == 'plug-2' and kind == 'update' then
+ if not ev.data.active then
+ vim.cmd.packadd('plug-2')
+ end
+ vim.cmd('PlugTwoUpdate')
+ require('plug2').after_update()
+ end
+ end
+
+ -- If hooks need to run on install, run this before `vim.pack.add()`
+ vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
+<
+
*vim.pack.Spec*
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
@@ -91,17 +91,44 @@
---- Use |vim.pack.del()| with a list of plugin names to remove. Make sure their specs
---are not included in |vim.pack.add()| call in 'init.lua' or they will be reinstalled.
---
---- Available events to hook into ~
+---Available events to hook into ~
---
---- - [PackChangedPre]() - before trying to change plugin's state.
---- - [PackChanged]() - after plugin's state has changed.
+---- [PackChangedPre]() - before trying to change plugin's state.
+---- [PackChanged]() - after plugin's state has changed.
---
---- Each event populates the following |event-data| fields:
---- - `active` - whether plugin was added via |vim.pack.add()| to current session.
---- - `kind` - one of "install" (install on disk), "update" (update existing
---- plugin), "delete" (delete from disk).
---- - `spec` - plugin's specification with defaults made explicit.
---- - `path` - full path to plugin's directory.
+---Each event populates the following |event-data| fields:
+---- `active` - whether plugin was added via |vim.pack.add()| to current session.
+---- `kind` - one of "install" (install on disk; before loading),
+--- "update" (update already installed plugin; might be not loaded),
+--- "delete" (delete from disk).
+---- `spec` - plugin's specification with defaults made explicit.
+---- `path` - full path to plugin's directory.
+---
+--- These events can be used to execute plugin hooks. For example:
+---```lua
+---local hooks = function(ev)
+--- -- Use available |event-data|
+--- local name, kind = ev.data.spec.name, ev.data.kind
+---
+--- -- Run build script after plugin's code has changed
+--- if name == 'plug-1' and (kind == 'install' or kind == 'update') then
+--- vim.system({ 'make' }, { cwd = ev.data.path })
+--- end
+---
+--- -- If action relies on code from the plugin (like user command or
+--- -- Lua code), make sure to explicitly load it first
+--- if name == 'plug-2' and kind == 'update' then
+--- if not ev.data.active then
+--- vim.cmd.packadd('plug-2')
+--- end
+--- vim.cmd('PlugTwoUpdate')
+--- require('plug2').after_update()
+--- end
+---end
+---
+----- If hooks need to run on install, run this before `vim.pack.add()`
+---vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
+---```
local api = vim.api
local uv = vim.uv
