Prune by either int or interval for all retention policies

docs/misc/prune-example-interval.txt

@@ -0,0 +1,91 @@
+borg prune visualized (count and interval mixed)
+================================================================================
+
+Assume it is 2026-06-04 16:00. You have been creating backup archives at 16:00
+on most days going back to late 2025, with pruning running immediately after
+each archival. Todays archive has just been made and the following prune
+operation is about to start.
+
+This example shows what would be kept/pruned when running the following prune
+command. Note the yearly rule keeping _any two_ yearly archives.
+
+borg prune \
+  --since '2026-06-04 16:00' \
+  --keep-daily 1w \
+  --keep-monthly 5m \
+  --keep-yearly 2
+
+Archives kept by the `--keep-daily` rule are marked by a "d",
+archives kept by the `--keep-monthly` rule are marked by an "m", and
+archives kept by the `--keep-yearly` rule are marked by a "y" to the
+right.
+
+The first archive was made on 2025-11-15. You missed the backups on 2026-03-31
+and 2026-06-03.
+
+
+Calendar view
+-------------
+                            2025
+                            November              December
+                                             1  2  3  4  5  6  7
+                                             8  9 10 11 12 13 14
+                                     15y16  15 16 17 18 19 20 21
+                      17 18 19 20 21 22 23  22 23 24 25 26 27 28
+                      24 25 26 27 28 29 30  29 30 31y
+
+                            2026
+      January               February               March
+          1  2  3  4                     1                     1
+ 5  6  7  8  9 10 11   2  3  4  5  6  7  8   2  3  4  5  6  7  8
+12 13 14 15 16 17 18   9 10 11 12 13 14 15   9 10 11 12 13 14 15
+19 20 21 22 23 24 25  16 17 18 19 20 21 22  16 17 18 19 20 21 22
+26 27 28 29 30 31m    23 24 25 26 27 28m    23 24 25 26 27 28 29
+                                            30m31
+
+       April                  May                   June
+       1  2  3  4  5               1  2  3   1d 2d 3  4d
+ 6  7  8  9 10 11 12   4  5  6  7  8  9 10
+13 14 15 16 17 18 19  11 12 13 14 15 16 17
+20 21 22 23 24 25 26  18 19 20 21 22 23 24
+27 28 29 30m          25 26 27 28 29d30d31d
+
+
+List view
+---------
+
+--keep-daily 1w    --keep-monthly 5m    --keep-yearly 2
+--------------------------------------------------------------
+1. 2026-06-04      1. 2026-04-30        1. 2025-12-31
+2. 2026-06-02      2. 2026-03-30        2. 2025-11-15 (oldest)
+3. 2026-06-01      3. 2026-02-28
+4. 2026-05-31      4. 2026-01-31
+5. 2026-05-30
+6. 2026-05-29
+
+
+Notes
+-----
+
+2026-06-03 was skipped, so no archive on that day. No compensation is made for
+this, so the "daily" rule simply keeps one fewer archive. 2026-05-28 16:00 is
+exactly one week before `--since` and so would be excluded and pruned in this
+prune run.
+
+2026-03-31 was skipped, so 2026-03-30 is the monthly candidate for that month.
+2025-12-31 16:00 is exactly 5 months (5 * 31 days) from today and so that day's
+archive is no longer kept by the "monthly" rule but instead is now kept as the
+first true yearly candidate.
+
+Since interval rules define time windows rather than competing for a fixed
+number of slots, their interplay is simpler than count-based rules. An archive
+is kept by an interval rule as long as it falls within the specified window;
+the next rule simply considers whatever remains.
+
+Intervals and counts can be mixed freely. Yearly retention in this example is
+done by retention count instead of intervals. A count rule paired with interval
+rules behaves just as it would if all preceding rules were also counts:
+Archives already kept by earlier rules are excluded from consideration. In this
+example there is only one "true" yearly candidate, so the oldest archive at
+2025-11-15 is kept. This oldest archive will be kept until the rolling backup
+scheme reaches "steady state" (when all retention rules are fully satisfied).

docs/misc/prune-example.txt

