Pack

Nvim:help pages,generated fromsource using thetree-sitter-vimdoc parser.

Extending Nvim

Using Vim packages

A Vim "package" is a directory that containsplugins. Compared to normalplugins, a package can...

be downloaded as an archive and unpacked in its own directory, so the files are not mixed with files of other plugins.

be a git, mercurial, etc. repository, thus easy to update.

contain multiple plugins that depend on each other.

contain plugins that are automatically loaded on startup ("start" packages, located in "pack/*/start/*") and ones that are only loaded when needed with:packadd ("opt" packages, located in "pack/*/opt/*").

runtime-search-path
Nvim searches for:runtime files in:

1. all paths in'runtimepath'

2. all "pack/*/start/*" dirs

Note that the "pack/*/start/*" paths are not explicitly included in'runtimepath', so they will not be reported by ":set rtp" or "echo &rtp".Scripts can usenvim_list_runtime_paths() to list all used directories, andnvim_get_runtime_file() to query for specific files or sub-folders withinthe runtime path. Example:

" List all runtime dirs and packages with Lua paths.:echo nvim_get_runtime_file("lua/", v:true)

Using a package and loading automatically

Let's assume your Nvim files are in "~/.local/share/nvim/site" and you want toadd a package from a zip archive "/tmp/foopack.zip":

% mkdir -p ~/.local/share/nvim/site/pack/foo% cd ~/.local/share/nvim/site/pack/foo% unzip /tmp/foopack.zip

The directory name "foo" is arbitrary, you can pick anything you like.

You would now have these files under ~/.local/share/nvim/site:

pack/foo/README.txtpack/foo/start/foobar/plugin/foo.vimpack/foo/start/foobar/syntax/some.vimpack/foo/opt/foodebug/plugin/debugger.vim

On startup after processing yourconfig, Nvim scans all directories in'packpath' for plugins in "pack/*/start/*", then loads the plugins.

To allow for calling into package functionality while parsing yourvimrc,:colorscheme andautoload will both automatically search under'packpath'as well in addition to'runtimepath'. See the documentation for each fordetails.

In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and loadit.

If the "foobar" plugin kicks in and sets the'filetype' to "some", Nvim willfind the syntax/some.vim file, because its directory is in the runtime searchpath.

Nvim will also load ftdetect files, if there are any.

Note that the files under "pack/foo/opt" are not loaded automatically, onlythe ones under "pack/foo/start". Seepack-add below for how the "opt"directory is used.

Loading packages automatically will not happen if loading plugins is disabled,seeload-plugins.

To load packages earlier, so that plugin/ files are sourced: :packloadallThis also works when loading plugins is disabled. The automatic loading willonly happen once.

If the package has an "after" directory, that directory is added to the end of'runtimepath', so that anything there will be loaded later.

Using a single plugin and loading it automatically

If you don't have a package but a single plugin, you need to create the extradirectory level:

% mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar% cd ~/.local/share/nvim/site/pack/foo/start/foobar% unzip /tmp/someplugin.zip

You would now have these files:

pack/foo/start/foobar/plugin/foo.vimpack/foo/start/foobar/syntax/some.vim

From here it works like above.

Optional plugins

pack-add
To load an optional plugin from a pack use the:packadd command:

:packadd foodebug

This searches for "pack/*/opt/foodebug" in'packpath' and will find~/.local/share/nvim/site/pack/foo/opt/foodebug/plugin/debugger.vim and sourceit.

This could be done if some conditions are met. For example, depending onwhether Nvim supports a feature or a dependency is missing.

You can also load an optional plugin at startup, by putting this command inyourconfig:

:packadd! foodebug

The extra "!" is so that the plugin isn't loaded if Nvim was started with--noplugin.

It is perfectly normal for a package to only have files in the "opt"directory. You then need to load each plugin when you want to use it.

Where to put what

Since color schemes, loaded with:colorscheme, are found below"pack/*/start" and "pack/*/opt", you could put them anywhere. We recommendyou put them below "pack/*/opt", for example"~/.config/nvim/pack/mycolors/opt/dark/colors/very_dark.vim".

Filetype plugins should go under "pack/*/start", so that they are alwaysfound. Unless you have more than one plugin for a file type and want toselect which one to load with:packadd. E.g. depending on the compilerversion:

if foo_compiler_version > 34  packadd foo_newelse  packadd foo_oldendif

The "after" directory is most likely not useful in a package. It's notdisallowed though.

Creating Vim packagespackage-create

This assumes you write one or more plugins that you distribute as a package.

If you have two unrelated plugins you would use two packages, so that Vimusers can choose what they include or not. Or you can decide to use onepackage with optional plugins, and tell the user to add the preferred oneswith:packadd.

