Ramblings of General Geekery

Vimways Advent Blogging

Advent blogging, i.e. blogging about a specific subject every day between December 1st and December 24th, seems to be picking up steam quite a bit this year. In the previous years, FastMail was pretty much the only one in my feeds doing this but, ironically, as they stopped doing it this year, it’s been replaced by others like Micro.blog’s Manton Reece (although he’s only doing half of it) or Vimways.

Inspired by 24ways, another advent blog dating back a dozen years, Vimways is, as you might guess, about Vim!

I was flattered to have Gutentags, my little Vim plugin, mentioned in the 2nd entry of the blog, even if the Daniel Moch, the author, said he stopped using it a while ago. Since the various methods mentioned in the article are not all equivalent, I figured I would add some clarifications here.

This requires some basic knowledge about Vim’s tags feature-set, but thankfully if you’ve read the aforementioned Vimways article, you should know everything you need to.

Synchronization and scalability

Tags files contain the symbols of your codebase. As you work, however, symbols change – you add and remove methods, rename them, change their signature, etc. So, unless something is being done about it, the tags files slowly but surely get out-of-sync with the source code, until you can’t really jump around anymore (it’s common for me to keep a Vim instance alive for days on end!). Having something that can keep the tags in sync with code as you work on the latter is therefore important.

Now, most “simple” methods for managing tags files rely on running ctags whenever the tags file needs to be kept in sync with the source code. This works fine for most cases, because the codebase is either small (like in most utility/low-level libraries) or large but broken up in small pieces whose vast majority is excluded from the tags files (like most web development projects where all dependencies are in a node_modules-type folder).

For bigger codebases, however, this quickly breaks down because ctags takes a long time to run. It’s more efficient to only update the part of the tags file that relates to the code you’re changing, and leave the rest alone.

Gutentags does this by running ctags only on the file you just saved in Vim.

If you want to keep your tags management separate from the text editor, you can, like Daniel says in his article, use some file-system watcher to regenerate your tags… you can even use that file-system watcher to run Gutentags’ own tag generation script directly, passing the proper options:

cd /my/project
/path/to/update_tags.sh -s /my/project/file_that_was_written

Run update_tags.sh -?, or look inside the script’s source code, to see what other options are available. Even if you don’t use Gutentags as a Vim plugin, you might want to use its sh and cmd scripts!

Combining methods

One common problem with having Vim manage the tags file is that it doesn’t know when the codebase is being modified externally – mainly when pulling/merging/etc. files in your VCS.

To fix this, many Gutentags users actually combine Gutentags with Tim Pope’s Git hook-based. After all, there’s no reason not to have the best of both worlds, where you don’t need to remember to run :GutentagsUpdate! after a git pull, and where your tags don’t go out of sync when you write code

It’s a DIY world

Vim is ultimately about being able to do things your own way, so hopefully you can find yet another cool method to manage your tags, in which case you can share it with us!