From f32d2a0c870e28502b44c459a6cec5414f20f6a8 Mon Sep 17 00:00:00 2001
From: Daniele Fucini <dfucini@gmail.com>
Date: Tue, 13 Oct 2026 21:18:08 +0200
Subject: [PATCH] Add README

---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..640dee3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# 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`).
+
+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.
+
+## 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
+
+Build and install the package with the included PKGBUILD:
+
+```
+makepkg -si
+```
+
+Then enable the timer:
+
+```
+systemctl --user enable --now update-notify.timer
+```
+
+The timer runs 5 minutes after boot, then every 6 hours.
+
+## Usage
+
+```
+update-notify [threshold]
+```
+
+`threshold` is the minimum number of updates (repo + AUR) before update counts are shown. The default is 30.
+
+To change the threshold used by the timer, override the service:
+
+```
+systemctl --user edit update-notify.service
+```
+
+```ini
+[Service]
+ExecStart=
+ExecStart=/usr/bin/update-notify 50
+```
+
+## Configuration
+
+These settings are at the top of the script:
+
+- `AUR_REPO`: name of the local aurutils repository (default `aur-local`).
+- `KERNELS`: maps each stock kernel package to its custom build. Kernels where either package isn't installed are skipped.
+
+Changes to the installed script are overwritten on upgrade, so change them in the source and rebuild the package.
+
+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.
+
+## License
+
+GPL-3.0-or-later. See [LICENSE](LICENSE).