Decide how you want to distribute the package. You can create an archive oryou could use a repository. An archive can be used by more users, but is abit harder to update to a new version. A repository can usually be keptup-to-date easily, but it requires a program like "git" to be available.You can do both, github can automatically create an archive for a release.

Your directory layout would be like this:

start/foobar/plugin/foo.vim          " always loaded, defines commandsstart/foobar/plugin/bar.vim          " always loaded, defines commandsstart/foobar/autoload/foo.vim        " loaded when foo command usedstart/foobar/doc/foo.txt             " help for foo.vimstart/foobar/doc/tags                " help tagsopt/fooextra/plugin/extra.vim        " optional plugin, defines commandsopt/fooextra/autoload/extra.vim      " loaded when extra command usedopt/fooextra/doc/extra.txt           " help for extra.vimopt/fooextra/doc/tags                " help tags

This allows for the user to do:

mkdir ~/.local/share/nvim/site/packcd ~/.local/share/nvim/site/packgit clone https://github.com/you/foobar.git myfoobar

Here "myfoobar" is a name that the user can choose, the only condition is thatit differs from other packages.

In your documentation you explain what the plugins do, and tell the user howto load the optional plugin:

:packadd! fooextra

You could add this packadd command in one of your plugins, to be executed whenthe optional plugin is needed.

Run the:helptags command to generate the doc/tags file. Including thisgenerated file in the package means that the user can drop the package in thepack directory and the help command works right away. Don't forget to re-runthe command after changing the plugin help:

:helptags path/start/foobar/doc:helptags path/opt/fooextra/doc

Dependencies between plugins

packload-two-steps
Suppose you have two plugins that depend on the same functionality. You canput the common functionality in an autoload directory, so that it will befound automatically. Your package would have these files:

pack/foo/start/one/plugin/one.vim

call foolib#getit()

pack/foo/start/two/plugin/two.vim

call foolib#getit()

pack/foo/start/lib/autoload/foolib.vim

func foolib#getit()

This works, because start packages will be searched for autoload files, whensourcing the plugins.

Plugin managervim.pack

WORK IN PROGRESS built-in plugin manager! Early testing of existing featuresis appreciated, but expect breaking changes without notice.

Manages plugins only in a dedicatedvim.pack-directory (seepackages):$XDG_DATA_HOME/nvim/site/pack/core/opt.$XDG_DATA_HOME/nvim/site needs tobe part of'packpath'. It usually is, but might not be in cases like--cleanor setting$XDG_DATA_HOME during startup. Plugin's subdirectory name matchesplugin's name in specification. It is assumed that all plugins in thedirectory are managed exclusively byvim.pack.

Uses Git to manage plugins and requires presentgit executable. Targetplugins should be Git repositories with versions as named tags followingsemver conventionv<major>.<minor>.<patch>.

The latest state of all managed plugins is stored inside avim.pack-lockfilelocated at$XDG_CONFIG_HOME/nvim/nvim-pack-lock.json. It is a JSON file thatis used to persistently track data about plugins. For a more robust configtreat lockfile like its part: put under version control, etc. In this case allplugins from the lockfile will be installed at once and at lockfile's revision(instead of inferring fromversion). Should not be edited by hand. Corrupteddata for installed plugins is repaired (including after deleting whole file),butversion fields will be missing for not yet added plugins.

Example workflows

Basic install and management:

Addvim.pack.add() call(s) to 'init.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 afteradd() call. Their revision is taken fromvim.pack-lockfile (if present) or inferred from theversion.

To update all plugins with new changes:

Executevim.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.

Switch plugin's version:

Update 'init.lua' for plugin to have desiredversion. Let's say, plugin named 'plugin1' has changed tovim.version.range('*').

:restart. The plugin's actual revision on disk is not yet changed. Only plugin'sversion invim.pack-lockfile is updated.

Executevim.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 runvim.pack.update().

Switch plugin's source:

Update 'init.lua' for plugin to have desiredsrc.

:restart. This will cleanly reinstall plugin from the new source.

Freeze plugin from being updated:

