Refactor the interval-based pruning example

[PhrozenByte]

See my review on borgbackup#8775

[Goddesen]

"at or after" ensuring the week-old archive is kept isn't quite right since the interval end is compared exclusively to the archive time (and archive time is at the start of the create call). With microsecond precision this might not matter in most cases, but it's worth clearing up either this text and the example -- or maybe this is an argument to make the comparison inclusive such that this wording works.

I think that the exclusive check is technically right, but in practice it might be too much hassle for users.

[PhrozenByte]

Good point, fixed 👍

I think it's perfectly reasonable to keep the check exclusive. If the behavior doesn't match what someone expects, they can simply choose a different value for --since.

Honestly, I think --since solves all the weird edge cases we've struggled with in the past. That's why I'm a big fan of your idea to add this option.

[Goddesen]

I think an extra intro paragraph to set up the scenario is nice. Just launching into "you start your backups" is a bit abrupt.

Suggested change

	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, `create` took a little longer than usual. It's 16:12 now and you
	run `prune`.
	Scenario: You use borg to perform daily backups. The changes day-to-day are less
	important as time goes on, so to save some storage space you have the older
	archives "thin out" over time while keeping most of the recent archives. Your
	backup script does `borg create ...` followed immediately by `borg prune ...`.
	Assume today is 2026-06-04 and you 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`.

[PhrozenByte]

True, merged 👍

I just kept the "always", because it implies more or less consistent timing.

[Goddesen]

These are good suggestions. If you agree with my comments I'll merge it right in.

[PhrozenByte]

Suggestions applied, thanks 👍

However, there's one issue now following our discussion in the main PR: If we keep treating 5m as 155d for now, 2025-12-31 ends up being matched by --keep-monthly instead.

I guess we have three options:

1. Just leave the example as-is until the follow-up PR.
2. Update the docs to explain that 2025-12-31 is indeed matched by --keep-monthly instead.
3. Adjust the example so that "today" is, for example, 2026-06-05 instead.

[Goddesen]

I guess we have three options:

1. Just leave the example as-is until the follow-up PR.
2. Update the docs to explain that 2025-12-31 is indeed matched by `--keep-monthly` instead.
3. Adjust the example so that "today" is, for example, `2026-06-05` instead.

I'm hesitant to knowingly commit a wrongful example even just for a little bit, in case we somehow never get around to fixing it (or we forget). Could you include a fix here? I think your no. 2 is the least work.

[PhrozenByte]

Done 👍

I also added a note about this behavior to the main date interval docs.

I later force-pushed another change to add a note about years as well. Users are probably less likely to run into that case, but Borg also considers 3y before 2026-06-04 to be 2023-06-05 (not 2023-06-04, because of the 2024 leap year).

[Goddesen]

@PhrozenByte Thanks for the help.