Rebuild the GNU Info Index with update-info-dir

Run update-info-dir with no arguments and you have just rewritten a system-wide documentation index, because the default target is /usr/share/info. This guide rebuilds the GNU Info menu for a directory you choose and checks that the resulting dir index actually came from the installed Info files.

Allow about ten minutes if you are checking an existing system; the command itself finishes quickly. It uses the locally installed install-info package, version 7.1-3build2, and the matching update-info-dir(8) behaviour.

1. Check the installed command

Confirm which executable your shell runs and record the package version. None of this needs elevated privileges or changes anything:

$ command -v update-info-dir
/usr/sbin/update-info-dir
$ dpkg-query -W -f='${Package} ${Version}\n' install-info
install-info 7.1-3build2
$ update-info-dir --help
SYNOPSIS: update-info-dir [-h,--help] [info-directory]

The only operational flag is -h or --help. The one positional argument is the directory whose Info index to rebuild; leave it out and the program falls back to /usr/share/info.

Checkpoint: if command -v finds a different executable, stop and inspect that installation first. The package version matters if you are comparing results with another machine.

2. Inspect the default directory before changing it

Look at the current directory and index as an ordinary user:

$ ls -ld /usr/share/info
drwxr-xr-x 2 root root ... /usr/share/info
$ ls -l /usr/share/info/dir
-rw-r--r-- 1 root root ... /usr/share/info/dir

Your ownership, size and timestamps will differ. What matters is that the directory exists and the current index is named dir, the file Info browsers read at startup.

Warning: do not run the default command just to see what it does. It writes into a system documentation directory normally owned by root. If you only want to see the output, use the isolated test below instead.

3. Test the rebuild in a temporary directory

Point the command at an explicit directory and you can watch it work without touching the system index. This copies one installed Info file into a scratch directory, then rebuilds that directory's menu:

$ test_dir=$(mktemp -d /tmp/info-dir-test.XXXXXX)
$ cp /usr/share/info/bc.info.gz "$test_dir/"
$ update-info-dir "$test_dir"
$ find "$test_dir" -maxdepth 1 -type f -printf '%f %s bytes\n' | sort
bc.info.gz ... bytes
dir ... bytes
$ sed -n '1,24p' "$test_dir/dir"
This is the file .../info/dir, which contains the
...
* Menu:

Math
* bc: (bc).                     An arbitrary precision calculator language.

Byte counts and intro text vary with your installed files. What matters is a new dir containing a menu entry for bc. On this version, an empty temporary directory with no matching Info files produces no index at all, so do not read an unchanged empty directory as a successful rebuild.

The scratch directory lives under /tmp and nothing in /usr/share/info was touched. Leave it for inspection or clean it up as you normally would.

Checkpoint: only move on if the temporary test produced dir and the menu names the file you copied in.

4. Rebuild the system index

Back up the current index before touching the default directory, since the file is normally owned by root and this is a privileged operation:

$ sudo cp --preserve=all /usr/share/info/dir /usr/share/info/dir.before-update-info-dir
$ sudo update-info-dir /usr/share/info

The command normally prints no progress at all, so a clean return to the shell is the signal to look for. Spelling out the path makes the write target visible in a script or review; leaving it out and running sudo update-info-dir alone does the same thing here, but an explicit path is safer if the command ever gets copied between hosts.

Warning: only use sudo when the target permissions actually require it, and never point the command at a directory of unrelated files just to test it. It indexes installed Info documentation there, nothing else.

5. Verify the resulting index

Confirm the target still exists, that dir is a regular file, and that its menu contains entries from the installed documentation:

$ stat /usr/share/info/dir
  File: /usr/share/info/dir
  Size: ...
...
$ grep -n '^\* Menu:' /usr/share/info/dir
...
$ grep -n 'bc:' /usr/share/info/dir
...

Do not expect a fixed line number or menu order: packages add and remove Info files, so the index changes between machines. Check instead that the file is readable, the * Menu: marker is there, and a known entry appears when its Info file is present.

Only try the interactive browser after the file check passes:

$ info bc

Press q to leave it. If it reports the entry cannot be found, go back and inspect the index and the Info file names, not just rebuild it again and hope.

6. Recover from an unwanted result

Warning: restoring the backup replaces the current system index. Confirm the backup exists and is the one you made for this change before overwriting anything:

$ sudo ls -l /usr/share/info/dir.before-update-info-dir
$ sudo cp --preserve=all /usr/share/info/dir.before-update-info-dir /usr/share/info/dir
$ grep -n '^\* Menu:' /usr/share/info/dir

This restores the previous index only; it does not uninstall packages or remove Info files. Keep the backup until you have checked the browser too, since deleting it is optional and irreversible.

If the command says the target is not a directory, check the path with ls -ld. In this version a missing target is rejected with a non-zero exit status rather than silently created. If it fails on permissions, confirm ownership first: changing it isn't a prerequisite for normal use.

Done means