1

Part of the job performed by virtually all plugin managers in Vim is to create helptags, which will index the help files shipped with the plugins and will allow searching for commands and mappings added by the plugins themselves.

This action is implemented by calling the :helptags command and passing it the path to the doc/ directory inside a plugin directory tree.

The :helptags command will scan that directory for files matching *.txt, index the tags inside those files and then create a new file named tags inside that same directory.

So the contents of the tags file only depend on contents of files shipped by the plugin itself (the doc/*.txt files) and the file lives within the plugin directory tree as well (also under the doc/ subdirectory.)

So why is it that this file always needs to be generated when installing or updating plugins, rather than shipped with the plugins themselves?

I ask because it's kind of a pain to keep that always up to date when manually managing plugins, for instance when using the package manager support from Vim 8 and when storing the plugins as git submodules of a main repository.

  • 1
    IMHO generated files do not belong into a git repository. This shortens commit size, makes git log shorter, less human errors such as the tag file can be outdated w.r.t. actual doc file etc. BTW do you know that you can run :helptags ALL to generate/update all tags file with a single command? – Hotschke May 14 at 7:36
  • @Hotschke I somewhat agree with that in principle, but in this case the git repository is used both as source control and as a delivery mechanism, so I don't think storing the tags file there would be such a huge problem. Framing the question a bit differently, I think at some point Vim plugins were typically distributed as tarballs (Vimballs?) and I believe those didn't come with helptags either. Getting out of sync is definitely a concern, but git can somewhat deal with that using hooks to ensure contents are synchronized. – filbranden May 14 at 7:54
1

I think the helptags are not distributed with the plugins for the same reasons you don't put the tags generated by cscope or ctags in version control:

  • That limits the size of your repo
  • Since generating them is deterministic, there is no added value to have the file generated by the author
  • And that limit the risk for the author to distribute the wrong tags or to forget to update them.

Also if your problem is to manually keep track of your helptags, maybe you don't know about :helptag ALL which generates the tags for all of the directories in your runtimepath :h :helptags

EDIT I didn't see @Hotschke comment before redacting this answer but basically I agree with all they said :)

  • Actually yes, I do know about :helptags ALL (on Vim 8) or similarly :Helptags from Pathogen, but I don't think calling those from .vimrc is a good idea, both because it would always slow down startup, and because it wouldn't fix the help tags if a plugin is updated while Vim is opened already... So far, the best I've come up with is a wrapper around git submodule to update the helptags whenever they get synced, but I'm not in love with that since it can be easily forgotten... – filbranden May 14 at 7:50
  • Personally I don't use vim's built-in package manager because I find it way less convenient than vim-plug. However maybe you could create a git hook to automatically run the command after a git pull I think maybe a post merge hook could do the trick. – statox May 14 at 7:57
  • So for actual tags files in projects written in C, I'm using vim-gutentags, which works really well. I wonder if it would be possible to do something similar to generate helptags on demand, only when really needed? Perhaps an autocmd? Just not sure how to match it to :help being called... I'll take a look and see if I can find something that makes that work. – filbranden May 14 at 8:10
  • I don't think generating code tags and help tags are the same use case: I see the point of automatically generating code tags because they change often and you need to keep track of that, but you don't update your plugins as often (maybe once a month? I know that all of my plugins work just fine so I update them maybe once every few month) and in this case I have trouble seeing how running :helptag ALL manually is an issue. However instead of creating an hacky autocommand maybe you can just define your own :Help command which will run :helptags before running the actual :help command – statox May 14 at 15:08
  • 1
    @statox i have a makefile that runs my dotfiles; one of the phony targets is the helptags, also triggered by an update. – D. Ben Knoble May 14 at 17:12

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.