Skip to content

Commit

Permalink
Add help for new quarterly prune options.
Browse files Browse the repository at this point in the history
  • Loading branch information
@cr1901
cr1901 committed Aug 19, 2024
1 parent a555f67 commit e4347e6
Show file tree
Hide file tree
Showing 3 changed files with 48 additions and 10 deletions.
24 changes: 24 additions & 0 deletions docs/misc/prune-example.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
22 changes: 16 additions & 6 deletions docs/usage/prune.rst.inc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ borg prune
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``REPOSITORY`` | repository to prune |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| **optional arguments** |
| **options** |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
| | ``-n``, ``--dry-run`` | do not change repository |
+-----------------------------------------------------------------------------+---------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------+
Expand All @@ -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 |
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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
Expand Down
12 changes: 8 additions & 4 deletions src/borg/archiver.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit e4347e6

Please sign in to comment.