Snapshot workflow

A snapshot is a commit: a reviewable tree of a manifest plus the files you approved. Nothing is captured that you did not select, and a commit is only created when content actually changed.

Selecting what gets captured

rivet checklist --repo ~/rivet-snapshots                       # show what exists
rivet checklist --repo ~/rivet-snapshots --select              # choose interactively
rivet checklist --repo ~/rivet-snapshots --only shell-git      # choose in a script
rivet checklist --json                                         # machine-readable

--select first walks Rivet’s curated configuration groups, then package sources: Pacman repositories, AUR packages, portable AppImages, Snap packages, and Flatpak applications, each toggled independently. Selections persist in the snapshot repository’s rivet.toml.

--only is the non-interactive form, and the capture-side twin of restore --only: it takes a comma-separated list of group ids plus packages, and deselects everything you did not name. Because it states the whole selection rather than adding to it, re-running the same command is a no-op and re-running a different one fully replaces the previous answer — which is what makes it safe to keep in a provisioning script.

$ rivet checklist --only shell-git,packages
✓ Saved selections: 1 configuration group(s), packages included.
Rivet checklist
  [x] Shell and Git — 2 path(s)

✓ Finished successfully.

The two flags conflict, and Rivet refuses them together rather than picking one: both write the saved selection, so accepting both would silently discard one of the two answers you gave.

APT, DNF, Zypper, XBPS, and Nix are captured by default on their respective distros; per-manager interactive toggles for them are not wired up yet, and --only packages is all-or-nothing across every manager. Unavailable optional tools (snap, flatpak) are reported as notices and skipped rather than failing the run.

Taking a snapshot

rivet snapshot --repo ~/rivet-snapshots
rivet snapshot --repo ~/rivet-snapshots --message "before the GPU driver swap"
rivet snapshot --repo ~/rivet-snapshots --push

Snapshots are identified by local time and host. Rivet also writes an anonymous navigation README into the repository.

Alongside the structured manifest.toml used for restore, each snapshot writes readable package lists under packages/: native.txt, foreign.txt, nix.txt, snap.txt, flatpak.txt, and a Markdown index. Those are there so a human can read a snapshot without running Rivet at all.

Reviewing before you push

Omit --push whenever you want a manual review step:

cd ~/rivet-snapshots
git status
git show --stat

Rivet rejects known secret paths and common private-key/token signatures before Git staging — including output captured from hooks — but reviewing the diff before the first push is still the right habit. See What Rivet excludes.

Checking for drift

rivet status --repo ~/rivet-snapshots

Reports files that are modified (M), newly found (A), or missing (D) relative to the last snapshot. Run snapshot to record reviewed changes.

Pushing safely

--push pushes Git specifically, after committing. It has no effect on the fs, rclone, and restic backends, which write directly to their destination during snapshot.

To deliberately replace remote history, use the guarded form. It uses Git’s --force-with-lease, which refuses to overwrite unexpected remote state:

rivet snapshot --repo ~/rivet-snapshots --push --force-push

If the configured GitHub repository was deleted, Rivet recreates that same private repository with gh and retries the push once.

Removing the latest snapshot

rivet snapshot --repo ~/rivet-snapshots --delete-latest --yes --push

Removes only the most recent snapshot commit, locally and remotely. Rivet refuses when the snapshot repository is dirty, or when that commit is the only one remaining. Earlier history is intentionally never rewritten.

Capturing something Rivet has no group for

rivet track ~/dev/scripts --repo ~/rivet-snapshots --include '**/*.sh'
rivet track --repo ~/rivet-snapshots --list
rivet untrack ~/dev/scripts --repo ~/rivet-snapshots

This records a [[track]] entry in rivet.toml. The path then flows through exactly the same pipeline as a built-in group: same exclusion rules, credential scanning, mode and symlink handling, and rollback on restore. Add --vault to seal a tracked path’s files instead of capturing them in the clear.

To add a whole application as a reusable group, drop a declarative plugin in ~/.config/rivet/plugins/ and list what is loaded with rivet plugins. Both are covered in full by Tracking files and writing plugins.

Diagnostics

Normal output is deliberately compact — counts and outcomes, not every path.

rivet --verbose snapshot --repo ~/rivet-snapshots
rivet --log ~/rivet-run.log snapshot --repo ~/rivet-snapshots --push

Warnings and failures are always summarised at the end of a run. When a selected configuration group can no longer be found, Rivet records a warning rather than silently omitting it.