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?

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)

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

• System: /etc/zoi/hooks/
• User: ~/.zoi/hooks/
• Extensions: Distributed via Zoi Extensions.

Example: update-icon-cache.hook.yaml

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
  dirs:
    - "usr/share/icons"
    - "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 Reference

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 usr/share/applications/*.desktop.

Builtin Hooks

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 Hooks

Zoi follows a hierarchical loading order. If a hook in your user directory (~/.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.