commit c81dc320b0246c25d2580d67a83a3b9f56738808
parent 56a4ef3c213d87bfba5f361376bd23eefdf6c6ec
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Mon, 28 Jul 2025 15:57:21 -0400
docs: vim.pack
Diffstat:
2 files changed, 55 insertions(+), 54 deletions(-)
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -8,7 +8,7 @@
Type |gO| to see the table of contents.
==============================================================================
-Using Vim packages *packages*
+Using Vim packages *packages*
A Vim "package" is a directory that contains |plugin|s. Compared to normal
plugins, a package can...
@@ -20,34 +20,34 @@ plugins, a package can...
located in "pack/*/start/*") and ones that are only loaded when needed with
|:packadd| ("opt" packages, located in "pack/*/opt/*").
- *runtime-search-path*
+ *runtime-search-path*
Nvim searches for |:runtime| files in:
- 1. all paths in 'runtimepath'
- 2. all "pack/*/start/*" dirs
+- 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 use |nvim_list_runtime_paths()| to list all used directories, and
|nvim_get_runtime_file()| to query for specific files or sub-folders within
the runtime path. Example: >
- " List all runtime dirs and packages with Lua paths.
- :echo nvim_get_runtime_file("lua/", v:true)
+ " 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 to
add 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
+ % 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.txt
- pack/foo/start/foobar/plugin/foo.vim
- pack/foo/start/foobar/syntax/some.vim
- pack/foo/opt/foodebug/plugin/debugger.vim
+You would now have these files under ~/.local/share/nvim/site: >
+ pack/foo/README.txt
+ pack/foo/start/foobar/plugin/foo.vim
+ pack/foo/start/foobar/syntax/some.vim
+ pack/foo/opt/foodebug/plugin/debugger.vim
On startup after processing your |config|, Nvim scans all directories in
'packpath' for plugins in "pack/*/start/*", then loads the plugins.
@@ -74,7 +74,7 @@ Loading packages automatically will not happen if loading plugins is disabled,
see |load-plugins|.
To load packages earlier, so that plugin/ files are sourced:
- :packloadall
+ :packloadall
This also works when loading plugins is disabled. The automatic loading will
only happen once.
@@ -86,21 +86,21 @@ Using a single plugin and loading it automatically ~
If you don't have a package but a single plugin, you need to create the extra
directory level: >
- % mkdir -p ~/.local/share/nvim/site/pack/foo/start/foobar
- % cd ~/.local/share/nvim/site/pack/foo/start/foobar
- % unzip /tmp/someplugin.zip
+ % 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.vim
- pack/foo/start/foobar/syntax/some.vim
+You would now have these files: >
+ pack/foo/start/foobar/plugin/foo.vim
+ pack/foo/start/foobar/syntax/some.vim
From here it works like above.
Optional plugins ~
- *pack-add*
+ *pack-add*
To load an optional plugin from a pack use the `:packadd` command: >
- :packadd foodebug
+ :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 source
it.
@@ -110,7 +110,7 @@ whether Nvim supports a feature or a dependency is missing.
You can also load an optional plugin at startup, by putting this command in
your |config|: >
- :packadd! foodebug
+ :packadd! foodebug
The extra "!" is so that the plugin isn't loaded if Nvim was started with
|--noplugin|.
@@ -129,17 +129,17 @@ Filetype plugins should go under "pack/*/start", so that they are always
found. Unless you have more than one plugin for a file type and want to
select which one to load with `:packadd`. E.g. depending on the compiler
version: >
- if foo_compiler_version > 34
- packadd foo_new
- else
- packadd foo_old
- endif
+ if foo_compiler_version > 34
+ packadd foo_new
+ else
+ packadd foo_old
+ endif
The "after" directory is most likely not useful in a package. It's not
disallowed though.
==============================================================================
-Creating Vim packages *package-create*
+Creating Vim packages *package-create*
This assumes you write one or more plugins that you distribute as a package.
@@ -154,28 +154,28 @@ bit harder to update to a new version. A repository can usually be kept
up-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 commands
- start/foobar/plugin/bar.vim " always loaded, defines commands
- start/foobar/autoload/foo.vim " loaded when foo command used
- start/foobar/doc/foo.txt " help for foo.vim
- start/foobar/doc/tags " help tags
- opt/fooextra/plugin/extra.vim " optional plugin, defines commands
- opt/fooextra/autoload/extra.vim " loaded when extra command used
- opt/fooextra/doc/extra.txt " help for extra.vim
- opt/fooextra/doc/tags " help tags
-
+Your directory layout would be like this: >
+ start/foobar/plugin/foo.vim " always loaded, defines commands
+ start/foobar/plugin/bar.vim " always loaded, defines commands
+ start/foobar/autoload/foo.vim " loaded when foo command used
+ start/foobar/doc/foo.txt " help for foo.vim
+ start/foobar/doc/tags " help tags
+ opt/fooextra/plugin/extra.vim " optional plugin, defines commands
+ opt/fooextra/autoload/extra.vim " loaded when extra command used
+ opt/fooextra/doc/extra.txt " help for extra.vim
+ opt/fooextra/doc/tags " help tags
+<
This allows for the user to do: >
- mkdir ~/.local/share/nvim/site/pack
- cd ~/.local/share/nvim/site/pack
- git clone https://github.com/you/foobar.git myfoobar
+ mkdir ~/.local/share/nvim/site/pack
+ cd ~/.local/share/nvim/site/pack
+ git clone https://github.com/you/foobar.git myfoobar
Here "myfoobar" is a name that the user can choose, the only condition is that
it differs from other packages.
In your documentation you explain what the plugins do, and tell the user how
to load the optional plugin: >
- :packadd! fooextra
+ :packadd! fooextra
You could add this packadd command in one of your plugins, to be executed when
the optional plugin is needed.
@@ -184,22 +184,22 @@ Run the `:helptags` command to generate the doc/tags file. Including this
generated file in the package means that the user can drop the package in the
pack directory and the help command works right away. Don't forget to re-run
the command after changing the plugin help: >
- :helptags path/start/foobar/doc
- :helptags path/opt/fooextra/doc
+ :helptags path/start/foobar/doc
+ :helptags path/opt/fooextra/doc
Dependencies between plugins ~
- *packload-two-steps*
+ *packload-two-steps*
Suppose you have two plugins that depend on the same functionality. You can
put the common functionality in an autoload directory, so that it will be
found 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()
+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, when
sourcing the plugins.
diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua
@@ -79,6 +79,7 @@ local new_layout = {
['news-0.10.txt'] = true,
['news-0.11.txt'] = true,
['nvim.txt'] = true,
+ ['pack.txt'] = true,
['provider.txt'] = true,
['tui.txt'] = true,
['ui.txt'] = true,
