Snapper Tools

Snapper Tools (snapper-tools) is a small Qt 6 application to create, delete and restore Snapper snapshots of the root filesystem. Its menu entry reads Create, delete and restore Snapper snapshots. Its main job is to bring a broken system back after you boot into a snapshot. The changelog entry that introduced it calls it a tool that Mimics the UI of Timeshift while being able to restore snapshots.

The Snapper configuration that it works with is set up by snapper-support. For the restore procedure from the boot menu, see Restoring snapshots.

Package

Item	Value
Package	`snapper-tools`. The README says the PKGBUILD lives in the AUR.
Build	CMake with Qt 6 `Widgets` and `Svg`. It installs `/usr/bin/snapper-tools`, the menu entry and the icon `snapper-tools.svg`.
ISO	Listed in the `Snapshot` section of `Packages-Desktop-Common`, together with `snapper-support` and `btrfs-assistant`.
Needed by	`garuda-system-maintenance` depends on it.
Translations	The `i18n/` folder holds 47 Qt Linguist files. They are managed through Transifex.

Starting it

From the menu: Snapper Tools, in the System category.
From a terminal: snapper-tools.
On Garuda Hyprland: SUPER + F11 (garuda-hyprland-settings).
On Dr460nized: the default dock has a launcher for it.

The window needs root rights. When you start it as a normal user, it runs itself again through pkexec /usr/lib/snapper-tools-pkexec gui. The polkit action org.garuda.snapper-tools.pkexec.policy.run asks for the administrator password.

The window

The window lists all snapshots under @/.snapshots, newest first. The row header is the snapshot number. The columns are Date (hh:mm yyyy-MM-dd) and Description.

Button	What it does
Create	Asks for a description (default `Manual Snapshot`) and runs `snapper create -t single -d <description>`.
Delete	Runs `snapper delete <number>` for every selected snapshot.
Restore	Restores the selected snapshot to `@`. Only one snapshot can be selected. It asks `Are you sure you want to restore snapshot <number> to @?` first.
Settings	Opens the settings dialog described below.

While you are booted into a snapshot, only Restore is enabled. Create, Delete and Settings stay greyed out.

Settings

The settings dialog reads the values with snapper --jsonout get-config and saves them with snapper set-config.

Field	Snapper key
Enable timeline snapshots	`TIMELINE_CREATE`
Hourly, Daily, Weekly, Monthly, Yearly	`TIMELINE_LIMIT_HOURLY`, `TIMELINE_LIMIT_DAILY`, `TIMELINE_LIMIT_WEEKLY`, `TIMELINE_LIMIT_MONTHLY`, `TIMELINE_LIMIT_YEARLY`
Pacman Settings: Keep `<n>` snapshots	`NUMBER_LIMIT`

The defaults of these keys come from the Garuda Snapper template. See snapper-support.

Snapshot boot detection

Snapper Tools reads /proc/cmdline. It treats the boot as a snapshot boot when the command line has root=UUID=<uuid> and a rootflags= entry whose subvol= value contains .snapshots.

The repository contains an autostart entry, snapper-tools-check.desktop, named BTRFS Assistant Snapper check. It runs grep -q .snapshots /proc/cmdline && sleep 3 && snapper-tools --autostart. With --autostart the tool behaves like this:

If the system was not booted from a snapshot, it exits without showing anything.
If it was, it shows the dialog Snapshot boot detected with the text You are currently booted into snapshot <subvol> and the question Would you like to restore it?. This question comes before the password prompt.
If you answer Yes, it asks for the administrator password and starts the restore of the booted snapshot right away.
When the restore is done, it shows Subvolume has been restored successfully. Please reboot immediately.

Starting Snapper Tools by hand during a snapshot boot asks the same question.

How the restore works

A restore replaces the @ subvolume. It does not copy files back into the running system.

The tool mounts the top level (subvolid=5) of the Btrfs volume on a temporary folder /run/snapper-tools-<random>. During a snapshot boot it uses the UUID from the kernel command line.
It creates a writable copy of the chosen snapshot named @_backup_<timestamp>. The code says it uses the same format as BTRFS Assistant.
It moves the subvolumes nested directly in @ into the new copy.
It swaps the new copy and @ in one atomic rename (renameat2 with RENAME_EXCHANGE).

After the swap, @ holds the restored snapshot. The previous @ stays on the disk under the name @_backup_<timestamp>. Reboot right after the restore.

Old snapshots and restore backups

Snapper Tools also finds data that no cleanup removes on its own.

Kind	Rule in the code
Old snapshots	Snapshots without a Snapper cleanup algorithm that are 14 days old or older.
Old restore subvolumes	Subvolumes named `@_backup_<digits>` or `restore_backup_<name>_<digits>` that were last changed 10 or more days ago.

The find-old action lists them. The delete-old action removes them. Other Garuda tools use these actions.

garuda-health runs pkexec snapper-tools find-old. When it finds something, it reports Old Btrfs snapshots found that can be deleted. Its fix runs sudo snapper-tools delete-old.
garuda-system-maintenance runs pkexec /usr/bin/snapper-tools find-old and shows the notification Old snapshots/backups found. Its settings can turn this notification off.
The polkit rules in garuda-common-settings and garuda-system-maintenance allow find-old for members of the wheel group without a password. delete-old still asks for it.

Command line

All actions except gui must run as root. Otherwise the tool prints Application must be executed as root user.

sudo snapper-tools <action> [<argument>]

Action	Effect
`gui`	Open the window. This is the default when no action is given.
`list`	Print number, date and description of every snapshot.
`create [<description>]`	Create a snapshot. The default description is `Manual Snapshot`.
`delete <number>`	Delete one snapshot.
`restore <number>`	Restore one snapshot to `@`, as described above.
`find-old`	Print old snapshots and old restore subvolumes. Exit code 0 when something was found, 1 when nothing was found.
`delete-old`	Delete old snapshots and old restore subvolumes. Same exit codes as `find-old`.

Option	Effect
`-d`	Print debug output in command line mode.
`-h`, `--help`	Print the usage.

Package updates in a snapshot boot

Two other packages stop updates while you are booted into a snapshot, because the changes would be lost at the next reboot.

Package	Behavior
`garuda-hooks`	The pacman hook `01-snapshot-reject.hook` aborts every pacman transaction during a snapshot boot.
`garuda-update`	Refuses to update when `/proc/cmdline` contains `subvol=@/.snapshots/<number>/snapshot`.

Both print Please restore the snapshot via btrfs-assistant or snapper-tools. To bypass the check, set GARUDA_SNAPSHOT_PACMAN=1, for example sudo GARUDA_SNAPSHOT_PACMAN=1 pacman <arguments>.

snapper-support sets up Snapper, snap-pac and grub-btrfs.
Restoring snapshots walks through booting a snapshot and restoring it.
Garuda Health reports old snapshots and broken Snapper setups.
The Arch Wiki pages Snapper and Btrfs explain the tools underneath.