Learn Borg Backup - Prune & Compact (Retention)

#Introduction

After a few weeks of daily backups, the repository fills up with archives. Without a policy, disk space runs out and every borg create slows down. Episode 8 introduces two commands that work as a pair: borg prune to delete archives according to retention rules, and borg compact to truly reclaim the space. This is where you start thinking like an SRE: backup is not just copying, it is managing the data lifecycle.

#Prune: Managing Archive History

#The Basic Command

Prune with a retention policy

borg prune --list --stats \
  --keep-daily 7 \
  --keep-weekly 4 \
  --keep-monthly 6 \
  /backup/borg

Reading the rules:

--keep-daily 7 — keep the last 7 daily archives.
--keep-weekly 4 — keep the last 4 weekly archives.
--keep-monthly 6 — keep the last 6 monthly archives.

Borg computes the "newest" archives for each category and deletes the rest. Archives retained by any category will not be deleted. --list and --stats show what was deleted and how much space could potentially be freed.

#Filtering with --prefix and --glob-archives

If one repo holds archives from many hosts or backup types, limit the prune scope:

Prune only one host's archives

borg prune --prefix "web-01-" \
  --keep-daily 7 --keep-weekly 4 /backup/borg

Prune with a glob pattern

borg prune --glob-archives "web-01-*" \
  --keep-daily 7 --keep-weekly 4 /backup/borg

#--keep-tag: Protecting Important Archives

Not every archive is subject to retention. For snapshots that must survive (e.g. before a big migration or release), give them a tag:

Tag an important archive

borg tag /backup/borg::"web-01-2026-08-13T10:30:00" pre-migration

Prune respects tags

borg prune --keep-tag pre-migration \
  --keep-daily 7 --keep-weekly 4 --keep-monthly 6 /backup/borg

Archives tagged pre-migration will be kept indefinitely until you remove the tag or delete the archive explicitly.

Important

Since Borg 1.2, prune and delete no longer automatically free space. They only mark segments as unused. Space truly comes back only after borg compact. If you only ran prune and wonder why df did not change — this is the answer.

#Compact: Reclaiming Space

#The Command

Compact the repository

borg compact /backup/borg

borg compact merges segments that still contain valid chunks, discards chunks no longer referenced by any archive, and deletes empty segments. Run compact every time you finish a prune or delete.

#When to Run It

After every scheduled prune.
After a manual borg delete.
As part of monthly maintenance (episode 12) to handle fragments from deleted archives.

#Building a Retention Policy: RPO and RTO

#RPO and RTO

RPO (Recovery Point Objective): how much data may be lost. A daily backup means an RPO of at most 24 hours.
RTO (Recovery Time Objective): how quickly the system must recover.

A retention policy must answer these two numbers, not follow habit:

Strict RPO (at most 1 hour of loss): needs hourly backups → more archives → shorter retention.
Strict RTO: needs fast restores → routine restore tests and consider a repo on fast local storage.
Historical needs: old data is rarely accessed but must exist → keep it longer with decreasing density (daily → weekly → monthly → yearly).

#Example Policy

Example retention policy

Short   (7 days)    : --keep-daily 7
Medium  (4 weeks)   : --keep-weekly 4
Long    (6 months)  : --keep-monthly 6
Yearly  (2 years)   : --keep-yearly 2
Total active archives: 7 + 4 + 6 + 2 = 19

Because of Borg dedup, old archives that contain the same data as new ones barely add space — so long retention is not as expensive as it looks.

Tip

A retention policy should be written down, agreed by the team, and reviewed periodically — not kept in someone's head. When the policy changes, just change the prune parameters; borgmatic (episode 9) is the right place to document it as code.

#Common Pitfalls

Prune without compact: space does not come back — always run the two together.
Prune without a prefix on a shared repo: one repo, many hosts? Without --prefix, prune can delete another host's archives. Filter first.
Retention too short for audits: if you have audit obligations, keep yearly archives longer — delete only after the compliance period ends.
Ignoring --stats: a prune that deletes hundreds of archives should be suspicious. Always inspect the output before and after.

#Closing

borg prune deletes archives according to retention rules (daily/weekly/monthly/yearly).
borg compact reclaims space — mandatory after prune/delete.
Use --prefix/--glob-archives to filter the scope on shared repos.
--keep-tag protects important archives from automatic deletion.
A retention policy must answer your organization's RPO and RTO, not habit.

In episode 9 we automate everything: automation with borgmatic — a YAML config that brings together create, prune, compact, and check in one place, scheduled via cron or a systemd timer, with hooks before and after the backup.