Generate Vim Help Tags Safely with helpztags

Written a plugin's help file and found :help yourplugin does nothing? That is a missing tags file, and helpztags builds it in seconds. This guide builds a Vim tags file for a directory of help documents, then checks that Vim can actually use it. The installed command is helpztags 0.4 from vim-common version 2:9.1.0016-1ubuntu7.20. Allow about ten minutes if the documentation directory already exists.

You need a shell and a directory containing Vim help files. The command only reads those files and writes a generated tag file beside them, so you normally do not need sudo: do not run it as root just because the directory sits under a system path, only when your account genuinely lacks permission to write the tag file.

1. Check the installed command

Confirm which executable and package version you are using:

$ command -v helpztags
/usr/bin/helpztags
$ dpkg-query -W -f='${Package} ${Version}\n' vim-common
vim-common 2:9.1.0016-1ubuntu7.20

The command takes one or more directory arguments and has no option for choosing an output filename. For each directory it processes, it writes a file named tags into that directory.

2. Inspect the help directory

Use the directory that directly contains the help files: the program scans matching files in that directory, not an arbitrary tree below it.

$ HELP_DIR='/path/to/vim-help'
$ find "$HELP_DIR" -maxdepth 1 -type f \( -name '*.txt' -o -name '*.txt.gz' \) -print
/path/to/vim-help/intro.txt
/path/to/vim-help/plugins.txt.gz

Replace /path/to/vim-help with a real path. The command recognises plain .txt and compressed .txt.gz files. That find output is only an inventory; whether a tag is actually recognised depends on the Vim help markup inside each file.

Do not point it at a parent directory and expect nested language or version subdirectories to be picked up automatically. Run it once per directory whose tags you want generated.

3. Generate the tag file

Run helpztags with the help directory as its argument:

$ helpztags "$HELP_DIR"
Processing /path/to/vim-help

The Processing line is normal progress output. Worth recording the exit status too:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ ls -l "$HELP_DIR/tags"
-rw-r--r-- 1 user user 1234 Sep 24 12:00 /path/to/vim-help/tags

Your size and timestamp will differ. What matters is that a regular tags file now exists in the directory you passed in.

4. Check what was generated

Inspect a few lines without editing the generated file:

$ sed -n '1,8p' "$HELP_DIR/tags"
buffer\tintro.txt\t/*buffer*
help-tags\tplugins.txt.gz\t/*help-tags*
$ grep -F $'help-tags\t' "$HELP_DIR/tags"
help-tags\tplugins.txt.gz\t/*help-tags*

• Entries are sorted by tag name. Each line records the tag, the source file and a search pattern; your tag names and files will differ.
• File absent or empty? Check that the source files actually contain Vim help tags written as asterisks around the name, for example *help-tags*, with whitespace around the marked tag where Vim's help format requires it.
• Compressed files are read through zcat, not decompressed in place. The original .txt.gz file stays unchanged.

5. Test lookup in Vim

Start Vim with the help directory as a runtime path component, or test an existing Vim setup that already knows this directory:

$ vim -Nu NONE -n
:set runtimepath^=/path/to/vim-help
:helptags /path/to/vim-help
:help help-tags

In a normal Vim session, :help help-tags should open the matching help section if that tag exists. The :helptags command shown here is Vim's own built-in generator, a separate route worth using when you are already working inside Vim. Exit with :q when finished.

6. Recover from a stale or unwanted tag file

Running the command again regenerates tags in the target directory, replacing the previous file, so back it up first if it holds local changes:

$ cp --preserve=all "$HELP_DIR/tags" "$HELP_DIR/tags.backup"
$ helpztags "$HELP_DIR"
$ cmp -s "$HELP_DIR/tags" "$HELP_DIR/tags.backup"; printf 'cmp status: %s\n' "$?"
cmp status: 1

A status of 1 from cmp means the files differ, expected when the source documentation changed. If the new file is wrong, restore the backup explicitly:

$ mv "$HELP_DIR/tags.backup" "$HELP_DIR/tags"

Common traps

• No directory given. Calling helpztags with nothing is an error. Pass at least one directory, and check each additional path separately.
• Expecting recursion. Nested files get no useful tags from a single run. Use find to identify each relevant directory, then invoke helpztags against each one.
• Hunting for a custom output name. Do not bother, the output name is always tags; rename a copy only if a consuming tool explicitly requires it.
• Assuming any word becomes a tag. False confidence: the scanner looks for Vim's asterisk-delimited tags, not ordinary prose.