mirror of
https://github.com/neovim/neovim.git
synced 2025-09-05 19:08:15 +00:00
docs(pack): move vim.pack documentation into a separate file
This commit is contained in:
Evgeni Chasnovski
@@ -2535,192 +2535,6 @@ vim.loader.reset({path}) *vim.loader.reset()*
|
||||
• {path} (`string?`) path to 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*
|
||||
|
||||
|
||||
196
runtime/doc/pack.txt
Normal file
196
runtime/doc/pack.txt
Normal file
@@ -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:
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user