Merge #37617 from echasnovski/pack-clearer-lockfile-sync

runtime/doc/pack.txt

@@ -226,9 +226,11 @@ located at `$XDG_CONFIG_HOME/nvim/nvim-pack-lock.json`. It is a JSON file that
 is used to persistently track data about plugins. For a more robust config
 treat lockfile like its part: put under version control, etc. In this case all
 plugins from the lockfile will be installed at once and at lockfile's revision
-(instead of inferring from `version`). Should not be edited by hand. Corrupted
-data for installed plugins is repaired (including after deleting whole file),
-but `version` fields will be missing for not yet added plugins.
+(instead of inferring from `version`). This is done on the very first
+`vim.pack` function call to ensure that lockfile is aligned with what is
+actually on the disk. Lockfile should not be edited by hand. Corrupted data
+for installed plugins is repaired (including after deleting whole file), but
+`version` fields will be missing for not yet added plugins.
 
                                                            *vim.pack-examples*
 
@@ -351,6 +353,8 @@ Remove plugins from disk ~
 <
 
                                                              *vim.pack-events*
+
+Performing actions via `vim.pack` functions can trigger these events:
 • *PackChangedPre* - before trying to change plugin's state.
 • *PackChanged* - after plugin's state has changed.
 
@@ -385,6 +389,7 @@ These events can be used to execute plugin hooks. For example: >lua
     end
 
     -- If hooks need to run on install, run this before `vim.pack.add()`
+    -- To act on install from lockfile, run before very first `vim.pack.add()`
     vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
 <
 

runtime/lua/vim/pack.lua

@@ -18,9 +18,10 @@
 ---located at `$XDG_CONFIG_HOME/nvim/nvim-pack-lock.json`. It is a JSON file that
 ---is used to persistently track data about plugins.
 ---For a more robust config treat lockfile like its part: put under version control, etc.
----In this case all plugins from the lockfile will be installed at once and
----at lockfile's revision (instead of inferring from `version`).
----Should not be edited by hand. Corrupted data for installed plugins is repaired
+---In this case all plugins from the lockfile will be installed at once and at lockfile's revision
+---(instead of inferring from `version`). This is done on the very first `vim.pack` function call
+---to ensure that lockfile is aligned with what is actually on the disk.
+---Lockfile should not be edited by hand. Corrupted data for installed plugins is repaired
 ---(including after deleting whole file), but `version` fields will be missing
 ---for not yet added plugins.
 ---
@@ -160,6 +161,7 @@
 ---
 ---[vim.pack-events]()
 ---
+---Performing actions via `vim.pack` functions can trigger these events:
 ---- [PackChangedPre]() - before trying to change plugin's state.
 ---- [PackChanged]() - after plugin's state has changed.
 ---
@@ -195,6 +197,7 @@
 ---end
 ---
 ----- If hooks need to run on install, run this before `vim.pack.add()`
+----- To act on install from lockfile, run before very first `vim.pack.add()`
 ---vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })
 ---```
 

test/functional/plugin/pack_spec.lua

@@ -612,6 +612,7 @@ describe('vim.pack', function()
       -- Mock clean initial install, but with lockfile present
       vim.fs.rm(pack_get_dir(), { force = true, recursive = true })
       n.clear()
+      watch_events({ 'PackChangedPre', 'PackChanged' })
 
       local basic_rev = git_get_hash('feat-branch', 'basic')
       local defbranch_rev = git_get_hash('HEAD', 'defbranch')
@@ -637,6 +638,17 @@ describe('vim.pack', function()
       eq(true, pack_exists('defbranch'))
       eq(false, exec_lua('return pcall(require, "defbranch")'))
 
+      -- Should trigger `kind=install` events
+      local log = exec_lua('return _G.event_log')
+      local find_event = make_find_packchanged(log)
+      local installpre_basic = find_event('Pre', 'install', 'basic', 'feat-branch', false)
+      local installpre_defbranch = find_event('Pre', 'install', 'defbranch', nil, false)
+      local install_basic = find_event('', 'install', 'basic', 'feat-branch', false)
+      local install_defbranch = find_event('', 'install', 'defbranch', nil, false)
+      eq(4, #log)
+      eq(true, installpre_basic < install_basic)
+      eq(true, installpre_defbranch < install_defbranch)
+
       -- Running `update()` should still update to use `main`
       exec_lua(function()
         vim.pack.update({ 'basic' }, { force = true })