Update 'init.lua' for plugin to haveversion set to current revision. Get it fromvim.pack-lockfile (plugin's fieldrev; looks likeabc12345).

:restart.

Unfreeze plugin to start receiving updates:

Update 'init.lua' for plugin to haveversion set to whichever version you want it to be updated.

:restart.

Revert plugin after an update:

Locate plugin's revision at working state. For example:

If there is a previous version ofvim.pack-lockfile (like from version control history), use it to get plugin'srev field.

If there is a log file ("nvim-pack.log" at "log"stdpath()), open it and navigate to latest updates (at the bottom). Locate lines about plugin update details and use revision from "State before".

Freeze plugin to target revision (setversion and:restart).

Runvim.pack.update({ 'plugin-name' }, { force = true }) to make plugin state on disk follow target revision.:restart.

When ready to deal with updating plugin, unfreeze it.

Remove plugins from disk:

Usevim.pack.del() with a list of plugin names to remove. Make sure their specs are not included invim.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 followingevent-data fields:

active - whether plugin was added viavim.pack.add() to current session.

kind - one of "install" (install on disk; before loading), "update" (update already installed plugin; might be not loaded), "delete" (delete from disk).

spec - plugin's specification with defaults made explicit.

path - full path to plugin's directory.

These events can be used to execute plugin hooks. For example:

local hooks = function(ev)  -- Use available |event-data|  local name, kind = ev.data.spec.name, ev.data.kind  -- Run build script after plugin's code has changed  if name == 'plug-1' and (kind == 'install' or kind == 'update') then    vim.system({ 'make' }, { cwd = ev.data.path })  end  -- If action relies on code from the plugin (like user command or  -- Lua code), make sure to explicitly load it first  if name == 'plug-2' and kind == 'update' then    if not ev.data.active then      vim.cmd.packadd('plug-2')    end    vim.cmd('PlugTwoUpdate')    require('plug2').after_update()  endend-- If hooks need to run on install, run this before `vim.pack.add()`vim.api.nvim_create_autocmd('PackChanged', { callback = hooks })

vim.pack.Spec

Fields:

{src} (string) URI from which to install and pull updates. Any format supported bygit 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 (usuallymain ormaster).

String to use specific branch, tag, or commit hash.

Output ofvim.version.range() to install the greatest/last semver tag inside the version constraint.

{data}? (any) Arbitrary data associated with a plugin.

add({specs},{opts})vim.pack.add()
Add plugin to current session

For each specification check that plugin exists on disk invim.pack-directory:

If exists, check if itssrc is the same as input. If not - delete immediately to clean install from the new source. Otherwise do nothing.

If doesn't exist, install it by downloading fromsrc intoname subdirectory (via partial bloblessgit clone) and update revision to matchversion (viagit checkout). Plugin will not be on disk if any step resulted in an error.

For each plugin execute:packadd (or customizableload function) making it 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 current revision. The specifiedversion can be not the one actually present on disk. Executevim.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 assrc.

{opts} (table?) A table with the following fields:

{load}? (boolean|fun(plug_data: {spec: vim.pack.Spec, path: string})) Loadplugin/ files andftdetect/ scripts. Iffalse, works like:packadd!. If function, called with plugin data and is fully responsible for loading plugin. Defaultfalse duringinit.lua sourcing andtrue afterwards.

{confirm}? (boolean) Whether to ask user to confirm initial install. Defaulttrue.

del({names})vim.pack.del()
Remove plugins from disk

Parameters:

{names} (string[]) List of plugin names to remove from disk. Must be managed byvim.pack, not necessarily already added to current session.

get({names},{opts})vim.pack.get()
Getsvim.pack plugin info, optionally filtered bynames.

Parameters:

{names} (string[]?) List of plugin names. Default: all plugins managed byvim.pack.

{opts} (table?) A table with the following fields:

{info} (boolean) Whether to include extra plugin info. Defaulttrue.

Return:

(table[]) A list of objects with the following fields:

{active} (boolean) Whether plugin was added viavim.pack.add() to current session.

{branches}? (string[]) Available Git branches (first is default). Missing ifinfo=false.

{path} (string) Plugin's path on disk.

{rev} (string) Current Git revision.

{spec} (vim.pack.SpecResolved) Avim.pack.Spec with resolvedname.

{tags}? (string[]) Available Git tags. Missing ifinfo=false.

update({names},{opts})vim.pack.update()
Update plugins

Download new changes from source.

Infer update info (current/target revisions, changelog, etc.).

Depending onforce:

Iffalse, 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 dedicated buffer-local mappings:

]] and[[ to navigate through plugin sections. Some features are provided via LSP:

'textDocument/documentSymbol' (gO vialsp-defaults orvim.lsp.buf.document_symbol()) - show structure of the buffer.

'textDocument/hover' (K vialsp-defaults orvim.lsp.buf.hover()) - show more information at cursor. Like details of particular pending change or newer tag.

'textDocument/codeAction' (gra vialsp-defaults orvim.lsp.buf.code_action()) - show code actions available for "plugin at cursor". Like "delete", "update", or "skip updating". Execute:write to confirm update, execute:quit to discard the update.

Iftrue, 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 byvim.pack, not necessarily already added to current session. Default: names of all plugins managed byvim.pack.

{opts} (table?) A table with the following fields:

{force}? (boolean) Whether to skip confirmation and make updates immediately. Defaultfalse.

Creating Vim packages

Plugin manager

Movatterモバイル変換

Pack

Using Vim packages

Creating Vim packagespackage-create

Plugin managervim.pack