update-notify/README.md

update-notify

Desktop notifications for pending updates on Arch Linux.

update-notify runs on a systemd user timer and checks:

• Repo updates, using checkupdates from pacman-contrib.
• AUR updates for packages in a local aurutils repository (aur repo -u).
• Custom kernel rebuilds: when a stock kernel (e.g. linux-lts) has a newer version than your custom build of it (e.g. linux-lts-custom), for the kernels set in KERNELS.
• Maintenance: .pacnew/.pacsave files to merge (pacdiff -o), and a reboot after the running kernel was upgraded.

It sends one notification, and only when its content changes since the last one:

• Update counts are shown once the total number of updates reaches a threshold (default 30). Reminders for git-monitor and pending firmware updates (fwupdmgr) are added when those tools are installed.
• Kernel rebuild reminders are always shown, even below the threshold.
• Maintenance reminders are added to every notification. On their own, they notify only when something new appears (a new file to merge, a new kernel to reboot into), so a .pacnew you keep isn't repeated.

Requirements

• pacman-contrib
• libnotify and a running notification daemon

Optional:

• aurutils: check AUR packages in the local repository
• fwupd: check for firmware updates
• git-monitor: remind to check git packages

Installation

update-notify is available in the AUR as update-notify. Install it with your AUR helper, e.g. aur sync update-notify with aurutils.

Then enable the timer:

systemctl --user enable --now update-notify.timer

The timer runs 5 minutes after boot, then every 6 hours.

Refresh after building packages

To run update-notify --quiet whenever a repository changes, add the repository files to watch to update-notify.path:

systemctl --user edit update-notify.path

[Path]
PathChanged=/home/aur-local/aur-local.db.tar.gz.sig
PathChanged=/home/custom-pkgs/custom-pkgs.db.tar.gz.sig

Watch the .db.tar.gz.sig file for signed repositories, or .db.tar.gz for unsigned ones (.db is a symlink). Then enable it:

systemctl --user enable --now update-notify.path

Usage

update-notify [-q|--quiet] [threshold]

threshold is the minimum number of updates (repo + AUR) before update counts are shown. It overrides the THRESHOLD setting below for that run's notification only; the pending file keeps the configured value.

--quiet updates the pending file without notifying. Changes to a notification already shown are recorded, so the next timer run doesn't repeat them; a new notification is left for the timer. update-notify.path uses it (through update-notify-quiet.service), so building many packages doesn't notify after each one.

Configuration

Settings are read from $XDG_CONFIG_HOME/update-notify/config (default ~/.config/update-notify/config), a bash file that is sourced by the script. All settings are optional:

• THRESHOLD: minimum number of updates before update counts are shown (default 30).
• AUR_REPO: name of the local aurutils repository (default aur-local).
• KERNELS: maps each stock kernel package to its custom build, e.g. KERNELS=([linux-lts]=linux-lts-custom). Empty by default, which disables the kernel check. Kernels where either package isn't installed are skipped.
• PACNEW_CHECK: set to 0 to disable the .pacnew/.pacsave reminder (default 1).
• REBOOT_CHECK: set to 0 to disable the reboot reminder (default 1). A reboot is needed when the running kernel's /usr/lib/modules/<version>/vmlinuz is gone.

A commented sample config is installed with the package. To start from it:

mkdir -p ~/.config/update-notify
cp /usr/share/doc/update-notify/config.example ~/.config/update-notify/config

Kernel versions are compared without pkgrel, so a stock packaging-only update doesn't trigger a rebuild reminder. A custom build already in the local repository but not installed yet counts as up to date.

The content of the last notification is stored in $XDG_STATE_HOME/update-notify (default ~/.local/state/update-notify). Delete it to get the current notification again.

Status bars

Each run also writes the pending updates to $XDG_STATE_HOME/update-notify/pending, whether or not the threshold is reached, for status bars such as xmobar to read:

threshold <THRESHOLD from the config, not the argument>
repo <pkg> <newver>
aur <pkg> <newver>
kernel <custom-pkg> <stock-ver>
pacnew <path>
reboot <running kernel version>

The file reflects the last timer or update-notify.path run. To keep a bar current in between, e.g. right after an upgrade, drop entries whose installed version (pacman -Q) is no longer older than newver; for kernel lines, whose custom build has caught up with stock-ver (ignoring pkgrel); for pacnew lines, whose file is gone; for reboot lines, whose version is no longer uname -r. This only reads local data, so it's cheap to run often.

License

GPL-3.0-or-later. See LICENSE.