From e4347e67a2fbb3670fae609d6b1010f84cac1189 Mon Sep 17 00:00:00 2001 From: "William D. Jones" Date: Mon, 19 Aug 2024 14:49:48 -0400 Subject: [PATCH] Add help for new quarterly prune options. --- docs/misc/prune-example.txt | 24 ++++++++++++++++++++++++ docs/usage/prune.rst.inc | 22 ++++++++++++++++------ src/borg/archiver.py | 12 ++++++++---- 3 files changed, 48 insertions(+), 10 deletions(-) diff --git a/docs/misc/prune-example.txt b/docs/misc/prune-example.txt index bc6bb209ac..e2f0606c55 100644 --- a/docs/misc/prune-example.txt +++ b/docs/misc/prune-example.txt @@ -100,3 +100,27 @@ 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 interested, read "ISO 8601:2000 standard week-based year". + +The 13weekly and 3monthly rules are two different strategies for keeping one +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 + 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. + +If the subtleties of the definition of a quarter year doesn't matter to you, +a short summary of behavior is: + +* --keep-13weekly favors keeping backups at the beginning of Jan, Apr, July, + and Oct. +* --keep-3montly favors keeping backups at the end of Dec, Mar, Jun, and Sept. +* Both strategies will have some overlap in which backups are kept. +* The differences are negligible unless backups considered for deletion were + created weekly or more frequently. + +.. _multiple ways: https://en.wikipedia.org/wiki/Calendar_year#Quarter_year diff --git a/docs/usage/prune.rst.inc b/docs/usage/prune.rst.inc index c57677bf7a..f2c6fbc276 100644 --- a/docs/usage/prune.rst.inc +++ b/docs/usage/prune.rst.inc @@ -17,7 +17,7 @@ borg prune +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | | ``REPOSITORY`` | repository to prune | +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ - | **optional arguments** | + | **options** | +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | | ``-n``, ``--dry-run`` | do not change repository | +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ @@ -41,6 +41,10 @@ borg prune +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | | ``-m``, ``--keep-monthly`` | number of monthly archives to keep | +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-13weekly`` | number of quarterly archives to keep (13 week strategy) | + +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ + | | ``--keep-3monthly`` | number of quarterly archives to keep (3 month strategy) | + +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | | ``-y``, ``--keep-yearly`` | number of yearly archives to keep | +-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+ | | ``--save-space`` | work slower, but using less space | @@ -72,7 +76,7 @@ borg prune repository to prune - optional arguments + options -n, --dry-run do not change repository --force force pruning of corrupted archives, use ``--force --force`` in case ``--force`` does not work. -s, --stats print statistics for the deleted archive @@ -84,6 +88,8 @@ borg prune -d, --keep-daily number of daily archives to keep -w, --keep-weekly number of weekly archives to keep -m, --keep-monthly number of monthly archives to keep + --keep-13weekly number of quarterly archives to keep (13 week strategy) + --keep-3monthly number of quarterly archives to keep (3 month strategy) -y, --keep-yearly number of yearly archives to keep --save-space work slower, but using less space -c SECONDS, --checkpoint-interval SECONDS write checkpoint every SECONDS seconds (Default: 1800) @@ -141,13 +147,17 @@ starts is used for pruning purposes. Dates and times are interpreted in the local timezone, and weeks go from Monday to Sunday. Specifying a negative number of archives to keep means that there is no limit. As of borg 1.2.0, borg will retain the oldest archive if any of the secondly, minutely, -hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet -its retention target. This enables the first chronological archive to continue -aging until it is replaced by a newer archive that meets the retention criteria. +hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise +able to meet its retention target. This enables the first chronological archive +to continue aging until it is replaced by a newer archive that meets the +retention criteria. + +The ``--keep-13weekly`` and ``--keep-3monthly`` rules are two different +strategies for keeping archives every quarter year. The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will keep the last N archives under the assumption that you do not create more than one -backup archive in the same second). +backup archive in the same second). When using ``--stats``, you will get some statistics about how much data was deleted - the "Deleted data" deduplicated size there is most interesting as diff --git a/src/borg/archiver.py b/src/borg/archiver.py index 6ec0ee02d7..5b2984aa39 100644 --- a/src/borg/archiver.py +++ b/src/borg/archiver.py @@ -4675,13 +4675,17 @@ def define_borg_mount(parser): the local timezone, and weeks go from Monday to Sunday. Specifying a negative number of archives to keep means that there is no limit. As of borg 1.2.0, borg will retain the oldest archive if any of the secondly, minutely, - hourly, daily, weekly, monthly, or yearly rules was not otherwise able to meet - its retention target. This enables the first chronological archive to continue - aging until it is replaced by a newer archive that meets the retention criteria. + hourly, daily, weekly, monthly, quarterly, or yearly rules was not otherwise + able to meet its retention target. This enables the first chronological archive + to continue aging until it is replaced by a newer archive that meets the + retention criteria. + + The ``--keep-13weekly`` and ``--keep-3monthly`` rules are two different + strategies for keeping archives every quarter year. The ``--keep-last N`` option is doing the same as ``--keep-secondly N`` (and it will keep the last N archives under the assumption that you do not create more than one - backup archive in the same second). + backup archive in the same second). When using ``--stats``, you will get some statistics about how much data was deleted - the "Deleted data" deduplicated size there is most interesting as