From e6d955cb2c93c71cd6a2b27b19792e0745fb6049 Mon Sep 17 00:00:00 2001
From: Evgeni Chasnovski <evgeni.chasnovski@gmail.com>
Date: Mon, 26 Jan 2026 15:20:33 +0200
Subject: [PATCH] docspack): mention re-install after source's default branch
 change #37560

Problem: `vim.pack.update()` doesn't update source's default branch if
  it has changed on the remote. It can be done by executing
  `git remote set-head origin --auto` for every plugin on every update,
  but it feels like too much extra work (which requires Internet
  connection) for a very rare use case.

  This matters since `version = nil` will keep pointing to previous
  default branch even after `vim.pack.update()`.

Solution: Document that in order for `version = nil` to point to the
  source's new default branch, perform clean re-install.
---
 runtime/doc/pack.txt     | 3 +++
 runtime/lua/vim/pack.lua | 3 +++
 2 files changed, 6 insertions(+)

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.