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.

Checkpoint: if command -v prints nothing, install or repair the package through your normal system administration process. Do not copy a similarly named script from an untrusted location into your path.

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.

Warning: if you use a package-managed runtime directory, check its ownership before writing. A failed open or permission error means the account cannot replace tags; either generate tags in a user-owned copy or use your system's approved administrative workflow, and avoid making the generated file world-writable.

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"

Recovery: this restore touches only the tag file. Keep the backup until lookup works; removing it with rm is irreversible.

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.

Done means

• Versions checked. The installed helpztags and vim-common versions were confirmed.
• Right directory scanned. You scanned the intended directory, not an assumed recursive tree.
• Tags generated. A tags file was created or refreshed beside the .txt and .txt.gz help files.
• Lookup tested. At least one generated entry was inspected and Vim lookup was tested.
• Recoverable. Any replacement was recoverable from an explicit backup.