Borg: what a backup contains, and what retention keeps

What takes the space

borg list --format prints raw byte sizes by field: sort and tail to find heavy files:

borg list --format '{size:>12} {path}{NL}' ~/backup::desktop-2026-05-06 | sort -n | tail -50

1200000000 /home/user/videos/movie.mkv
420000000  /home/user/photos/raw.zip

numfmt --to=iec reads them as 1.2G, 850M, 420M; such findings usually mean a directory to exclude, not a Borg problem.

Verifying without restoring

borg check /path/to/repo
borg check user@host:/path/to/repo
borg check --verify-data /path/to/repo::archive-name
borg check --repository-only /path/to/repo

borg check verifies repository structure, metadata and archive consistency. --verify-data also reads and hashes contents — much slower, the only proof the data is intact. --repository-only limits the check to the repository, an archive argument to that archive.

A cheap smoke test without full verification:

borg list /path/to/repo::archive-name
borg extract --dry-run /path/to/repo::archive-name some/path/in/archive

What prune keeps

borg prune -v --list --progress --keep-weekly=10 --keep-monthly=4 --keep-yearly=2

prune deletes whole archives per the retention rules, keeping the most recent of each period:

Twenty January backups collapse to one kept archive for the month unless a weekly or daily rule retains more. Deletion is dedup-safe: blocks a kept archive references stay, the rest freed.

Without --keep-daily, daily granularity is not retained; retention is the union of named rules, not a superset.

Archive names are free-form

No naming pattern is enforced: a new one for future backups leaves old archives untouched and coexisting:

borg create /path/to/repo::myhost-{now:%Y-%m-%d-%H%M} /home/user

Two caveats: the new pattern must not collide with existing names, and anything filtering by prefix or glob — prune, list, check in a script, borgmatic — must be told. Renaming old archives is optional:

borg rename /path/to/repo::oldname newname

–filter is output, not content

--filter=AME selects which files Borg prints while running, not which are included:

borg create --filter=AME ...

A /home/user/newfile.txt
M /home/user/config.cfg
E /home/user/picture.jpg

The snapshot is identical whatever the filter: AME watches progress as a change log, and -v/--list add detail.