Rebuild X Font Aliases Safely with update-fonts-alias

An X client can't resolve a font alias a package is supposed to provide, and update-fonts-alias is the tool that regenerates the lookup file.

It rebuilds the generated fonts.alias file for one or more Debian X font directories, using the alias fragments installed by font packages. The key detail is the operand: update-fonts-alias wants a directory name such as 75dpi or misc, not the full path to an X font directory.

The examples below were checked with xfonts-utils version 1:7.7+6build3. The installed program advertises two extra options, --include and --exclude, that the installed update-fonts-alias(8) page does not describe. Treat the local --help output as the authority for those version-specific options, and do not copy them into a package script without testing their exact behaviour.

1. Check the installed command

Start with read-only checks; they need no sudo:

$ command -v update-fonts-alias
/usr/sbin/update-fonts-alias
$ dpkg-query -W -f='${Package} ${Version}\n' xfonts-utils
xfonts-utils 1:7.7+6build3
$ update-fonts-alias --help
Usage: update-fonts-alias [OPTIONS] DIRECTORY ...
       update-fonts-alias { -h | --help }
...
    -h, --help                        display this usage message and exit
    -i, --include ALIAS-FILE          drop ALIAS-FILE from exlude list if any
    -x, --exclude ALIAS-FILE          add ALIAS-FILE to exclude list

The help text contains the spelling exlude; that is the program's own displayed text, not something you need to reproduce. The documented manual page lists only -h and --help. This mismatch is a good reason to check both the binary and the manual before putting a command into automation.

2. Understand what will be assembled

For each operand, the utility gathers matching files below /etc/X11/fonts/. An alias fragment has the form:

/etc/X11/fonts/75dpi/package-name.alias

It combines the matching fragments into fonts.alias in the corresponding X font directory. Depending on the layout present on the machine, that destination is under either /usr/lib/X11/fonts/ or /usr/share/fonts/X11/. This lets several packages contribute aliases without one package overwriting another's fragment.

Inspect a candidate directory before changing anything:

$ find /etc/X11/fonts/75dpi -maxdepth 1 -type f -name '*.alias' -print
/etc/X11/fonts/75dpi/xfonts-base.alias
$ ls -l /usr/share/fonts/X11/75dpi/fonts.alias
-rw-r--r-- 1 root root 1842 Sep 27 06:00 /usr/share/fonts/X11/75dpi/fonts.alias

Your file list will differ. An empty find result does not prove a directory is safe to invent: confirm the target X font directory exists and that the package layout expects it.

3. Use the final directory component

Pass the component name, not a path:

$ update-fonts-alias 75dpi

For several directories, give several operands in one invocation:

$ sudo update-fonts-alias 75dpi 100dpi misc

Checkpoint: Every operand above is just the final component. Do not use /usr/share/fonts/X11/75dpi, /usr/lib/X11/fonts/75dpi, or any other absolute path as the normal form. The manual marks absolute paths as deprecated because the utility needs the component to locate both the configuration fragments and the destination.

The first command may succeed without writing anything if the destination is writable by your user. On a normal system, regeneration under /usr needs root, so use sudo for the actual change rather than running an entire exploratory shell as root.

4. Check the result and preserve a rollback

Before a planned regeneration, save the current generated file if one exists. This is a state-changing step, so pick the exact file and make the backup explicit:

$ sudo cp --preserve=all \
    /usr/share/fonts/X11/75dpi/fonts.alias \
    /usr/share/fonts/X11/75dpi/fonts.alias.before-update

If your installation uses /usr/lib/X11/fonts, substitute that exact destination after checking it with ls. Do not back up a guessed path. Now rebuild:

$ sudo update-fonts-alias 75dpi
$ printf 'exit status: %s\n' "$?"
exit status: 0
$ ls -l /usr/share/fonts/X11/75dpi/fonts.alias
-rw-r--r-- 1 root root 1842 Sep 27 06:12 /usr/share/fonts/X11/75dpi/fonts.alias

Exit status zero means the utility ran successfully. It does not tell you every alias is semantically correct, so compare the generated file with the fragments when investigating a font lookup problem:

$ sed -n '1,80p' /usr/share/fonts/X11/75dpi/fonts.alias
$ grep -n 'alias-name' /usr/share/fonts/X11/75dpi/fonts.alias

The exact aliases are package and host specific. Do not treat the sample name alias-name as a real alias.

5. Read warnings before adding more operands

An invalid component is not necessarily fatal. This harmless diagnostic probe exits zero while warning there is no matching directory:

$ update-fonts-alias definitely-not-a-font-dir
warning: /etc/X11/fonts/definitely-not-a-font-dir does not exist or is not
   a directory
warning: /usr/share/fonts/X11/definitely-not-a-font-dir does not exist or
   is not a directory
$ printf 'exit status: %s\n' "$?"
exit status: 0

The line wrapping depends on terminal width. The important point is that a zero status can coexist with warnings. Check each operand and do not assume a partially useful run updated every requested directory.

No operand at all is an error:

$ update-fonts-alias
usage error: one or more font directories must be specified
$ printf 'exit status: %s\n' "$?"
exit status: 2

An unrecognised option is also an argument error. A malformed directory argument can produce a fatal error with status 1. These statuses are useful in maintainer scripts, but always log the diagnostic text alongside the number.

6. Undo a mistaken regeneration

If the regenerated file causes a problem and you made the backup above, restore only the affected file:

$ sudo cp --preserve=all \
    /usr/share/fonts/X11/75dpi/fonts.alias.before-update \
    /usr/share/fonts/X11/75dpi/fonts.alias

Recovery: That restores the generated index; it does not remove or alter the package-provided *.alias fragments. If the utility ran during a package installation or removal, fix the package state and rerun its normal maintainer operation rather than hand-editing the generated file, since the next regeneration will overwrite manual edits.

Do not delete the backup until an X client can resolve the expected font aliases. Removing it is irreversible, and deleting fonts.alias itself is not a substitute for rebuilding it.

Done means