From 47dedb55fcd052b651b79b8c3981ba85e8a6e71a Mon Sep 17 00:00:00 2001 From: Evgeni Chasnovski Date: Mon, 9 Mar 2026 18:49:01 +0200 Subject: [PATCH] docs(pack): simpify `update()` docs, fix directory path #38194 Problem: Documentation of `vim.pack.update()` contains a lot of text inside nested list. This might be a bit confusing to parse for humans and definitely confusing to parse for neovim.io. The description of `vim.pack` directory is not correct for Windows. Solution: Move description of confirmation buffer in a separate "subsection". Use '"data" standard path' instead of '$XDG_DATA_HOME/nvim' when documenting directory. Also use `|standard-path|` tag to link to standard path section instead of `|stdpath()|`. --- runtime/doc/pack.txt | 62 ++++++++++++++++++++++------------------ runtime/lua/vim/pack.lua | 52 +++++++++++++++++---------------- 2 files changed, 61 insertions(+), 53 deletions(-) diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index 1c6658e9a8..6b9ec96cce 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -211,11 +211,12 @@ 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 -be part of 'packpath'. It usually is, but might not be in cases like |--clean| -or setting |$XDG_DATA_HOME| during startup. Plugin's subdirectory name matches -plugin's name in specification. It is assumed that all plugins in the -directory are managed exclusively by `vim.pack`. +`site/pack/core/opt` subdirectory of "data" |standard-path|. Subdirectory +`site` of "data" standard path needs to be part of 'packpath'. It usually is, +but might not be in cases like |--clean| or setting |$XDG_DATA_HOME| during +startup. Plugin's subdirectory name matches plugin's name in specification. It +is assumed that all plugins in the directory are managed exclusively by +`vim.pack`. Uses Git to manage plugins and requires present `git` executable. Target plugins should be Git repositories with versions as named tags following @@ -319,9 +320,9 @@ Unfreeze plugin to start receiving updates ~ Revert plugin after an update ~ • Revert the |vim.pack-lockfile| to the state before the update: • If Git tracked: `git checkout HEAD -- nvim-pack-lock.json` - • If not tracked: examine log file ("nvim-pack.log" at "log" |stdpath()|), - locate the revisions before the latest update, and (carefully) adjust - current lockfile to have those revisions. + • If not tracked: examine log file ("nvim-pack.log" at "log" + |standard-path|), locate the revisions before the latest update, and + (carefully) adjust current lockfile to have those revisions. • |:restart|. • `vim.pack.update({ 'plugin' }, { offline = true, target = 'lockfile' })`. Read and confirm. @@ -484,33 +485,38 @@ update({names}, {opts}) *vim.pack.update()* Update plugins • Download new changes from source. • Infer update info (current/target revisions, changelog, etc.). - • Depending on `force`: - • If `false`, show confirmation buffer. It lists data about all set to - update plugins. Pending changes starting with `>` will be applied - while the ones starting with `<` will be reverted. It has dedicated - buffer-local mappings: - • |]]| and |[[| to navigate through plugin sections. - Some features are provided via LSP: - • 'textDocument/documentSymbol' (`gO` via |lsp-defaults| or - |vim.lsp.buf.document_symbol()|) - show structure of the buffer. - • 'textDocument/hover' (`K` via |lsp-defaults| or - |vim.lsp.buf.hover()|) - show more information at cursor. Like - details of particular pending change or newer tag. - • 'textDocument/codeAction' (`gra` via |lsp-defaults| or - |vim.lsp.buf.code_action()|) - show code actions available for - "plugin at cursor". Like "delete" (if plugin is not active), - "update" or "skip updating" (if there are pending updates). - Execute |:write| to confirm update, execute |:quit| to discard the - update. - • If `true`, make updates right away. + • If `force` is `false` (default), show confirmation buffer. If `force` is + `true`, make updates right away. Notes: • Every actual update is logged in "nvim-pack.log" file inside "log" - |stdpath()|. + |standard-path|. • It doesn't update source's default branch if it has changed (like from `master` to `main`). To have `version = nil` point to a new default branch, re-install the plugin (|vim.pack.del()| + |vim.pack.add()|). + Confirmation buffer ~ + + The goal of the confirmation buffer is to show update details for the user + to read, confirm (execute |:write|) or deny (execute |:quit|) the update. + + Pending changes starting with `>` will be applied while the ones starting + with `<` will be reverted. + + There are convenience buffer-local mappings: + • |]]| and |[[| to navigate through plugin sections. + + Some features are provided via LSP: + • 'textDocument/documentSymbol' (`gO` via |lsp-defaults| or + |vim.lsp.buf.document_symbol()|) - show structure of the buffer. + • 'textDocument/hover' (`K` via |lsp-defaults| or |vim.lsp.buf.hover()|) - + show more information at cursor. Like details of particular pending + change or newer tag. + • 'textDocument/codeAction' (`gra` via |lsp-defaults| or + |vim.lsp.buf.code_action()|) - show code actions relevant for "plugin at + cursor". Like "delete" (if plugin is not active), "update" or "skip + updating" (if there are pending updates). + Parameters: ~ • {names} (`string[]?`) List of plugin names to update. Must be managed by |vim.pack|, not necessarily already added to current diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua index 0d01b5ab10..c59a9b410a 100644 --- a/runtime/lua/vim/pack.lua +++ b/runtime/lua/vim/pack.lua @@ -4,9 +4,9 @@ --- 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 ----be part of 'packpath'. It usually is, but might not be in cases like |--clean| or ----setting |$XDG_DATA_HOME| during startup. +---`site/pack/core/opt` subdirectory of "data" |standard-path|. Subdirectory `site` of "data" +---standard path needs to be part of 'packpath'. It usually is, but might not be +---in cases like |--clean| or setting |$XDG_DATA_HOME| during startup. ---Plugin's subdirectory name matches plugin's name in specification. ---It is assumed that all plugins in the directory are managed exclusively by `vim.pack`. --- @@ -123,7 +123,7 @@ --- ---- Revert the |vim.pack-lockfile| to the state before the update: --- - If Git tracked: `git checkout HEAD -- nvim-pack-lock.json` ---- - If not tracked: examine log file ("nvim-pack.log" at "log" |stdpath()|), +--- - If not tracked: examine log file ("nvim-pack.log" at "log" |standard-path|), --- locate the revisions before the latest update, and (carefully) adjust --- current lockfile to have those revisions. ---- |:restart|. @@ -1213,33 +1213,35 @@ end --- --- - Download new changes from source. --- - Infer update info (current/target revisions, changelog, etc.). ---- - Depending on `force`: ---- - If `false`, show confirmation buffer. It lists data about all set to ---- update plugins. Pending changes starting with `>` will be applied while ---- the ones starting with `<` will be reverted. ---- It has dedicated buffer-local mappings: ---- - |]]| and |[[| to navigate through plugin sections. ---- ---- Some features are provided via LSP: ---- - 'textDocument/documentSymbol' (`gO` via |lsp-defaults| ---- or |vim.lsp.buf.document_symbol()|) - show structure of the buffer. ---- - 'textDocument/hover' (`K` via |lsp-defaults| or |vim.lsp.buf.hover()|) - ---- show more information at cursor. Like details of particular pending ---- change or newer tag. ---- - 'textDocument/codeAction' (`gra` via |lsp-defaults| or |vim.lsp.buf.code_action()|) - ---- show code actions available for "plugin at cursor". ---- Like "delete" (if plugin is not active), "update" or "skip updating" ---- (if there are pending updates). ---- ---- Execute |:write| to confirm update, execute |:quit| to discard the update. ---- - If `true`, make updates right away. +--- - If `force` is `false` (default), show confirmation buffer. +--- If `force` is `true`, make updates right away. --- --- Notes: ---- - Every actual update is logged in "nvim-pack.log" file inside "log" |stdpath()|. +--- - Every actual update is logged in "nvim-pack.log" file inside "log" |standard-path|. --- - It doesn't update source's default branch if it has changed (like from `master` to `main`). --- To have `version = nil` point to a new default branch, re-install the plugin --- (|vim.pack.del()| + |vim.pack.add()|). --- +--- Confirmation buffer ~ +--- +--- The goal of the confirmation buffer is to show update details for the user to read, confirm +--- (execute |:write|) or deny (execute |:quit|) the update. +--- +--- Pending changes starting with `>` will be applied while the ones starting with `<` will be +--- reverted. +--- +--- There are convenience buffer-local mappings: +--- - |]]| and |[[| to navigate through plugin sections. +--- +--- Some features are provided via LSP: +--- - 'textDocument/documentSymbol' (`gO` via |lsp-defaults| or |vim.lsp.buf.document_symbol()|) - +--- show structure of the buffer. +--- - 'textDocument/hover' (`K` via |lsp-defaults| or |vim.lsp.buf.hover()|) - show more +--- information at cursor. Like details of particular pending change or newer tag. +--- - 'textDocument/codeAction' (`gra` via |lsp-defaults| or |vim.lsp.buf.code_action()|) - show +--- code actions relevant for "plugin at cursor". Like "delete" (if plugin is not active), +--- "update" or "skip updating" (if there are pending updates). +--- --- @param names? string[] List of plugin names to update. Must be managed --- by |vim.pack|, not necessarily already added to current session. --- Default: names of all plugins managed by |vim.pack|.