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

+7 -6
View File
@@ -198,7 +198,8 @@ func RunApp(ctx context.Context, app *fx.App) error {
// (or, under `snapshot verify --json`, put in its document). Entry
// turns it into a non-zero exit status without printing anything
// further, so the error line is not doubled. It flows up from
// RunOperation through cobra to Entry.
// RunOperation through cobra to Entry, wrapping the operation's error
// so that Entry can choose the exit status from it.
var errReported = errors.New("operation failed")
// errInterrupted marks an operation that SIGINT or SIGTERM stopped
@@ -232,8 +233,8 @@ func RunOperation(
) error {
var (
mu sync.Mutex
finished bool // op returned before any interrupt cancelled it
failed bool // op finished with an error
finished bool // op returned before any interrupt cancelled it
opErr error // what op returned, when it finished
)
opts.Invokes = append(opts.Invokes,
@@ -258,7 +259,7 @@ func RunOperation(
mu.Lock()
finished = true
failed = err != nil
opErr = err
mu.Unlock()
}
@@ -303,8 +304,8 @@ func RunOperation(
switch {
case !finished:
return errInterrupted
case failed:
return errReported
case opErr != nil:
return fmt.Errorf("%w: %w", errReported, opErr)
default:
return nil
}
+16 -2
View File
@@ -9,6 +9,7 @@ import (
"sneak.berlin/go/vaultik/internal/globals"
"sneak.berlin/go/vaultik/internal/ui"
"sneak.berlin/go/vaultik/internal/vaultik"
)
// shortCommitLen is the number of git commit hash characters shown in
@@ -20,6 +21,13 @@ const shortCommitLen = 12
// shell reports for a command stopped by Ctrl-C.
const exitCodeInterrupted = 130
// exitCodeSkippedFiles is the exit status of a `snapshot create` or
// `snapshot restore` that finished but skipped files under
// --skip-errors. It is the status `restic backup` uses for a snapshot
// that could not read some files, so a cron job can tell such a run
// from one that made no backup.
const exitCodeSkippedFiles = 3
// Entry is the main entry point for the CLI application.
// It first calls globals.FillUnsetFromBuildInfo, which fills in the
// version, commit and commit date that the linker flags did not set.
@@ -30,8 +38,9 @@ const exitCodeInterrupted = 130
// The banner goes to stderr because stdout carries only the output the
// user asked for, such as a completion script or a `config get` value.
//
// It returns the process exit code (0 on success, 130 when interrupted,
// 1 on any other error) rather than calling os.Exit, so that main's
// It returns the process exit code (0 on success, 3 when files were
// skipped, 130 when interrupted, 1 on any other error) rather than
// calling os.Exit, so that main's
// deferred profile writers run before the process ends. See run in
// cmd/vaultik/main.go.
func Entry() int {
@@ -58,6 +67,11 @@ func Entry() int {
return exitCodeInterrupted
}
if errors.Is(err, vaultik.ErrFilesUnreadable) ||
errors.Is(err, vaultik.ErrFilesFailedRestore) {
return exitCodeSkippedFiles
}
return 1
}
@@ -0,0 +1,83 @@
package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
import (
"os"
"path/filepath"
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
const flagSkipErrors = "--skip-errors"
// TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips backs up,
// under --skip-errors, a source directory that does not exist, which the
// walk skips. The command exits with exitCodeSkippedFiles and reports
// the backup as completed, not as a failed snapshot creation. See
// https://git.eeqj.de/sneak/vaultik/issues/310 and
// https://git.eeqj.de/sneak/vaultik/issues/439.
//
//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
func TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips(t *testing.T) {
// writeBackupConfig would create the source directory.
configPath := writeHermeticPruneConfig(t, false)
code, stdout, stderr := runEntry(t,
flagConfig, configPath, flagSkipErrors, cmdSnapshot, cmdCreate)
assert.Equal(t, exitCodeSkippedFiles, code)
assert.Contains(t, stdout,
"Files: 1 examined, 0 backed up, 0 unchanged, 1 failed.")
assert.NotContains(t, stdout, "Finished successfully.")
assert.Contains(t, stderr,
"Backup completed, but 1 file(s) could not be read")
assert.NotContains(t, stderr, "Snapshot creation failed")
}
// TestEntrySnapshotRestoreSkipErrorsExitStatus backs up, deletes the
// blobs from the destination, and restores under --skip-errors, so every
// file is skipped. A restore that only skipped files exits with
// exitCodeSkippedFiles. One that was also asked for a path the snapshot
// does not hold exits 1. See
// https://git.eeqj.de/sneak/vaultik/issues/439.
//
//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
func TestEntrySnapshotRestoreSkipErrorsExitStatus(t *testing.T) {
for _, testCase := range []struct {
name string
missingPaths []string
want int
}{
{name: "skipped files only", want: exitCodeSkippedFiles},
{
name: "and a path that matches nothing",
missingPaths: []string{"/no/such/path"},
want: 1,
},
} {
t.Run(testCase.name, func(t *testing.T) {
configPath, storeDir := writeBackupConfigWithPrivateKey(t)
code, _, _ := runEntry(t,
flagConfig, configPath, cmdSnapshot, cmdCreate)
require.Equal(t, 0, code)
require.NoError(t, os.RemoveAll(filepath.Join(storeDir, blobsDir)))
// writeBackupConfig puts the source directory beside the
// config file.
sourceDir := filepath.Join(filepath.Dir(configPath), "source")
args := append([]string{
flagConfig, configPath, flagSkipErrors, cmdSnapshot,
cmdRestore, onlySnapshotID(t, configPath), t.TempDir(),
sourceDir,
}, testCase.missingPaths...)
code, _, stderr := runEntry(t, args...)
assert.Equal(t, testCase.want, code)
assert.Contains(t, stderr, "1 file(s) failed to restore")
})
}
}
@@ -1,30 +0,0 @@
package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
import (
"testing"
"github.com/stretchr/testify/assert"
)
// TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips backs up,
// under --skip-errors, a source directory that does not exist, which the
// walk skips. The command exits non-zero and reports the backup as
// completed, not as a failed snapshot creation. See
// https://git.eeqj.de/sneak/vaultik/issues/310.
//
//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
func TestEntrySnapshotCreateSkipErrorsExitsNonZeroWhenItSkips(t *testing.T) {
// writeBackupConfig would create the source directory.
configPath := writeHermeticPruneConfig(t, false)
code, stdout, stderr := runEntry(t,
flagConfig, configPath, "--skip-errors", cmdSnapshot, cmdCreate)
assert.Equal(t, 1, code)
assert.Contains(t, stdout,
"Files: 1 examined, 0 backed up, 0 unchanged, 1 failed.")
assert.NotContains(t, stdout, "Finished successfully.")
assert.Contains(t, stderr,
"Backup completed, but 1 file(s) could not be read")
assert.NotContains(t, stderr, "Snapshot creation failed")
}
+19 -8
View File
@@ -25,9 +25,13 @@ import (
"sneak.berlin/go/vaultik/internal/types"
)
// ErrFilesFailedRestore is returned when --skip-errors skipped files the
// restore could not write. Every other file was restored, so the caller
// can report it apart from a failed restore.
var ErrFilesFailedRestore = errors.New("file(s) failed to restore")
// Sentinel errors for restore failures.
var (
errFilesFailedRestore = errors.New("file(s) failed to restore")
errPathsNotInSnapshot = errors.New("requested path(s) not in the snapshot")
errFilesFailedVerify = errors.New("files failed verification")
errDecryptionKeyRequired = errors.New(
@@ -201,9 +205,9 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
}
// finishRestore prints the restore summary and the post-restore
// warnings, runs optional verification, and converts any failed-file
// count into an error. Otherwise it returns unmatchedErr, the error for
// the requested paths that matched nothing (nil when there are none).
// warnings, runs optional verification, and returns the error the
// restore ends with: one for the files --skip-errors skipped, one for
// unmatchedErr, the requested paths that matched nothing, or nil.
func (v *Vaultik) finishRestore(
repos *database.Repositories,
files []*database.File,
@@ -250,11 +254,18 @@ func (v *Vaultik) finishRestore(
}
}
if result.FilesFailed > 0 {
return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedRestore)
switch {
case result.FilesFailed > 0 && unmatchedErr != nil:
// A requested path that matched nothing outweighs skipped files:
// the error wraps only unmatchedErr, so the command does not exit
// as a restore that only skipped files.
return fmt.Errorf("%w; %d %s",
unmatchedErr, result.FilesFailed, ErrFilesFailedRestore.Error())
case result.FilesFailed > 0:
return fmt.Errorf("%d %w", result.FilesFailed, ErrFilesFailedRestore)
default:
return unmatchedErr
}
return unmatchedErr
}
// warnIfOwnershipNotPreserved warns once if some entry restored under
+1 -1
View File
@@ -80,7 +80,7 @@ func TestRestoreFreesBlobsNoPendingFileNeeds(t *testing.T) {
TargetDir: restoreDir,
SkipErrors: true,
})
require.ErrorIs(t, err, errFilesFailedRestore)
require.ErrorIs(t, err, ErrFilesFailedRestore)
requireRestoredFiles(t, fs, restoreDir, originals)
assert.LessOrEqualf(t, peak, 1,
+20 -7
View File
@@ -49,8 +49,7 @@ var ErrFilesUnreadable = errors.New("file(s) could not be read")
// prune because the scan found nothing in a configured path of a
// snapshot, as in the mount point of a volume that is not mounted. The
// snapshots are complete and kept, so the caller can report it apart
// from a failed backup. A run that also skipped unreadable files
// returns ErrFilesUnreadable instead.
// from a failed backup.
var ErrSourcePathEmpty = errors.New("source path(s) were empty")
// ErrVolumeNotMounted is returned when --prune skipped the post-backup
@@ -59,8 +58,8 @@ var ErrSourcePathEmpty = errors.New("source path(s) were empty")
// mounted there is not mounted, the run found no entry in it, or the
// directory is no longer backed up. The snapshots are complete and
// kept, so the caller can report it apart from a failed backup. A run
// that also skipped unreadable files or found a configured path empty
// returns ErrFilesUnreadable or ErrSourcePathEmpty instead.
// that also found a configured path empty returns ErrSourcePathEmpty
// instead.
var ErrVolumeNotMounted = errors.New(
"mount point(s) an earlier snapshot recorded were not found")
@@ -243,15 +242,29 @@ func (v *Vaultik) skipPostBackupPrune(
if filesUnreadable > 0 {
v.UI.Warningf("Skipped the post-backup prune because %d file(s) "+
"could not be read; older snapshots are kept.", filesUnreadable)
}
var err error
switch {
case len(emptyPaths) > 0:
err = fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty)
case len(unmountedPaths) > 0:
err = fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted)
default:
return fmt.Errorf("%d %w", filesUnreadable, ErrFilesUnreadable)
}
if len(emptyPaths) > 0 {
return fmt.Errorf("%d %w", len(emptyPaths), ErrSourcePathEmpty)
// An empty path or a missing volume can mean a whole volume is not
// in the backup, which outweighs skipped files: the error wraps only
// the former, so the command does not exit as a backup that only
// skipped files.
if filesUnreadable > 0 {
return fmt.Errorf("%w; %d %s",
err, filesUnreadable, ErrFilesUnreadable.Error())
}
return fmt.Errorf("%d %w", len(unmountedPaths), ErrVolumeNotMounted)
return err
}
// finishCreateSnapshot ends a run whose snapshots are all complete and
+9 -3
View File
@@ -176,8 +176,11 @@ func TestBackupThroughSymlinkWhoseTargetIsGoneDoesNotPrune(t *testing.T) {
// A backup under --skip-errors --prune that both skipped a file it could
// not read and found nothing in a configured path names the empty path
// too when it skips the prune. See
// https://git.eeqj.de/sneak/vaultik/issues/388.
// too when it skips the prune. It ends with the empty path's error, which
// names the unreadable file too but does not wrap ErrFilesUnreadable, so
// the command does not exit as a backup that only skipped files. See
// https://git.eeqj.de/sneak/vaultik/issues/388 and
// https://git.eeqj.de/sneak/vaultik/issues/439.
func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) {
log.Initialize(log.Config{})
t.Parallel()
@@ -207,7 +210,10 @@ func TestBackupWithEmptySourcePathAndUnreadableFileNamesBoth(t *testing.T) {
SkipErrors: true,
Snapshots: []string{snapshotName},
})
require.ErrorIs(t, err, vaultik.ErrFilesUnreadable)
require.ErrorIs(t, err, vaultik.ErrSourcePathEmpty)
require.NotErrorIs(t, err, vaultik.ErrFilesUnreadable)
require.EqualError(t, err,
"1 source path(s) were empty; 1 file(s) could not be read")
assert.Contains(t, env.out.String(),
"Skipped the post-backup prune because 1 file(s) could not be read")
assert.Contains(t, env.out.String(),