Prune by either int or interval for all retention policies

docs/misc/prune-example-interval.txt

@@ -0,0 +1,149 @@
+borg prune visualized (count and interval mixed)
+================================================================================
+
+Scenario: You use borg to perform daily backups. As backups age, the day-to-day
+changes become less important, so to save storage space you want older archives
+to "thin out" over time while retaining most recent archives. Your backup
+script runs `borg create`, immediately followed by `borg prune`.
+
+Assume today is 2026-06-04 and you always start your backups at 16:00. You have
+been creating backup archives starting at 16:00 on most days going back to late
+2025. Today, `borg create` took a little longer than usual. It's 16:12 now and
+you run `borg prune`.
+
+You want Borg to keep one archive per day for one week, four weekly archives,
+one archive per month for five months, and two yearly backups. For that, you
+use the following command:
+
+```
+borg prune \
+  --keep-daily 1w \
+  --keep-weekly 4 \
+  --keep-monthly 5m \
+  --keep-yearly 2 \
+  --since '2026-06-04 16:00'
+```
+
+The `--keep-*` options reflect the intended retention policy exactly. Note the
+different wording in the retention policy for weekly and yearly archives: They
+aren't *interval*-based, but *count*-based.
+
+Another important detail here is `--since`. Without it, intervals would be
+calculated relative to the actual start time of `prune` - in this case 16:12.
+Since your backups are always created at 16:00, this 12-minute shift would move
+the cutoff point of intervals and could cause archives near the boundary to
+unexpectedly fall outside the expected time window.
+
+By specifying `--since '2026-06-04 16:00'`, all intervals are anchored to the
+intended reference time (16:00), not the moment `prune` happens to run. This
+ensures stable and predictable retention behavior, independent of when `prune`
+actually runs.
+
+The first archive was made on 2025-11-15. You missed the backups on 2026-03-31,
+2026-05-24, and 2026-06-03.
+
+Below you find an overview of what archives `prune` will keep.
+
+Archives kept by the `--keep-daily` rule are marked by a "d" to the right,
+archives kept by the `--keep-weekly` rule are marked by a "w" to the right,
+archives kept by the `--keep-monthly` rule are marked by a "m" to the right,
+archives kept by the `--keep-yearly` rule are marked by a "y" to the right, and
+archives kept by the `--since` rule are marked by a "x" to the right.
+
+
+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 31m
+
+                            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  3w  1d 2d 3  4x
+ 6  7  8  9 10 11 12   4  5  6  7  8  9 10w
+13 14 15 16 17 18 19  11 12 13 14 15 16 17w
+20 21 22 23 24 25 26  18 19 20 21 22 23w24
+27 28 29 30m          25 26 27 28d29d30d31d
+
+
+List view
+---------
+
+--keep-daily 1w     --keep-weekly 4     --keep-monthly 5m   --keep-yearly 2
+--------------------------------------------------------------------------------
+                                                            1. 2025-11-15 (oldest)
+1. 2026-06-02       1. 2026-05-23       1. 2026-04-30
+2. 2026-06-01       2. 2026-05-17       2. 2026-03-30
+3. 2026-05-31       3. 2026-05-10       3. 2026-02-28
+4. 2026-05-30       4. 2026-05-03       4. 2026-01-31
+5. 2026-05-29                           5. 2025-12-31
+6. 2026-05-28
+
+2026-06-04 is additionally kept due to `--since`.
+
+
+Notes
+-----
+
+The current day's archive is always kept, because `create` ran after the date
+given with `--since`. For `prune`, it's as if this archive doesn't exist (yet).
+
+2026-06-03 was skipped, so no archive can be kept with `--keep-daily` for that
+day. Other than with a *count*-based policy, no compensation is made for an
+*interval* like `--keep-daily 1w`, so the rule simply keeps one archive fewer.
+
+2026-05-28 16:00 is exactly one week before `--since`. Since `create` always
+runs after 16:00, the archive created on 2026-05-28 is kept, too. Without
+`--since`, Borg would cut off at 2026-05-28 16:12 instead, which would likely
+mean that the archive created on 2026-05-28 would be pruned. `--since` ensures
+that 2026-05-28 is consistently kept. If you want it consistently pruned, try a
+later reference time, e.g. `--since '2026-06-04 23:59:59'`.
+
+2026-05-31 is considered not only by `--keep-daily`, but by `--keep-weekly`
+and `--keep-monthly`, too. The archive is effectively kept by `--keep-daily`,
+but how this affects other rules differs between *count*- and *interval*-based
+policies. For *interval*-based rules like `--keep-monthly 5m` it has no effect:
+The rule simply keeps one archive fewer.
+
+For *count*-based rules like `--keep-weekly 4` it has an effect: The policy
+tells Borg to keep 4 weekly archives, and if 2026-05-31 is kept by another
+rule already, Borg compensates by keeping an older archive instead.
+Consequently, Borg will also keep the 2026-05-03 archive.
+
+Since 2026-05-24 and 2026-03-31 were skipped, there are no perfect candidates
+for that week and month. Borg chooses the next best candidate, so it keeps
+2026-05-23 as the weekly and 2026-03-30 as the monthly candidate.
+
+The implementation of `--keep-monthly 5m` is somewhat special: Borg defines a
+month as a fixed 31-day period, independent of the actual calendar dates
+involved. As a result, `5m` corresponds to 5 × 31 = 155 days. The archive from
+2025-12-31 16:00 is exactly 155 days older than the reference time and is
+therefore retained by `--keep-monthly`.
+
+As a result, there are no true yearly candidates. In the absence of a better
+candidate, `--keep-yearly 2` only matches the oldest archive, 2025-11-15.
+
+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,20 @@ 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).
+
+Please note that Borg treats months (e.g. ``12m``) as fixed 31-day periods
+rather than calendar months. As a result, ``12m`` corresponds to
+12 × 31 = 372 days. Similarly, years (e.g. ``2y``) are treated as fixed
+365-day periods and do not take leap years into account.

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.
@@ -42,10 +49,26 @@ Do not forget to run ``borg compact -v`` after prune to actually free disk space
 
     # Keep all backups in the last 10 days, 4 additional end of week archives,
     # and an end of month archive for every month:
-    $ borg prune -v --list --keep-within=10d --keep-weekly=4 --keep-monthly=-1
+    $ borg prune -v --list --keep=10d --keep-weekly=4 --keep-monthly=-1
+
+    # 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`:
+    $ borg prune -v --list --dry-run --keep 14
 
-There is also a visualized prune example in ``docs/misc/prune-example.txt``:
+    # Keep all archives from the last 30 days using `--keep`:
+    $ 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: