neovim

commit 18e6ba90e25327dd8b34960902f3433cf00259dc
parent 2e533e364e2d52bcfe531d8ddd4a148d3f3bfed1
Author: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date:   Thu, 13 Nov 2025 15:49:17 +0200

docs(pack): add example workflow of how to revert after a bad update

Problem: No example workflow of how to revert after a bad update.

Solution: Add example workflow of how to revert after a bad update.

  In future this might be improved by utilizing other `vim.pack`
  features or via a dedicated function (like `vim.pack.restore()` that
  restores all installed plugins to a state from the lockfile).

Diffstat:
M
runtime/doc/pack.txt
 | 
12
++++++++++++
M
runtime/lua/vim/pack.lua
 | 
12
++++++++++++

2 files changed, 24 insertions(+), 0 deletions(-)
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -294,6 +294,18 @@ Unfreeze plugin to start receiving updates:
   want it to be updated.
 • |:restart|.
 
+Revert plugin after an update:
+• Locate plugin's revision at working state. For example:
+  • If there is a previous version of |vim.pack-lockfile| (like from version
+    control history), use it to get plugin's `rev` field.
+  • If there is a log file ("nvim-pack.log" at "log" |stdpath()|), open it and
+    navigate to latest updates (at the bottom). Locate lines about plugin
+    update details and use revision from "State before".
+• Freeze plugin to target revision (set `version` and |:restart|).
+• Run `vim.pack.update({ 'plugin-name' }, { force = true })` to make plugin
+  state on disk follow target revision. |:restart|.
+• When ready to deal with updating plugin, unfreeze it.
+
 Remove plugins from disk:
 • 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
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
@@ -91,6 +91,18 @@
 ---you want it to be updated.
 ---- |:restart|.
 ---
+---Revert plugin after an update:
+---- Locate plugin's revision at working state. For example:
+---    - If there is a previous version of |vim.pack-lockfile| (like from version
+---    control history), use it to get plugin's `rev` field.
+---    - If there is a log file ("nvim-pack.log" at "log" |stdpath()|), open it
+---      and navigate to latest updates (at the bottom). Locate lines about plugin
+---      update details and use revision from "State before".
+---- Freeze plugin to target revision (set `version` and |:restart|).
+---- Run `vim.pack.update({ 'plugin-name' }, { force = true })` to make plugin
+---  state on disk follow target revision. |:restart|.
+---- When ready to deal with updating plugin, unfreeze it.
+---
 ---Remove plugins from disk:
 ---- 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.