diff --git a/runtime/doc/pack.txt b/runtime/doc/pack.txt
index 96809efe42..aaf1bc7ba0 100644
--- a/runtime/doc/pack.txt
+++ b/runtime/doc/pack.txt
@@ -502,6 +502,9 @@ update({names}, {opts})                                    *vim.pack.update()*
     Notes:
     • Every actual update is logged in "nvim-pack.log" file inside "log"
       |stdpath()|.
+    • It doesn't update source's default branch if it has changed (like from
+      `master` to `main`). To have `version = nil` point to a new default
+      branch, re-install the plugin (|vim.pack.del()| + |vim.pack.add()|).
 
     Parameters: ~
       • {names}  (`string[]?`) List of plugin names to update. Must be managed
diff --git a/runtime/lua/vim/pack.lua b/runtime/lua/vim/pack.lua
index 9aabc91351..8ce951bde6 100644
--- a/runtime/lua/vim/pack.lua
+++ b/runtime/lua/vim/pack.lua
@@ -1210,6 +1210,9 @@ end
 ---
 --- Notes:
 --- - Every actual update is logged in "nvim-pack.log" file inside "log" |stdpath()|.
+--- - It doesn't update source's default branch if it has changed (like from `master` to `main`).
+---   To have `version = nil` point to a new default branch, re-install the plugin
+---   (|vim.pack.del()| + |vim.pack.add()|).
 ---
 --- @param names? string[] List of plugin names to update. Must be managed
 --- by |vim.pack|, not necessarily already added to current session.