Fix lazy.nvim Local Changes That Block vimdoc-ja Updates

I moved plugin management over to lazy.nvim when I migrated from init.vim to init.lua .
On top of that, I also installed vimdoc-ja (in Japanese) as a lazy.nvim plugin so I could read :help in Japanese.

When I started Neovim, lazy.nvim would occasionally fail to update vimdoc-ja. The error was “local changes”, and the only file involved was doc/tags-ja.

The symptom

The message that showed up at startup was the following.

Failed (1)
  ● vimdoc-ja  0.46ms  start
      You have local changes in `~/.local/share/nvim/lazy/vimdoc-ja`:
        * doc/tags-ja
      Please remove them to update.
      You can also press `x` to remove the plugin and then `I` to install it again.

It was not the plugin itself that was treated as a local change, only the generated helptags file.
lazy.nvim refuses the update once it decides the git working tree is dirty.

The cause is that tags-ja is tracked in git

vimdoc-ja commits the generated doc/tags-ja (the helptags file) into the repository.
Meanwhile lazy.nvim runs :helptags on every plugin install or update and regenerates doc/tags-ja locally.

If that regenerated file differs from the committed content by even one byte, lazy.nvim concludes there are local changes in the git repository and stops the update.

The maintainer (folke) has stated clearly that there are no plans to add this kind of special-case handling on the lazy.nvim side.
The root issue is the structure of vimdoc-ja tracking generated files in git.

In the past, version differences in the Vim used to generate helptags were also a factor.
Vim 9.0.0110 changed how pseudo-tags in code examples inside the help were handled, which made the generated result more likely to drift.
After vimdoc-ja-working#1434 (in Japanese) (merged 2024-02-07) updated the generating Vim to 9.1.0065, it happens less often.
Even so, as long as :helptags runs every time, the drift itself can still come back.

The history is collected in vim-jp/vimdoc-ja#279 (in Japanese).

Workaround: clear the error that is showing now

If you just want the update to go through, discard the diff on that file.

cd ~/.local/share/nvim/lazy/vimdoc-ja
git checkout -- doc/tags-ja

Pressing x (remove) then I (install again) on the :Lazy screen gets you back to the same state.
That said, if :helptags runs again and doc/tags-ja drifts once more, the same error comes back.

Permanent fix: discard tags-ja before the update

Doing checkout by hand every time is a pain, so I decided to discard the diff right before lazy.nvim starts the update.
I added an autocmd on the LazyUpdatePre event just before the require('lazy').setup(...) call in ~/dotfiles/nvim/lua/plugins.lua.

-- vimdoc-ja tracks generated doc/tags-ja in git, so a local regenerate via :helptags
-- that differs makes lazy.nvim refuse the update with "local changes"
-- (https://github.com/vim-jp/vimdoc-ja/issues/279). Discard it before the update.
vim.api.nvim_create_autocmd('User', {
  pattern = 'LazyUpdatePre',
  group = vim.api.nvim_create_augroup('lazy_vimdoc_ja_fix', { clear = true }),
  callback = function()
    local dir = vim.fn.stdpath('data') .. '/lazy/vimdoc-ja'
    if vim.fn.isdirectory(dir) == 1 then
      vim.system({ 'git', 'checkout', '--', 'doc/tags-ja' }, { cwd = dir }):wait()
    end
  end,
})

Because it goes through stdpath('data'), I do not have to hard-code the plugin’s real path.
I took a workaround that is actually used in the community (mimikun/dotfiles ), simplified it, and put it into my own config.

Summary

The cause was not a bug in lazy.nvim. It was the combination of vimdoc-ja tracking generated doc/tags-ja in git and lazy.nvim running :helptags every time.
I hope this is useful for anyone whose updates have stopped on the same error.

See also