commit a3cfdcebb9b507e10537c4288047bcc6a6f47f96
parent 538c945fdf0c1980369373a9534656f4b2836bbf
Author: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Fri, 18 Jul 2025 17:43:41 +0300
docs: move *packages* and *package-create* into 'pack.txt'
Diffstat:
| M | runtime/doc/pack.txt | | | 197 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | runtime/doc/repeat.txt | | | 197 | ------------------------------------------------------------------------------- |
2 files changed, 197 insertions(+), 197 deletions(-)
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -8,6 +8,203 @@
Type |gO| to see the table of contents.
==============================================================================
+Using Vim packages *packages*
+
+A Vim "package" is a directory that contains |plugin|s. Compared to normal
+plugins, 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 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)
+
+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
+
+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
+
+On startup after processing your |config|, Nvim scans all directories in
+'packpath' for plugins in "pack/*/start/*", then loads the plugins.
+
+To allow for calling into package functionality while parsing your |vimrc|,
+|:colorscheme| and |autoload| will both automatically search under 'packpath'
+as well in addition to 'runtimepath'. See the documentation for each for
+details.
+
+In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load
+it.
+
+If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will
+find the syntax/some.vim file, because its directory is in the runtime search
+path.
+
+Nvim will also load ftdetect files, if there are any.
+
+Note that the files under "pack/foo/opt" are not loaded automatically, only the
+ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
+is used.
+
+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
+This also works when loading plugins is disabled. The automatic loading will
+only 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 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
+
+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*
+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 source
+it.
+
+This could be done if some conditions are met. For example, depending on
+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
+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 recommend
+you 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 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
+
+The "after" directory is most likely not useful in a package. It's not
+disallowed though.
+
+==============================================================================
+Creating Vim packages *package-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 Vim
+users can choose what they include or not. Or you can decide to use one
+package with optional plugins, and tell the user to add the preferred ones with
+`:packadd`.
+
+Decide how you want to distribute the package. You can create an archive or
+you could use a repository. An archive can be used by more users, but is a
+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
+
+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
+
+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
+
+You could add this packadd command in one of your plugins, to be executed when
+the optional plugin is needed.
+
+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
+
+
+Dependencies between plugins ~
+ *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()
+
+This works, because start packages will be searched for autoload files, when
+sourcing the plugins.
+
+==============================================================================
Plugin manager *vim.pack*
WORK IN PROGRESS built-in plugin manager! Early testing of existing features
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
@@ -521,203 +521,6 @@ Rationale:
backslash is to make it very unlikely this is a normal comment line.
==============================================================================
-Using Vim packages *packages*
-
-A Vim "package" is a directory that contains |plugin|s. Compared to normal
-plugins, 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 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)
-
-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
-
-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
-
-On startup after processing your |config|, Nvim scans all directories in
-'packpath' for plugins in "pack/*/start/*", then loads the plugins.
-
-To allow for calling into package functionality while parsing your |vimrc|,
-|:colorscheme| and |autoload| will both automatically search under 'packpath'
-as well in addition to 'runtimepath'. See the documentation for each for
-details.
-
-In the example Nvim will find "pack/foo/start/foobar/plugin/foo.vim" and load
-it.
-
-If the "foobar" plugin kicks in and sets the 'filetype' to "some", Nvim will
-find the syntax/some.vim file, because its directory is in the runtime search
-path.
-
-Nvim will also load ftdetect files, if there are any.
-
-Note that the files under "pack/foo/opt" are not loaded automatically, only the
-ones under "pack/foo/start". See |pack-add| below for how the "opt" directory
-is used.
-
-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
-This also works when loading plugins is disabled. The automatic loading will
-only 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 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
-
-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*
-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 source
-it.
-
-This could be done if some conditions are met. For example, depending on
-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
-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 recommend
-you 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 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
-
-The "after" directory is most likely not useful in a package. It's not
-disallowed though.
-
-==============================================================================
-Creating Vim packages *package-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 Vim
-users can choose what they include or not. Or you can decide to use one
-package with optional plugins, and tell the user to add the preferred ones with
-`:packadd`.
-
-Decide how you want to distribute the package. You can create an archive or
-you could use a repository. An archive can be used by more users, but is a
-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
-
-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
-
-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
-
-You could add this packadd command in one of your plugins, to be executed when
-the optional plugin is needed.
-
-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
-
-
-Dependencies between plugins ~
- *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()
-
-This works, because start packages will be searched for autoload files, when
-sourcing the plugins.
-
-==============================================================================
Debugging scripts *debug-scripts*
Besides the obvious messages that you can add to your scripts to find out what
