% zelta-prune(8) | System Manager's Manual
zelta prune - report snapshot prune candidates
zelta prune [OPTIONS] source [target]
zelta prune reports snapshots on a source dataset tree that are candidates for pruning. It is nondestructive. To destroy snapshots, use zprune(8) with identical prune options.
Pruning is built from filters which describe the retention shape or narrow the dataset tree, snapshot names, target-safety requirement, or size recovery target.
By default, zelta prune applies this failsafe filter:
Defining any explicit retention shape replaces the 30/30 default. Filters can be combined; a snapshot is reported only when all selected filters allow it.
As with other Zelta commands, zelta prune works recursively on dataset trees. Source and target endpoints may be local or remote using scp(1)-style syntax.
The examples below show time moving left to right. o means kept. x means selected as a prune candidate.
Keep windows count from the latest snapshots. They protect recent history and prune older history.
oldest latest
x x x x x x x x x x x x x x x x x x o o o o
keep 4
Common options:
The grid keeps sparse historical points and prunes snapshots between them. Grid mode always protects the oldest and newest snapshots in each dataset.
oldest latest
o x x x o x x x o x o x o x o o o o o o o o
weekly daily hourly recent
Grid terms use COUNTxINTERVAL. A term without x keeps one snapshot per interval forever from that point onward. Separate terms with commas or vertical bars. Whitespace is allowed around x and between interval numbers and units.
zelta prune --prune-grid='30x1 day, 52x1 week, 1 year' source target
Grid intervals use the same duration syntax as --prune-time.
Snapshots older than a bounded grid span are prune candidates unless protected by another filter. An unbounded term such as 1 year keeps one snapshot per year for all older history. Zelta recommends putting unbounded terms last, but does not enforce it.
Bare numbers are seconds. Use unambiguous units for anything else:
seconds s, sec, second, seconds
minutes mi, min, minute, minutes
hours h, hour, hours
days d, day, days
weeks w, week, weeks
months mo, mon, month, months
years y, year, years
The units m and M are invalid because they are ambiguous between minutes and months. Months are treated as 30 days and years as 365 days.
source
: Dataset tree containing snapshots to evaluate.
target
: Dataset tree used for target-safety checks. If the target is omitted while --prune-guard is enabled, zelta prune returns an error. Use --no-prune-guard only for local-only retention.
--prune-num N
: Keep the newest N snapshots after the guard point. With the default guard, this keeps snapshots newer than the latest common source/target match.
--prune-time TIME
: Keep snapshots newer than TIME. Bare numbers are seconds.
--prune-grid GRID
: Apply GFS-style grid retention. Example: 30x1 day, 52x1 week, 1 year.
--prune-guard latest|unsynced|none
: Select target safety behavior. The default is latest.
latest
: Require a common source/target snapshot match. Snapshots newer than the latest match are protected from pruning.
unsynced
: Require each candidate to exist on the target with the same GUID and snapshot name. Snapshots not confirmed on the target are protected from pruning.
none
: Do not use target matching. This is local-only retention.
--no-prune-guard
: Equivalent to --prune-guard=none.
--prune-size SIZE
: Select oldest eligible snapshots until their estimated reclaim reaches at least SIZE. This planner target is off by default. SIZE accepts ZFS-style byte counts and suffixes such as K, KB, M, GB, and T.
The estimate is based on sequential oldest-first pruning. It does not factor in other retention shapes; if other filters create gaps, run pruning in multiple passes or use zprune(8) preview as the final authority.
Snapshots with clones are never reported as prune candidates. zprune also previews with zfs destroy -nvp before destruction, so clone checks remain effective if state changes after candidate selection.
-d, --depth LEVELS
: Limit dataset-tree recursion depth. A depth of 1 includes only the specified dataset.
-X, --exclude PATTERN
: Exclude datasets or snapshots matching PATTERN. Snapshot patterns begin with @. Dataset patterns may be exact dataset names or glob patterns containing /.
--include PATTERN
: Include only datasets or snapshots matching PATTERN. This uses the same pattern style as --exclude.
-f, --force
: Suppress the interactive prompt. With zelta prune, this only affects the prompt shown before the candidate list. With zprune(8), this permits destruction after preview without asking for confirmation.
-q, --quiet
: Hide the snapshot candidate list. If -f is also given, zelta prune suppresses the prompt and snapshot list.
--no-ranges
: Disable range compression. By default, consecutive snapshots are emitted as ZFS snapshot ranges.
-v, --verbose
: Increase verbosity. Specify once for operational detail, twice for debug output.
-n, --dryrun, --dry-run
: Display underlying listing commands without running them.
By default, zelta prune outputs ZFS snapshot names or ranges, one per line:
pool/dataset@oldest_snapshot%newest_snapshot
With --no-ranges, each candidate snapshot is emitted individually:
pool/dataset@snapshot
The output is suitable for review and for zprune(8). Manual piping to zfs destroy is discouraged; zprune previews candidates with zfs destroy -nvp and prompts before deletion.
Report candidates using the default 30/30 failsafe:
zelta prune tank/data backup:tank/data
Preview and confirm destructive pruning with the wrapper:
zprune tank/data backup:tank/data
Require every candidate to exist on the target:
zelta prune --prune-guard=unsynced tank/data backup:tank/data
Run local-only retention:
zelta prune --no-prune-guard tank/data
Keep a larger recent window:
zelta prune --prune-num=200 --prune-time=180days \
tank/data backup:tank/data
Apply GFS-style retention:
zelta prune --prune-grid='30x1 day, 52x1 week, 1 year' \
tank/data backup:tank/data
Exclude temporary datasets and include only daily snapshots:
zelta prune --exclude='*/tmp' --include='@daily-*' \
tank/data backup:tank/data
Prune from the oldest eligible snapshots until at least 1 GiB is selected:
zelta prune --prune-size=1G tank/data backup:tank/data
Returns 0 on success and non-zero on error.
zelta prune is under active development for the BSDCan 2026 prune workflow. Review output carefully before destructive use.
This command is driven by the same comparison engine as zelta match. See zelta-match(8) for source/target matching behavior.
zelta(8), zprune(8), zelta-options(7), zelta-match(8), zelta-backup(8), zfs(8), zfs-destroy(8)
Daniel J. Bell <bellhyve@zelta.space>