From c773c882b9a94cfa43693e5d98a184fe4e4824da Mon Sep 17 00:00:00 2001 From: Thomas Waldmann Date: Mon, 27 Jun 2016 21:20:12 +0200 Subject: [PATCH] add prune visualization / example, fixes #723 --- docs/misc/prune-example.txt | 93 +++++++++++++++++++++++++++++++++++++ docs/usage.rst | 2 + 2 files changed, 95 insertions(+) create mode 100644 docs/misc/prune-example.txt diff --git a/docs/misc/prune-example.txt b/docs/misc/prune-example.txt new file mode 100644 index 000000000..6c8f8e553 --- /dev/null +++ b/docs/misc/prune-example.txt @@ -0,0 +1,93 @@ +borg prune visualized +===================== + +Assume it is 2016-01-01, today's backup has not yet been made and you have +created at least one backup on each day in 2015 except on 2015-12-20 (no +backup made on that day). + +This is what borg prune --keep-daily 14 --keep-monthly 6 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. + +Calendar view +------------- + + 2015 + January February March +Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su + 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 31 23 24 25 26 27 28 23 24 25 26 27 28 29 + 30 31 + + April May June +Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su + 1 2 3 4 5 1 2 3 1 2 3 4 5 6 7 + 6 7 8 9 10 11 12 4 5 6 7 8 9 10 8 9 10 11 12 13 14 +13 14 15 16 17 18 19 11 12 13 14 15 16 17 15 16 17 18 19 20 21 +20 21 22 23 24 25 26 18 19 20 21 22 23 24 22 23 24 25 26 27 28 +27 28 29 30 25 26 27 28 29 30 31 29 30m + + + July August September +Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su + 1 2 3 4 5 1 2 1 2 3 4 5 6 + 6 7 8 9 10 11 12 3 4 5 6 7 8 9 7 8 9 10 11 12 13 +13 14 15 16 17 18 19 10 11 12 13 14 15 16 14 15 16 17 18 19 20 +20 21 22 23 24 25 26 17 18 19 20 21 22 23 21 22 23 24 25 26 27 +27 28 29 30 31m 24 25 26 27 28 29 30 28 29 30m + 31m + + October November December +Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su + 1 2 3 4 1 1 2 3 4 5 6 + 5 6 7 8 9 10 11 2 3 4 5 6 7 8 7 8 9 10 11 12 13 +12 13 14 15 16 17 18 9 10 11 12 13 14 15 14 15 16 17d18d19d20 +19 20 21 22 23 24 25 16 17 18 19 20 21 22 21d22d23d24d25d26d27d +26 27 28 29 30 31m 23 24 25 26 27 28 29 28d29d30d31d + 30m + +List view +--------- + +--keep-daily 14 --keep-monthly 6 +------------------------------------------------- + 1. 2015-12-31 (2015-12-31 kept by daily rule) + 2. 2015-12-30 1. 2015-11-30 + 3. 2015-12-29 2. 2015-10-31 + 4. 2015-12-28 3. 2015-09-30 + 5. 2015-12-27 4. 2015-08-31 + 6. 2015-12-26 5. 2015-07-31 + 7. 2015-12-25 6. 2015-06-30 + 8. 2015-12-24 + 9. 2015-12-23 +10. 2015-12-22 +11. 2015-12-21 + (no backup made on 2015-12-20) +12. 2015-12-19 +13. 2015-12-18 +14. 2015-12-17 + + +Notes +----- + +2015-12-31 is kept due to the --keep-daily 14 rule (because it is applied +first), not due to the --keep-monthly rule. + +Because of that, 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 the daily rule. + +2015-12-17 is kept to satisfy the --keep-daily 14 rule - because no backup was +made on 2015-12-20. If a backup had been made on that day, it would not keep +the one from 2015-12-17. + +We did not include yearly, 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 interested, read "ISO 8601:2000 standard week-based year". diff --git a/docs/usage.rst b/docs/usage.rst index acca302ac..b7863d9a9 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -419,6 +419,8 @@ prefix "foo" if you do not also want to match "foobar". It is strongly recommended to always run ``prune --dry-run ...`` first so you will see what it would do without it actually doing anything. +There is also a visualized prune example in ``docs/misc/prune-example.txt``. + :: # Keep 7 end of day and 4 additional end of week archives.