Exit 3 when a backup or restore finished but skipped files (closes #439)
check / check (push) Waiting to run

A `snapshot create` or `snapshot restore` that --skip-errors made skip
files now exits 3, the status `restic backup` uses, so a cron job can
tell it from a run that made no backup (1). RunOperation keeps the
operation's error inside errReported so Entry can pick the status.

A run that skipped files and also found a configured path empty, missed
a mount point, or was asked for a path the snapshot lacks still exits 1:
its error wraps only that condition and names the skipped files in text.

The README gains an exit status section.

Model: opus-5-5
This commit is contained in:
sneak committed 2026-11-19 13:09:34 +00:00
1 parent be362080d3
commit e5b08b8638
9 files changed
+191 -79

No files matched your search

+36 -22
View File
@@ -197,9 +197,10 @@ vaultik --version
that cannot be restored when restoring, instead of aborting. Packing and
storage errors while creating a snapshot (which would leave a chunk recorded
but not stored) still abort the run. A run that skipped anything still
finishes but exits non-zero: `snapshot create` keeps the snapshot and counts
each file or directory it skipped as failed. A file removed during the backup
is also counted as failed but does not change the exit status.
finishes but exits `3` (see [exit status](#exit-status)): `snapshot create`
keeps the snapshot and counts each file or directory it skipped as failed. A
file removed during the backup is also counted as failed but does not change
the exit status.
### locking
@@ -272,6 +273,19 @@ Every `--json` command therefore pipes on its own, with no additional flag:
`vaultik snapshot list --json | jq .` and `vaultik prune --json | jq .` both
work as written.
### exit status
- `0`: the command succeeded.
- `1`: the command failed.
- `3`: `snapshot create` or `snapshot restore` finished, but `--skip-errors`
skipped files it could not read or restore. `restic backup` uses the same
status for this case.
- `130`: Ctrl-C, `SIGINT` or `SIGTERM` stopped the command.
A cron job can page on `1` and only log `3`. A run that skipped files and also
failed in another way exits `1`. For example, a restore that skipped files and
was asked for a path the snapshot does not hold exits `1`.
### environment variables
- `VAULTIK_AGE_SECRET_KEY`: Age private key for decryption (required for
@@ -345,25 +359,25 @@ In such a config, an unknown key or a value of the wrong type is refused.
delete from the destination store what `prune` deletes there. By default keeps
only the latest snapshot per name; use `--keep-newer-than` for a rolling
window. When `--skip-errors` skipped a file or directory it could not read or
list, the prune does not run and every older snapshot is kept, since one of
them may be the only one that holds what was skipped; the command says so and
exits non-zero. When the backup found nothing in a configured path, as in the
mount point of a volume that is not mounted, the prune does not run either:
every older snapshot is kept, and the command names the path and exits
non-zero, on every run until the path holds something again. Take a path that
is empty on purpose out of the config, or remove the older snapshots by hand
with `snapshot purge`. When an earlier snapshot of the same name in the local
index found a volume mounted at or below a configured path (a directory on a
different filesystem from its parent, with an entry in it that the backup does
not exclude) and this backup does not, the prune does not run either: every
older snapshot is kept, and the command names the directory and exits
non-zero, on every run until the volume is mounted again. A backup also does
not find the volume when it finds no such entry in its directory, as when an
automounted volume cannot be mounted, or when that directory is no longer
backed up, because it is excluded or its configured path was removed. If any
of this is on purpose, as for a retired volume, remove the older snapshots by
hand with `snapshot purge`. A file removed during the backup does not stop the
prune.
list, the prune does not run and every older snapshot is kept. One of them may
be the only one that holds what was skipped. The command says so and exits
`3`. The prune does not run either when the backup found nothing in a
configured path, as in the mount point of a volume that is not mounted. Every
older snapshot is kept, and the command names the path and exits `1`, on every
run until the path holds something again. Take a path that is empty on purpose
out of the config, or remove the older snapshots by hand with
`snapshot purge`. The prune does not run either when this backup does not find
a volume that an earlier snapshot of the same name in the local index found.
The volume's mount point is a directory at or below a configured path. That
directory is on a different filesystem from its parent and holds an entry the
backup does not exclude. Every older snapshot is kept, and the command names
the directory and exits `1`, on every run until the volume is mounted again. A
backup also does not find the volume when it finds no such entry in its
directory, as when an automounted volume cannot be mounted. Nor does it find
the volume when that directory is no longer backed up, because it is excluded
or its configured path was removed. If any of this is on purpose, as for a
retired volume, remove the older snapshots by hand with `snapshot purge`. A
file removed during the backup does not stop the prune.
- `--keep-newer-than <duration>`: With `--prune`, keep snapshots newer than this
duration instead of only the latest (e.g. `4w`, `30d`, `6mo`, `1y`). Without
`--prune`, or with a value that is not a valid duration, the command fails