alex/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-01-04 10:26:42 +10:00
Code Issues Packages Projects Releases Wiki Activity

docs(pack): use more tags and add "Use shorter source" example

Browse Source
This commit is contained in:
Evgeni Chasnovski
2025-12-25 12:57:38 +02:00
parent 0353d33b00
commit c8ea8374c8
2 changed files with 55 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
runtime/doc/pack.txt
View File

@@ -230,9 +230,9 @@ plugins from the lockfile will be installed at once and at lockfile's revision
data for installed plugins is repaired (including after deleting whole file), data for installed plugins is repaired (including after deleting whole file),
but `version` fields will be missing for not yet added plugins. but `version` fields will be missing for not yet added plugins.
Example workflows ~ *vim.pack-examples*
Basic install and management: Basic install and management ~
• Add |vim.pack.add()| call(s) to 'init.lua': >lua • Add |vim.pack.add()| call(s) to 'init.lua': >lua
vim.pack.add({ vim.pack.add({
@@ -272,7 +272,23 @@ Basic install and management:
updates execute |:quit|. updates execute |:quit|.
• (Optionally) |:restart| to start using code from updated plugins. • (Optionally) |:restart| to start using code from updated plugins.
Switch plugin's version and/or source: 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.
Switch plugin's version and/or source ~
• Update 'init.lua' for plugin to have desired `version` and/or `src`. Let's • Update 'init.lua' for plugin to have desired `version` and/or `src`. Let's
say, the switch is for plugin named 'plugin1'. say, the switch is for plugin named 'plugin1'.
• |:restart|. The plugin's state on disk (revision and/or tracked source) is • |:restart|. The plugin's state on disk (revision and/or tracked source) is
@@ -282,17 +298,17 @@ Switch plugin's version and/or source:
`version` change in 'init.lua' as well or you will be prompted again next `version` change in 'init.lua' as well or you will be prompted again next
time you run |vim.pack.update()|. time you run |vim.pack.update()|.
Freeze plugin from being updated: Freeze plugin from being updated ~
• Update 'init.lua' for plugin to have `version` set to current revision. Get • 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`). it from |vim.pack-lockfile| (plugin's field `rev`; looks like `abc12345`).
• |:restart|. • |:restart|.
Unfreeze plugin to start receiving updates: Unfreeze plugin to start receiving updates ~
• Update 'init.lua' for plugin to have `version` set to whichever version you • Update 'init.lua' for plugin to have `version` set to whichever version you
want it to be updated. want it to be updated.
• |:restart|. • |:restart|.
Revert plugin after an update: Revert plugin after an update ~
• Locate plugin's revision at working state. For example: • Locate plugin's revision at working state. For example:
• If there is a previous version of |vim.pack-lockfile| (like from version • If there is a previous version of |vim.pack-lockfile| (like from version
control history), use it to get plugin's `rev` field. control history), use it to get plugin's `rev` field.
@@ -304,12 +320,12 @@ Revert plugin after an update:
state on disk follow target revision. |:restart|. state on disk follow target revision. |:restart|.
• When ready to deal with updating plugin, unfreeze it. • When ready to deal with updating plugin, unfreeze it.
Remove plugins from disk: Remove plugins from disk ~
• Use |vim.pack.del()| with a list of plugin names to remove. Make sure their • 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 specs are not included in |vim.pack.add()| call in 'init.lua' or they will
be reinstalled. be reinstalled.
Available events to hook into ~ *vim.pack-events*
• *PackChangedPre* - before trying to change plugin's state. • *PackChangedPre* - before trying to change plugin's state.
• *PackChanged* - after plugin's state has changed. • *PackChanged* - after plugin's state has changed.

39
runtime/lua/vim/pack.lua
View File

@@ -24,9 +24,9 @@
---(including after deleting whole file), but `version` fields will be missing ---(including after deleting whole file), but `version` fields will be missing
---for not yet added plugins. ---for not yet added plugins.
--- ---
---Example workflows ~ ---[vim.pack-examples]()
--- ---
---Basic install and management: ---Basic install and management ~
--- ---
---- Add |vim.pack.add()| call(s) to 'init.lua': ---- Add |vim.pack.add()| call(s) to 'init.lua':
---```lua ---```lua
@@ -70,7 +70,26 @@
--- To discard updates execute |:quit|. --- To discard updates execute |:quit|.
--- - (Optionally) |:restart| to start using code from updated plugins. --- - (Optionally) |:restart| to start using code from updated plugins.
--- ---
---Switch plugin's version and/or source: ---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.
---
---Switch plugin's version and/or source ~
---
---- Update 'init.lua' for plugin to have desired `version` and/or `src`. ---- Update 'init.lua' for plugin to have desired `version` and/or `src`.
--- Let's say, the switch is for plugin named 'plugin1'. --- Let's say, the switch is for plugin named 'plugin1'.
---- |:restart|. The plugin's state on disk (revision and/or tracked source) ---- |:restart|. The plugin's state on disk (revision and/or tracked source)
@@ -80,17 +99,20 @@
--- `version` change in 'init.lua' as well or you will be prompted again next time --- `version` change in 'init.lua' as well or you will be prompted again next time
--- you run |vim.pack.update()|. --- you run |vim.pack.update()|.
--- ---
---Freeze plugin from being updated: ---Freeze plugin from being updated ~
---
---- Update 'init.lua' for plugin to have `version` set to current revision. ---- 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`). ---Get it from |vim.pack-lockfile| (plugin's field `rev`; looks like `abc12345`).
---- |:restart|. ---- |:restart|.
--- ---
---Unfreeze plugin to start receiving updates: ---Unfreeze plugin to start receiving updates ~
---
---- Update 'init.lua' for plugin to have `version` set to whichever version ---- Update 'init.lua' for plugin to have `version` set to whichever version
---you want it to be updated. ---you want it to be updated.
---- |:restart|. ---- |:restart|.
--- ---
---Revert plugin after an update: ---Revert plugin after an update ~
---
---- Locate plugin's revision at working state. For example: ---- Locate plugin's revision at working state. For example:
--- - If there is a previous version of |vim.pack-lockfile| (like from version --- - If there is a previous version of |vim.pack-lockfile| (like from version
--- control history), use it to get plugin's `rev` field. --- control history), use it to get plugin's `rev` field.
@@ -102,11 +124,12 @@
--- state on disk follow target revision. |:restart|. --- state on disk follow target revision. |:restart|.
---- When ready to deal with updating plugin, unfreeze it. ---- When ready to deal with updating plugin, unfreeze it.
--- ---
---Remove plugins from disk: ---Remove plugins from disk ~
---
---- Use |vim.pack.del()| with a list of plugin names to remove. Make sure their specs ---- 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. ---are not included in |vim.pack.add()| call in 'init.lua' or they will be reinstalled.
--- ---
---Available events to hook into ~ ---[vim.pack-events]()
--- ---
---- [PackChangedPre]() - before trying to change plugin's state. ---- [PackChangedPre]() - before trying to change plugin's state.
---- [PackChanged]() - after plugin's state has changed. ---- [PackChanged]() - after plugin's state has changed.