Merge pull request #1212 from ThomasWaldmann/prune-example

add prune visualization / example, fixes #723

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".

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.