# cachy-auto-update configuration
#
# One "Key=Value" per line, '#' starts a comment. The file is parsed, never
# sourced, so shell syntax has no special meaning here.
#
# After editing run:  systemctl restart cachy-auto-update.timer
# Documentation:      man cachy-auto-update

# ---------------------------------------------------------------------------
# Main switches, normally set through `cachy-auto-update enable/disable`
# ---------------------------------------------------------------------------

# Apply updates automatically in the background.
# Off after installation: a freshly installed package should not start
# rebuilding the machine before anybody asked it to.
Enabled=no

# Show a desktop notification after an update, and whenever something needs
# attention.
Notifications=yes

# ---------------------------------------------------------------------------
# When
# ---------------------------------------------------------------------------

# How much time has to pass between two update runs. Accepts a plain number of
# seconds or a suffix of s, m, h, d, w.
# The systemd timer ticks hourly regardless; this is what decides whether a
# tick actually does anything, which is also how a postponed run retries.
UpdateInterval=1d

# Never update while the battery is below this percentage. Ignored on mains
# power and on machines without a battery.
MinBatteryPercent=30

# Update only while plugged in. Stricter than MinBatteryPercent.
RequireAC=no

# Postpone the update while a game is running (GameMode, known game processes,
# or an application blocking idle).
SkipWhenGaming=yes

# ---------------------------------------------------------------------------
# What
# ---------------------------------------------------------------------------

UpdateAUR=yes
UpdateFlatpak=yes
UpdateAppImages=yes

# Also rebuild -git / -devel AUR packages. Off by default: these rebuild
# constantly and break more often than released packages.
UpdateDevel=no

# Which AUR helper to use: auto, paru, yay or pikaur.
AURHelper=auto

# When a new package has to replace or remove an existing one, decide it
# automatically instead of aborting the update. Straightforward replacements
# are handled either way; this covers the case where pacman would otherwise
# stop and ask.
AutoResolveConflicts=yes

# Packages that are never updated automatically, space separated.
# Example: IgnorePkg=linux linux-headers nvidia
IgnorePkg=

# ---------------------------------------------------------------------------
# Housekeeping
# ---------------------------------------------------------------------------

# Trim the pacman package cache after an update: drop the older versions of
# installed packages, and every cached version of packages that are no longer
# installed. Nothing that is currently installed is ever touched, so this only
# costs the ability to downgrade further back than KeepOldPackages.
# Without it /var/cache/pacman/pkg grows forever: tens of gigabytes on a
# machine with a few large packages.
CleanCache=yes

# How many old versions per package to keep when CleanCache is on. 3 is the
# Arch default and leaves room to downgrade. Set it to 1 if disk space matters
# more than that; on a machine with a handful of multi-gigabyte packages the
# difference is easily ten gigabytes.
KeepOldPackages=3

# Remove packages nothing depends on any more: pacman packages that were pulled
# in as dependencies and are now unreferenced, plus Flatpak runtimes no
# installed application uses.
# Off by default, and unlike CleanCache this one deletes installed software:
# "orphaned" only means no other package requires it, which is also true of
# something installed deliberately as a dependency of nothing.
RemoveOrphans=no

# ---------------------------------------------------------------------------
# Notification detail
# ---------------------------------------------------------------------------
#
# How long a message stays on screen is not configurable, because it follows
# from what the message is for: anything reporting that the machine still needs
# a person (a failed update, a paused package queue, a package that had to be
# skipped) waits until it is dismissed, since a message like that is only ever
# useful if it is still there when somebody comes back. Everything else, an
# update that simply worked included, times out on its own.

# Say that an update has started. Worth keeping on: while one runs, a shutdown
# request is refused and the desktop answers with an untranslated polkit
# password prompt that never mentions updates. The message is withdrawn again
# when the result arrives, so it costs one bubble, not two.
#
# Separate from the progress bar in the notification area, which is not
# optional and appears whenever the desktop supports one.
NotifyOnStart=yes

# Say something after a successful update. Nothing is ever shown when there
# was nothing to do.
NotifyOnSuccess=yes

# Report failures.
NotifyOnError=yes

# A kernel update that needs a restart is not announced by a notification. The
# running kernel loses its module tree as soon as pacman unpacks the new one,
# so that would fire while the run is still working through AUR packages and
# Flatpaks, and reads as an invitation to restart in the middle of it.
# `cachy-auto-update status` reports it instead. The machine is never restarted
# automatically either way.