aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorIgor Pashev <pashev.igor@gmail.com>2019-10-05 21:54:27 +0200
committerIgor Pashev <pashev.igor@gmail.com>2019-10-05 22:02:27 +0200
commita65f7591894f67021df3490c07ab7e75627e476e (patch)
treea6137cfc9fa91c84c953e80e5a00a17b68a59640 /README.md
downloadfrotate.rs-a65f7591894f67021df3490c07ab7e75627e476e.tar.gz
Initial version 0.1.00.1.0
Diffstat (limited to 'README.md')
-rw-r--r--README.md89
1 files changed, 89 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..6e81c99
--- /dev/null
+++ b/README.md
@@ -0,0 +1,89 @@
+About
+=====
+
+*This is the [Rust](https://www.rust-lang.org/) version of
+[frotate](https://github.com/ip1981/frotate) ;)*
+
+
+`frotate` stands for "functional rotate", whatever.
+This is an evolution of the [log2rotate's ideas](http://jekor.com/log2rotate).
+See also [pylog2rotate](https://github.com/avian2/pylog2rotate).
+
+`frotate` is designed to rotate backups with any balance between retention
+and space usage. Instead of rotating backups using some familiar method such
+as daily, weekly, monthly, and yearly periods, it rotates backups using any
+periods. Thus "functional".
+
+The idea is simple, the rotation schedule is determined by an integer function.
+This function gives us a period (number) of days when we must encounter at
+least one backup or whatever we are rotating. When we use an exponential
+function, the scheme is similar to the radioactive decay law. When the
+function is simply a constant 1, we don't rotate anything and retain all
+the backups. If it is 2, we retain each second backup. With some trivial
+function we can achieve a well-known dayly-weekly-monthly-yearly scheme.
+
+The `frotate` command line utility implements only exponential periods with
+arbitrary base (ensure it is > 1, or have fun otherwise).
+
+
+Usage
+=====
+
+Note that when neither `--keep` nor `--delete` option is given, the utility
+prints all intervals with all days _to standard error_ and exits with non-zero
+code. In production you will need to specify `--keep` or `--delete` explicitly.
+
+```
+Usage: frotate [-k|-d] [-b <base>] <day>...
+ frotate --help
+
+Options:
+ -k --keep Print days to keep
+ -d --delete Print days to delete
+ -b --base <base> Base of the exponent [default: 1.1]
+ -h --help Show this help text
+
+```
+
+
+Example
+=======
+
+Different modes with the same days:
+
+```
+$ frotate --base 2 2019-08-31 2019-08-30 2019-08-29 2019-08-28 2019-08-27 2019-08-26 2019-08-25 2019-08-24
+2019-08-31
+2019-08-29 2019-08-30
+2019-08-25 2019-08-26 2019-08-27 2019-08-28
+2019-08-24
+
+$ frotate --keep --base 2 2019-08-31 2019-08-30 2019-08-29 2019-08-28 2019-08-27 2019-08-26 2019-08-25 2019-08-24
+2019-08-31 2019-08-29 2019-08-25 2019-08-24
+
+$ frotate --delete --base 2 2019-08-31 2019-08-30 2019-08-29 2019-08-28 2019-08-27 2019-08-26 2019-08-25 2019-08-24
+2019-08-30 2019-08-26 2019-08-27 2019-08-28
+```
+
+More or less realistic example when we keep some backups and get new ones, but not every day:
+
+```
+$ frotate --keep --base 2 2019-09-01 2019-08-31 2019-08-30 2019-08-28 2019-08-24
+2019-09-01 2019-08-30 2019-08-28 2019-08-24
+
+$ frotate --keep --base 2 2019-09-05 2019-09-01 2019-08-30 2019-08-28 2019-08-24
+2019-09-05 2019-08-30 2019-08-24
+
+$ frotate --keep --base 2 2019-09-06 2019-09-05 2019-08-30 2019-08-24
+2019-09-06 2019-09-05 2019-08-24
+
+$ frotate --keep --base 2 2019-09-07 2019-09-06 2019-09-05 2019-08-24
+2019-09-07 2019-09-05 2019-08-24
+
+$ frotate --keep --base 2 2019-09-08 2019-09-07 2019-09-06 2019-08-24
+2019-09-08 2019-09-06 2019-08-24
+
+$ frotate --keep --base 2 2019-09-09 2019-09-08 2019-09-06 2019-08-24
+2019-09-09 2019-09-08 2019-09-06 2019-08-24
+```
+