@@ -1,18 +1,17 @@
 borg prune visualized
 =====================
 
-Assume it is 2016-01-01. Today's backup has not yet been made. You have
-created at least one backup on each day in 2015 except on 2015-12-19 (no
+Assume it is 2016-01-01. Today's archive has not yet been made. You have
+created at least one archive on each day in 2015 except on 2015-12-19 (no
 backup was made on that day), and you started backing up with Borg on
 2015-01-01.
 
 This is what borg prune --keep-daily 14 --keep-monthly 6 --keep-yearly 1
 would keep.
 
-Backups kept by the --keep-daily rule are marked by a "d" to the right,
-backups kept by the --keep-monthly rule are marked by a "m" to the right,
-and backups kept by the --keep-yearly rule are marked by a "y" to the
-right.
+Archives kept by the --keep-daily rule are marked by a "d" to the right,
+archives kept by the --keep-monthly rule are marked by a "m" to the right, and
+archives kept by the --keep-yearly rule are marked by a "y" to the right.
 
 Calendar view
 -------------
@@ -71,7 +70,7 @@ List view
 10. 2015-12-22
 11. 2015-12-21
 12. 2015-12-20
-    (no backup made on 2015-12-19)
+    (no archive made on 2015-12-19)
 13. 2015-12-18
 14. 2015-12-17
 
@@ -82,45 +81,49 @@ Notes
 2015-12-31 is kept due to the --keep-daily 14 rule (because it is applied
 first), not due to the --keep-monthly or --keep-yearly rule.
 
-The --keep-yearly 1 rule does not consider the December 31st backup because it
-has already been kept due to the daily rule. There are no backups available
-from previous years, so the --keep-yearly target of 1 backup is not satisfied.
-Because of this, the 2015-01-01 archive (the oldest archive available) is kept.
+Rules are applied in the order given: archives already kept by an earlier
+rule are excluded from consideration by later rules.
+
+The --keep-yearly 1 rule does not consider the December 31st archive because it
+has already been kept due to the daily rule. There are no archives from
+previous years, so there are no "true" yearly candidates. The oldest archive at
+2015-01-01 fills the remaining slot and will be kept until the rolling backup
+scheme reaches "steady state" (when all retention rules are fully satisfied).
 
 The --keep-monthly 6 rule keeps Nov, Oct, Sep, Aug, Jul and Jun. December is
-not considered for this rule, because that backup was already kept because of
+not considered for this rule, because that archive was already kept because of
 the daily rule.
 
-2015-12-17 is kept to satisfy the --keep-daily 14 rule, because no backup was
-made on 2015-12-19. If a backup had been made on that day, it would not keep
-the one from 2015-12-17.
+2015-12-17 is kept to satisfy the --keep-daily 14 rule, because no archive was
+made on 2015-12-19. If an archive had been made on that day, it would not keep
+the archive from 2015-12-17.
 
 We did not include weekly, hourly, minutely, or secondly rules to keep this
 example simple. They all work in basically the same way.
 
 The weekly rule is easy to understand roughly, but hard to understand in all
 details. If you are interested, read "ISO 8601:2000 standard week-based year".
 
-The 13weekly and 3monthly rules are two different strategies for keeping one backup
-every quarter of a year. There are `multiple ways` to define a quarter-year;
-borg prune recognizes two:
+The 13weekly and 3monthly rules are two different strategies for keeping one
+archive every quarter of a year. There are `multiple ways` to define a
+quarter-year; borg prune recognizes two:
 
-* --keep-13weekly keeps one backup every 13 weeks using ISO 8601:2000's
+* --keep-13weekly keeps one archive every 13 weeks using ISO 8601:2000's
   definition of the week-based year. January 4th is always included in the
   first week of a year, and January 1st to 3rd may be in week 52 or 53 of the
   previous year. Week 53 is also in the fourth quarter of the year.
-* --keep-3monthly keeps one backup every 3 months. January 1st to
-  March 31, April 1st to June 30th, July 1st to September 30th, and October 1st
-  to December 31st form the quarters.
+* --keep-3monthly keeps one archive every 3 months. January 1st to March 31,
+  April 1st to June 30th, July 1st to September 30th, and October 1st to
+  December 31st form the quarters.
 
 If the subtleties of the definition of a quarter-year don't matter to you, a
 short summary of behavior is:
 
-* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, Jul,
+* --keep-13weekly favors keeping archives at the beginning of Jan, Apr, Jul,
   and Oct.
-* --keep-3monthly favors keeping backups at the end of Dec, Mar, Jun, and Sep.
-* Both strategies will have some overlap in which backups are kept.
-* The differences are negligible unless backups considered for deletion were
+* --keep-3monthly favors keeping archives at the end of Dec, Mar, Jun, and Sep.
+* Both strategies will have some overlap in which archives are kept.
+* The differences are negligible unless archives considered for deletion were
   created weekly or more frequently.
 
 .. _multiple ways: https://en.wikipedia.org/wiki/Calendar_year#Quarter_year

docs/usage/general/date-time.rst.inc

@@ -10,9 +10,15 @@ Unless otherwise noted, we display local date and time.
 Internally, we store and process date and time as UTC.
 
 
-.. rubric:: TIMESPAN
+.. rubric:: TIMESPAN / INTERVAL
 
-Some options accept a TIMESPAN parameter, which can be given as a number of
-years (e.g. ``2y``), months (e.g. ``12m``), weeks (e.g. ``2w``),
-days (e.g. ``7d``), hours (e.g. ``8H``), minutes (e.g. ``30M``),
-or seconds (e.g. ``150S``).
+Some options accept a TIMESPAN or an INTERVAL parameter, which can be given as
+a number of years (e.g. ``2y``), months (e.g. ``12m``), weeks (e.g. ``2w``),
+days (e.g. ``7d``), hours (e.g. ``8H``), minutes (e.g. ``30M``), or seconds
+(e.g. ``150S``).
+
+The ``borg prune`` ``--keep-*`` retention options accept either a plain count
+(e.g. ``--keep-daily 7``, keeping up to 7 daily archives) or a time interval
+(e.g. ``--keep-daily 7d``, keeping one daily archive per day within a 7-day window).
+When using interval-based retention, ``--since`` may be specified to set the
+reference timestamp for the interval (defaults to the current time).

docs/usage/prune.rst

@@ -23,6 +23,13 @@ first, so you will see what it would do without it actually doing anything.
 
 Do not forget to run ``borg compact -v`` after prune to actually free disk space.
 
+The ``--keep-*`` options accept either a **count** (e.g. ``--keep-daily 7``) or
+a **time interval** (e.g. ``--keep-daily 7d``). A count keeps up to *N* archives
+per period (e.g. the last 7 daily archives), while an interval keeps one
+archive per period within that time span (e.g. one daily archive per day in the
+last 7-day window). When using intervals, you may also specify ``--since`` to
+set the reference timestamp for interval calculation.
+
 ::
 
     # Keep 7 end of day and 4 additional end of week archives.
@@ -44,8 +51,24 @@ Do not forget to run ``borg compact -v`` after prune to actually free disk space
     # and an end of month archive for every month:
     $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1
 
-There is also a visualized prune example in ``docs/misc/prune-example.txt``:
+    # Keep daily archives from the last 7 days:
+    $ borg prune -v --list --dry-run --keep-daily=7d
+
+    # Same as above, but with a fixed reference timestamp:
+    $ borg prune -v --list --dry-run --since 2025-12-01T00:00:00+02:00 --keep-daily=7d
+
+    # Keep the last 14 archives using `--keep` (same as `--keep-last 14`):
+    $ borg prune -v --list --dry-run --keep 14
+
+    # Keep all archives from the last 30 days using `--keep` (same as `--keep-within 30d`):
+    $ borg prune -v --list --dry-run --keep 30d
+
+There are also visualized prune examples in ``docs/misc/prune-example.txt`` and
+``docs/misc/prune-example-interval.txt``:
 
 .. highlight:: none
 .. include:: ../misc/prune-example.txt
     :literal:
+
+.. include:: ../misc/prune-example-interval.txt
+    :literal: