Global Transaction Hooks

Zoi features a powerful global transaction hook system designed to automate system maintenance tasks. Similar to alpm-hooks, these allow you to define actions that run exactly once at the end of a package operation (install, upgrade, or remove) based on which files were modified.

Why Use Global Hooks?Copy Anchor Link

In a standard package manager, if you install 50 packages that all contain fonts, you might end up running fc-cache 50 times. Zoi's global hooks solve this by:

1. Deduplication: Matching modified paths across all packages in a transaction and running the associated command once.
2. Decoupling: Allowing system administrators to define maintenance logic without modifying individual package definitions.
3. Efficiency: Ensuring system caches (like font caches, desktop databases, or ldconfig) are updated only when necessary.

Hook Definition (.hook.yaml)Copy Anchor Link

Hooks are defined using simple YAML files. They can be placed in:

• System: /etc/zoi/hooks/
• User: the user data directory under zoi/hooks/
• Extensions: Distributed via Zoi Extensions.

Example: update-icon-cache.hook.yamlCopy Anchor Link

name: update-icon-cache
description: Rebuilds GTK icon caches when icon themes are installed or removed.
platforms: ["linux"]
trigger:
  # Trigger if any package touches files below these directories.
  # Paths use the same `${usrroot}`, `${usrhome}`, `${pkgstore}` placeholders
  # as `zcp` destinations, so they match installed files exactly.
  dirs:
    - "${usrroot}/usr/share/icons"
    - "${usrroot}/usr/local/share/icons"
  # Only trigger for these operations
  operation: ["install", "upgrade", "remove"]
action:
  when: PostTransaction
  exec: |
    if command -v gtk-update-icon-cache >/dev/null 2>&1; then
      for dir in /usr/share/icons/* /usr/local/share/icons/*; do
        [ -d "$dir" ] && [ -f "$dir/index.theme" ] && gtk-update-icon-cache -q -t -f "$dir"
      done
    fi

Schema ReferenceCopy Anchor Link

trigger.dirs is preferred for directory-wide maintenance triggers such as icon themes. trigger.paths remains useful when a hook should only match specific filenames or extensions, such as ${usrroot}/usr/share/applications/*.desktop. trigger.packages is the most reliable way to trigger a hook based on the presence of a specific package in the transaction.

Installed files are recorded with staging placeholders (e.g. ${usrroot}/usr/share/fonts/foo.ttf). Both sides are normalized before matching, so ${usrroot}/usr/share/fonts/**, /usr/share/fonts/**, and usr/share/fonts/** all match the same files. ${pkgstore}/... files are store-internal and never match system triggers. zoi install, zoi update, and zoi uninstall all run PostTransaction hooks once per transaction.

Hook EnvironmentCopy Anchor Link

When Zoi executes a hook's action.exec command, it injects the following environment variables:

• ZOI_SCOPE: The scope of the current transaction (user, system, or project).
• ZOI_TRANSACTION_ID: The UUID v7 identifier for the active transaction.

This allows hooks to perform scope-specific actions, such as reloading a user-space daemon versus a system-wide service.

Builtin HooksCopy Anchor Link

Zoi ships with several essential builtin hooks for Linux systems:

• update-icon-cache: Runs gtk-update-icon-cache once when files under icon theme directories are modified.
• update-font-cache: Runs fc-cache -fv when fonts are modified.
• update-desktop-database: Runs update-desktop-database -q when .desktop files are modified.
• ldconfig: Runs ldconfig when shared libraries (.so files) are modified.

Overriding HooksCopy Anchor Link

Zoi follows a hierarchical loading order. If a hook in your user data directory under zoi/hooks/ has the same name as a builtin or system hook, your user hook will take precedence and override the others. This allows you to easily customize or disable standard system behaviors.