path: root/runtime/lua/vim/pack.lua

--- @brief
---
--- 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|):
---`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 semver convention `v<major>.<minor>.<patch>` (with or without `v` prefix).
---Like `v1.2.0` or `1.2.0`, but not `1.2` or `v1`.
---
---The latest state of all managed plugins is stored inside a [vim.pack-lockfile]()
---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`). 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]()
---
---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 after `add()` call. Their revision is
---taken from |vim.pack-lockfile| (if present) or inferred from the `version`.
---
---- 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|.
---    - (Optionally) |:restart| to start using code from updated plugins.
---
---Use shorter source ~
---
--- Create custom Lua helpers:
---
---```lua
---
---local gh = function(x) return 'https://github.com/' .. x end
---local cb = function(x) return 'https://codeberg.org/' .. x end
---vim.pack.add({ gh('user/plugin1'), cb('user/plugin2') })
---```
---
---Another approach is to utilize Git's `insteadOf` configuration:
---- `git config --global url."https://github.com/".insteadOf "gh:"`
---- `git config --global url."https://codeberg.org/".insteadOf "cb:"`
---- In 'init.lua': `vim.pack.add({ 'gh:user/plugin1', 'cb:user/plugin2' })`.
---  These sources will be used verbatim in |vim.pack-lockfile|, so reusing
---  the config on different machine will require the same Git configuration.
---
---Explore installed plugins ~
---
---- `vim.pack.update(nil, { offline = true })`
---- Navigate between plugins with `[[` and `]]`. List them with `gO`
---  (|vim.lsp.buf.document_symbol()|).
---
---Switch plugin's version and/or source ~
---
---- Update 'init.lua' for plugin to have desired `version` and/or `src`.
---  Let's say, the switch is for plugin named 'plugin1'.
---- |:restart|. The plugin's state on disk (revision and/or tracked source)
---  is not yet changed. Only plugin's `version` in |vim.pack-lockfile| is updated.
---- Execute `vim.pack.update({ 'plugin1' })`. The plugin's source is updated.
---  If only switching version, use `{ offline = true }` option table.
---- Review changes and either confirm or discard them. If discarded, revert
---  `version` change 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 revision.
---Get it from |vim.pack-lockfile| (plugin's field `rev`; looks like `abc12345`).
---- |:restart|.
---
---Unfreeze plugin to start receiving updates ~
---
---- Update 'init.l