From c8ea8374c8a8fbc5893cfadde6954ea206631049 Mon Sep 17 00:00:00 2001 From: Evgeni Chasnovski Date: Thu, 25 Dec 2025 12:57:38 +0200 Subject: [PATCH] docs(pack): use more tags and add "Use shorter source" example --- runtime/doc/pack.txt | 32 ++++++++++++++++++++++++-------- runtime/lua/vim/pack.lua | 39 +++++++++++++++++++++++++++++++-------- 2 files changed, 55 insertions(+), 16 deletions(-) diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt index d15754b56e..eaac5d7b0b 100644 --- a/runtime/doc/pack.txt +++ b/runtime/doc/pack.txt @@ -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), 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 vim.pack.add({ @@ -272,7 +272,23 @@ Basic install and management: updates execute |:quit|. • (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 say, the switch is for plugin named 'plugin1'. • |: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 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 it from |vim.pack-lockfile| (plugin's field `rev`; looks like `abc12345`). • |: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 want it to be updated. • |:restart|. -Revert plugin after an update: +Revert plugin after an update ~ • Locate plugin's revision at working state. For example: • If there is a previous version of |vim.pack-lockfile| (like from version 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|. • 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 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. • *PackChanged* - after plugin's state has changed. diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua index 660745e120..736e78335a 100644 --- a/runtime/lua/vim/pack.lua +++ b/runtime/lua/vim/pack.lua @@ -24,9 +24,9 @@ ---(including after deleting whole file), 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 @@ -70,7 +70,26 @@ --- To discard updates execute |:quit|. --- - (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 say, the switch is for plugin named 'plugin1'. ---- |: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 --- 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 it from |vim.pack-lockfile| (plugin's field `rev`; looks like `abc12345`). ---- |: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 want it to be updated. ---- |:restart|. --- ----Revert plugin after an update: +---Revert plugin after an update ~ +--- ---- Locate plugin's revision at working state. For example: --- - If there is a previous version of |vim.pack-lockfile| (like from version --- control history), use it to get plugin's `rev` field. @@ -102,11 +124,12 @@ --- state on disk follow target revision. |:restart|. ---- 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 ---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. ---- [PackChanged]() - after plugin's state has changed.