commit 538c945fdf0c1980369373a9534656f4b2836bbf
parent d7050d6e397f8916a38e8610ae8c2d8d75610fe4
Author: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Fri, 18 Jul 2025 17:39:23 +0300
docs(pack): move `vim.pack` documentation into a separate file
Diffstat:
3 files changed, 207 insertions(+), 188 deletions(-)
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -2536,192 +2536,6 @@ vim.loader.reset({path}) *vim.loader.reset()*
==============================================================================
-Lua module: vim.pack *vim.pack*
-
-WORK IN PROGRESS built-in plugin manager! Early testing of existing features
-is appreciated, but expect breaking changes without notice.
-
-Manages plugins only in a dedicated *vim.pack-directory* (see |packages|):
-`$XDG_DATA_HOME/nvim/site/pack/core/opt`. 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 of at least
-version 2.36. Target plugins should be Git repositories with versions as named
-tags following semver convention `v<major>.<minor>.<patch>`.
-
-Example workflows ~
-
-Basic install and management:
-• Add |vim.pack.add()| call(s) to 'init.lua': >lua
-
- vim.pack.add({
- -- Install "plugin1" and use default branch (usually `main` or `master`)
- 'https://github.com/user/plugin1',
-
- -- Same as above, but using a table (allows setting other options)
- { src = 'https://github.com/user/plugin1' },
-
- -- Specify plugin's name (here the plugin will be called "plugin2"
- -- instead of "generic-name")
- { src = 'https://github.com/user/generic-name', name = 'plugin2' },
-
- -- Specify version to follow during install and update
- {
- src = 'https://github.com/user/plugin3',
- -- Version constraint, see |vim.version.range()|
- version = vim.version.range('1.0'),
- },
- {
- src = 'https://github.com/user/plugin4',
- -- Git branch, tag, or commit hash
- version = 'main',
- },
- })
-
- -- Plugin's code can be used directly after `add()`
- plugin1 = require('plugin1')
-<
-• Restart Nvim (for example, with |:restart|). Plugins that were not yet
- installed will be available on disk in target state after `add()` call.
-• To update all plugins with new changes:
- • Execute |vim.pack.update()|. This will download updates from source and
- show confirmation buffer in a separate tabpage.
- • Review changes. To confirm all updates execute |:write|. To discard
- updates execute |:quit|.
-
-Switch plugin's version:
-• Update 'init.lua' for plugin to have desired `version`. Let's say, plugin
- named 'plugin1' has changed to `vim.version.range('*')`.
-• |:restart|. The plugin's actual state on disk is not yet changed.
-• Execute `vim.pack.update({ 'plugin1' })`.
-• Review changes and either confirm or discard them. If discarded, revert any
- changes in 'init.lua' as well or you will be prompted again next time you
- run |vim.pack.update()|.
-
-Freeze plugin from being updated:
-• Update 'init.lua' for plugin to have `version` set to current commit hash.
- You can get it by running `vim.pack.update({ 'plugin-name' })` and yanking
- the word describing current state (looks like `abc12345`).
-• |:restart|.
-
-Unfreeze plugin to start receiving updates:
-• Update 'init.lua' for plugin to have `version` set to whichever version you
- want it to be updated.
-• |:restart|.
-
-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.
-
-Available events to hook into ~
-• *PackChangedPre* - before trying to change plugin's state.
-• *PackChanged* - after plugin's state has changed.
-
-Each event populates the following |event-data| fields:
-• `kind` - one of "install" (install on disk), "update" (update existing
- plugin), "delete" (delete from disk).
-• `spec` - plugin's specification.
-• `path` - full path to plugin's directory.
-
-
-*vim.pack.Spec*
-
- Fields: ~
- • {src} (`string`) URI from which to install and pull updates. Any
- format supported by `git clone` is allowed.
- • {name}? (`string`) Name of plugin. Will be used as directory name.
- Default: `src` repository name.
- • {version}? (`string|vim.VersionRange`) Version to use for install and
- updates. Can be:
- • `nil` (no value, default) to use repository's default
- branch (usually `main` or `master`).
- • String to use specific branch, tag, or commit hash.
- • Output of |vim.version.range()| to install the
- greatest/last semver tag inside the version constraint.
-
-
-vim.pack.add({specs}, {opts}) *vim.pack.add()*
- Add plugin to current session
- • For each specification check that plugin exists on disk in
- |vim.pack-directory|:
- • If exists, do nothin in this step.
- • If doesn't exist, install it by downloading from `src` into `name`
- subdirectory (via `git clone`) and update state to match `version`
- (via `git checkout`).
- • For each plugin execute |:packadd| making them reachable by Nvim.
-
- Notes:
- • Installation is done in parallel, but waits for all to finish before
- continuing next code execution.
- • If plugin is already present on disk, there are no checks about its
- present state. The specified `version` can be not the one actually
- present on disk. Execute |vim.pack.update()| to synchronize.
- • Adding plugin second and more times during single session does nothing:
- only the data from the first adding is registered.
-
- Parameters: ~
- • {specs} (`(string|vim.pack.Spec)[]`) List of plugin specifications.
- String item is treated as `src`.
- • {opts} (`table?`) A table with the following fields:
- • {load}? (`boolean`) Load `plugin/` files and `ftdetect/`
- scripts. If `false`, works like `:packadd!`. Default
- `true`.
-
-vim.pack.del({names}) *vim.pack.del()*
- Remove plugins from disk
-
- Parameters: ~
- • {names} (`string[]`) List of plugin names to remove from disk. Must
- be managed by |vim.pack|, not necessarily already added to
- current session.
-
-vim.pack.get() *vim.pack.get()*
- Get data about all plugins managed by |vim.pack|
-
- Return: ~
- (`table[]`) A list of objects with the following fields:
- • {spec} (`vim.pack.SpecResolved`) A |vim.pack.Spec| with defaults
- made explicit.
- • {path} (`string`) Plugin's path on disk.
- • {active} (`boolean`) Whether plugin was added via |vim.pack.add()|
- to current session.
-
-vim.pack.update({names}, {opts}) *vim.pack.update()*
- Update plugins
- • Download new changes from source.
- • Infer update info (current/target state, 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 special
- in-process LSP server attached to provide more interactive features.
- Currently supported methods:
- • '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.
- Execute |:write| to confirm update, execute |:quit| to discard the
- update.
- • If `true`, make updates right away.
-
- Notes:
- • Every actual update is logged in "nvim-pack.log" file inside "log"
- |stdpath()|.
-
- Parameters: ~
- • {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 added to current
- session via |vim.pack.add()|.
- • {opts} (`table?`) A table with the following fields:
- • {force}? (`boolean`) Whether to skip confirmation and make
- updates immediately. Default `false`.
-
-
-==============================================================================
Lua module: vim.uri *vim.uri*
vim.uri_decode({str}) *vim.uri_decode()*
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -0,0 +1,196 @@
+*pack.txt* Nvim
+
+ NVIM REFERENCE MANUAL
+
+ Extending Nvim
+
+
+ Type |gO| to see the table of contents.
+
+==============================================================================
+Plugin manager *vim.pack*
+
+WORK IN PROGRESS built-in plugin manager! Early testing of existing features
+is appreciated, but expect breaking changes without notice.
+
+Manages plugins only in a dedicated *vim.pack-directory* (see |packages|):
+`$XDG_DATA_HOME/nvim/site/pack/core/opt`. 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 of at least
+version 2.36. Target plugins should be Git repositories with versions as named
+tags following semver convention `v<major>.<minor>.<patch>`.
+
+Example workflows ~
+
+Basic install and management:
+• Add |vim.pack.add()| call(s) to 'init.lua': >lua
+
+ vim.pack.add({
+ -- Install "plugin1" and use default branch (usually `main` or `master`)
+ 'https://github.com/user/plugin1',
+
+ -- Same as above, but using a table (allows setting other options)
+ { src = 'https://github.com/user/plugin1' },
+
+ -- Specify plugin's name (here the plugin will be called "plugin2"
+ -- instead of "generic-name")
+ { src = 'https://github.com/user/generic-name', name = 'plugin2' },
+
+ -- Specify version to follow during install and update
+ {
+ src = 'https://github.com/user/plugin3',
+ -- Version constraint, see |vim.version.range()|
+ version = vim.version.range('1.0'),
+ },
+ {
+ src = 'https://github.com/user/plugin4',
+ -- Git branch, tag, or commit hash
+ version = 'main',
+ },
+ })
+
+ -- Plugin's code can be used directly after `add()`
+ plugin1 = require('plugin1')
+<
+• Restart Nvim (for example, with |:restart|). Plugins that were not yet
+ installed will be available on disk in target state after `add()` call.
+• To update all plugins with new changes:
+ • Execute |vim.pack.update()|. This will download updates from source and
+ show confirmation buffer in a separate tabpage.
+ • Review changes. To confirm all updates execute |:write|. To discard
+ updates execute |:quit|.
+
+Switch plugin's version:
+• Update 'init.lua' for plugin to have desired `version`. Let's say, plugin
+ named 'plugin1' has changed to `vim.version.range('*')`.
+• |:restart|. The plugin's actual state on disk is not yet changed.
+• Execute `vim.pack.update({ 'plugin1' })`.
+• Review changes and either confirm or discard them. If discarded, revert any
+ changes in 'init.lua' as well or you will be prompted again next time you
+ run |vim.pack.update()|.
+
+Freeze plugin from being updated:
+• Update 'init.lua' for plugin to have `version` set to current commit hash.
+ You can get it by running `vim.pack.update({ 'plugin-name' })` and yanking
+ the word describing current state (looks like `abc12345`).
+• |:restart|.
+
+Unfreeze plugin to start receiving updates:
+• Update 'init.lua' for plugin to have `version` set to whichever version you
+ want it to be updated.
+• |:restart|.
+
+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.
+
+Available events to hook into ~
+• *PackChangedPre* - before trying to change plugin's state.
+• *PackChanged* - after plugin's state has changed.
+
+Each event populates the following |event-data| fields:
+• `kind` - one of "install" (install on disk), "update" (update existing
+ plugin), "delete" (delete from disk).
+• `spec` - plugin's specification.
+• `path` - full path to plugin's directory.
+
+
+*vim.pack.Spec*
+
+ Fields: ~
+ • {src} (`string`) URI from which to install and pull updates. Any
+ format supported by `git clone` is allowed.
+ • {name}? (`string`) Name of plugin. Will be used as directory name.
+ Default: `src` repository name.
+ • {version}? (`string|vim.VersionRange`) Version to use for install and
+ updates. Can be:
+ • `nil` (no value, default) to use repository's default
+ branch (usually `main` or `master`).
+ • String to use specific branch, tag, or commit hash.
+ • Output of |vim.version.range()| to install the
+ greatest/last semver tag inside the version constraint.
+
+
+add({specs}, {opts}) *vim.pack.add()*
+ Add plugin to current session
+ • For each specification check that plugin exists on disk in
+ |vim.pack-directory|:
+ • If exists, do nothin in this step.
+ • If doesn't exist, install it by downloading from `src` into `name`
+ subdirectory (via `git clone`) and update state to match `version`
+ (via `git checkout`).
+ • For each plugin execute |:packadd| making them reachable by Nvim.
+
+ Notes:
+ • Installation is done in parallel, but waits for all to finish before
+ continuing next code execution.
+ • If plugin is already present on disk, there are no checks about its
+ present state. The specified `version` can be not the one actually
+ present on disk. Execute |vim.pack.update()| to synchronize.
+ • Adding plugin second and more times during single session does nothing:
+ only the data from the first adding is registered.
+
+ Parameters: ~
+ • {specs} (`(string|vim.pack.Spec)[]`) List of plugin specifications.
+ String item is treated as `src`.
+ • {opts} (`table?`) A table with the following fields:
+ • {load}? (`boolean`) Load `plugin/` files and `ftdetect/`
+ scripts. If `false`, works like `:packadd!`. Default
+ `true`.
+
+del({names}) *vim.pack.del()*
+ Remove plugins from disk
+
+ Parameters: ~
+ • {names} (`string[]`) List of plugin names to remove from disk. Must
+ be managed by |vim.pack|, not necessarily already added to
+ current session.
+
+get() *vim.pack.get()*
+ Get data about all plugins managed by |vim.pack|
+
+ Return: ~
+ (`table[]`) A list of objects with the following fields:
+ • {spec} (`vim.pack.SpecResolved`) A |vim.pack.Spec| with defaults
+ made explicit.
+ • {path} (`string`) Plugin's path on disk.
+ • {active} (`boolean`) Whether plugin was added via |vim.pack.add()|
+ to current session.
+
+update({names}, {opts}) *vim.pack.update()*
+ Update plugins
+ • Download new changes from source.
+ • Infer update info (current/target state, 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 special
+ in-process LSP server attached to provide more interactive features.
+ Currently supported methods:
+ • '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.
+ Execute |:write| to confirm update, execute |:quit| to discard the
+ update.
+ • If `true`, make updates right away.
+
+ Notes:
+ • Every actual update is logged in "nvim-pack.log" file inside "log"
+ |stdpath()|.
+
+ Parameters: ~
+ • {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 added to current
+ session via |vim.pack.add()|.
+ • {opts} (`table?`) A table with the following fields:
+ • {force}? (`boolean`) Whether to skip confirmation and make
+ updates immediately. Default `false`.
+
+
+ vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
diff --git a/src/gen/gen_vimdoc.lua b/src/gen/gen_vimdoc.lua
@@ -144,7 +144,6 @@ local config = {
'_inspector.lua',
'shared.lua',
'loader.lua',
- 'pack.lua',
'uri.lua',
'ui.lua',
'_extui.lua',
@@ -169,7 +168,6 @@ local config = {
'runtime/lua/vim/_options.lua',
'runtime/lua/vim/shared.lua',
'runtime/lua/vim/loader.lua',
- 'runtime/lua/vim/pack.lua',
'runtime/lua/vim/uri.lua',
'runtime/lua/vim/ui.lua',
'runtime/lua/vim/_extui.lua',
@@ -403,6 +401,17 @@ local config = {
return { 'vim.health', 'health' }
end,
},
+ pack = {
+ filename = 'pack.txt',
+ files = { 'runtime/lua/vim/pack.lua' },
+ section_order = { 'pack.lua' },
+ section_fmt = function(_name)
+ return 'Plugin manager'
+ end,
+ helptag_fmt = function()
+ return { 'vim.pack' }
+ end,
+ },
}
--- @param ty string
