commit 1ffaaa06c5529b26a97d57caf349eaed02233795
parent 7acfad226dac148cdf9950684afd35c5d65e6e14
Author: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Fri, 22 Aug 2025 13:41:36 +0300
docs(pack): document `$XDG_DATA_HOME/nvim/site` presence in 'packpath'
Problem: Some use cases might lead to `vim.pack.add()` failing to
`:packadd` a plugin because of missing entry in 'packpath'. Like with
`nvim --clean` or manually setting `$XDG_DATA_HOME` during startup.
Solution: Document it. A more proactive approach can be ensuring correct
'packpath' entry, but it is currently somewhat verbose to do (due to
having to adjust for Windows using `\` in 'packpath' entries).
Diffstat:
2 files changed, 6 insertions(+), 2 deletions(-)
diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
@@ -211,7 +211,9 @@ WORK IN PROGRESS built-in plugin manager! Early testing of existing features
is appreciated, but expect breaking changes without notice.
Manages plugins only in a dedicated *vim.pack-directory* (see |packages|):
-`$XDG_DATA_HOME/nvim/site/pack/core/opt`. Plugin's subdirectory name matches
+`$XDG_DATA_HOME/nvim/site/pack/core/opt`. `$XDG_DATA_HOME/nvim/site` needs to
+be part of 'packpath'. It usually is, but might not be in cases like |--clean|
+or setting |$XDG_DATA_HOME| during startup. Plugin's subdirectory name matches
plugin's name in specification. It is assumed that all plugins in the
directory are managed exclusively by `vim.pack`.
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
@@ -4,7 +4,9 @@
---is appreciated, but expect breaking changes without notice.
---
---Manages plugins only in a dedicated [vim.pack-directory]() (see |packages|):
----`$XDG_DATA_HOME/nvim/site/pack/core/opt`.
+---`$XDG_DATA_HOME/nvim/site/pack/core/opt`. `$XDG_DATA_HOME/nvim/site` needs to
+---be part of 'packpath'. It usually is, but might not be in cases like |--clean| or
+---setting |$XDG_DATA_HOME| during startup.
---Plugin's subdirectory name matches plugin's name in specification.
---It is assumed that all plugins in the directory are managed exclusively by `vim.pack`.
---
