Restore

Restore is opt-in at every step. Running it without --apply produces a plan and writes nothing.

Plan first

rivet restore --repo ~/rivet-snapshots
rivet restore --repo ~/rivet-snapshots --diff

--diff shows, per file, how the snapshot differs from your home directory before anything is written.

Choose what to restore

There are three tiers, in increasing order of how much you want to decide.

Everything. A bare rivet restore plans the whole snapshot, and lists the categories it contains so you can narrow it if you want to.

By category. Name the configuration groups you want, plus the pseudo-category packages:

rivet restore --only vim-neovim,shell-git    # dotfiles, no packages
rivet restore --only packages                # software, no dotfiles

Category names come from the snapshot itself, so run a bare rivet restore to see the ones yours has. An unrecognised name is an error listing the valid ones rather than a silently narrower restore.

--only excludes everything you do not name

That includes packages: --only vim-neovim restores no software at all. Name packages alongside your groups if you want both.

Item by item.

rivet restore --select

Interactively choose package sources and individual artifacts. Choices are saved beneath Rivet’s local state — not committed to the snapshot repository — and reused by future restore plans. --select and --only cannot be combined, since both write that saved selection.

Apply

rivet restore --repo ~/rivet-snapshots --apply --yes

Both flags are required. --yes acknowledges that existing files will be overwritten. With them, Rivet:

• installs approved native, AUR, Nix, Flatpak, and Snap packages
• restores selected AppImages with their executable mode
• restores in-root symlinks as symlinks
• replays captured hooks
• preserves every replaced home file under ~/.local/state/rivet/rollback/

Native package installation, system Flatpak, and Snap installation invoke sudo. AUR restoration requires paru or yay to already be installed, and Flatpak remotes and snapd must already be configured on the target system.

Restoring an earlier snapshot

rivet restore --repo ~/rivet-snapshots --revision HEAD~1
rivet restore --repo ~/rivet-snapshots --revision HEAD~1 --apply --yes

--revision accepts any Git ref — a commit hash, HEAD~3, a tag.

Restoring on a different distro

Restoring a snapshot taken on another distro family (an Arch snapshot on Fedora, say) resolves each native package through Rivet’s cross-distro package map rather than installing the name verbatim:

• an exact or hand-curated match becomes a normal install action
• an unmapped package becomes a warning — never a guessed install

rivet restore --repo ~/rivet-snapshots --strict-packages

--strict-packages refuses lower-confidence Repology-derived matches and keeps only hand-curated ones. See Cross-distro support for how the map is built and maintained.

Restoring from a specific backend

rivet restore --repo ~/rivet-snapshots --backend fs

Without --backend, restore reads from the first configured backend, or plain Git when none is configured. See Storage backends.

Rolling back a restore

Every file a restore replaced is copied to ~/.local/state/rivet/rollback/ first. There is no rivet rollback command yet — recovery today means copying files back from that directory by hand.