Add dss.1 and dss.1.html to .gitignore.
[dss.git] / dss.ggo
diff --git a/dss.ggo b/dss.ggo
index 6e222d2..7afa4ca 100644 (file)
--- a/dss.ggo
+++ b/dss.ggo
@@ -1,6 +1,9 @@
+# Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
 #
+# Licensed under the GPL v2. For licencing details see COPYING.
+
 package "dss"
-version "0.0.3"
+version "0.1.0"
 purpose "the dyadic snapshot scheduler
 
 dss creates hardlink-based snapshots of a given directory on a remote
@@ -79,12 +82,17 @@ details="
        is also given.
 "
 
+##################
+section "Commands"
+##################
+
 defgroup "command"
 #=================
 groupdesc="
        dss supports a couple of commands each of which corresponds
        to a different command line option. Exactly one of these
        options must be given.
+
 "
 required
 
@@ -99,13 +107,14 @@ details="
 
 groupoption "prune" P
 #~~~~~~~~~~~~~~~~~~~~
-"Remove a redundant snapshot"
+"Remove redundant and outdated snapshots"
 group="command"
 details="
-       A snapshot is considered redundant if it ether belongs to
-       an interval greater than the maximum number of intervals,
-       or if it belongs to an interval that already contains more
-       than the desired number of snapshots.
+       A snapshot is considered outdated if it belongs to an interval
+       greater than the maximum number of intervals. It is said to be
+       redundant if it belongs to an interval that already contains
+       more than the desired number of snapshots. This command gets
+       rid of such snapshots.
 "
 
 groupoption "ls" L
@@ -124,7 +133,9 @@ groupoption "run" R
 group="command"
 details="
        This is the main mode of operation. Snapshots will be created
-       as needed and pruned automatically.
+       in an endless loop as needed and pruned automatically. The loop
+       only terminates on fatal errors or if a terminating signal was
+       received. See also the --exit-hook option.
 "
 
 ###############################
@@ -188,12 +199,6 @@ details="
        to that option are passed verbatim to the rsync command.
 "
 
-option "exclude-patterns" e
-#~~~~~~~~~~~~~~~~~~~~~~~~~~
-"Rsync exclude patterns"
-string typestr="path"
-optional
-
 ###################
 section "Intervals"
 ###################
@@ -211,13 +216,14 @@ details="
        unit intervals.
 
        dss removes any snapshots older than n times u and tries to
-       keep 2^(k-1) snapshots in interval k, where the interval number
-       k counts from zero, zero being the most recent unit interval.
+       keep 2^(n - k - 1) snapshots in interval k, where the interval
+       number k counts from zero, zero being the most recent unit
+       interval.
 
        In other words, the oldest snapshot will at most be u * n days
        (= 20 days if default values are used) old.  Moreover, there
        are at most 2^n - 1 snapshots in total (i. e. 31 by default).
-       Observe that you have to create at least 2 ^ (n - 1) snapshots
+       Observe that you have to create at least 2^(n - 1) snapshots
        each interval for this to work out because that is the number
        of snapshots in interval zero.
 "
@@ -258,13 +264,29 @@ string typestr="command"
 optional
 details="
        Execute this after a snapshot has successfully been
-       created. The full path of the newly created snapshot is passed
-       to the hook as the first argument.  The return value of that
-       hook is ignored.
+       created. The full path of the newly created snapshot is
+       passed to the hook as the first argument.  The exit code of
+       this hook is ignored.
 
        For instance this hook can be used to count the number of
        files per user and/or the disk usage patterns in order to
-       store them in a database for further treatment.
+       store them in a database for further analysis.
+"
+
+option "exit-hook" e
+#~~~~~~~~~~~~~~~~~~~
+"Executed if run command exits"
+string typestr="command"
+optional
+details="
+       This hook is only used if the --run command was given which
+       instructs dss to run in an endless loop. The exit-hook gets
+       executed whenever this endless loop terminates. The reason
+       for terminating the loop is passed as the first argument.
+
+       One possible application for this hook is to send email to the
+       system administrator to let her know that no more snapshots
+       are going to be created.
 "
 
 ###############################
@@ -278,15 +300,15 @@ int typestr="megabytes"
 default="100"
 optional
 details="
-       If less than this many megabytes of space is available on
-       the file system containing the destination directory, \"dss
-       --run\" will suspend the currently running rsync process and will
-       start to remove snapshots, starting from the oldest snapshot,
-       until the free disk space exceeds this value.  See also the
-       --min_free_percent option.
+       If disk space on the file system containing the destination
+       directory gets low, \"dss --run\" will suspend the currently
+       running rsync process and will start to remove snapshots in
+       order to free disk space. This option specifies the minimal
+       amount of free disk space. If less than the given number of
+       megabytes is available, snapshots are being deleted. See also
+       the --min_free_percent and the min-free-percent-inodes options.
 
        A value of zero deactivates this check.
-
 "
 
 option "min-free-percent" p
@@ -296,7 +318,40 @@ int typestr="percent"
 default="2"
 optional
 details="
-       See --min-free-mb.  Note that it is not recommended to set both
+       See --min-free-mb. Note that it is not recommended to set both
        --min-free-mb and --min-free-percent to zero as this will
        cause your file system to fill up quickly.
 "
+option "min-free-percent-inodes" i
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"Minimal percent of free inodes"
+int typestr="percent"
+default="0"
+optional
+details="
+       Specify the minimum amount of free inodes on the file system
+       containing the destination dir. If less than that many inodes
+       are free, snapshot removal kicks in just as in case of low
+       disk space.
+
+       Note that not every file system supports the concept of inodes.
+       Moreover it is not possible to reliably detect whether this is
+       the case. Therefore this feature is disabled by default. It's
+       safe to enable it for ext3 file systems on linux though.
+
+       A value of zero (the default) deactivates this check.
+"
+
+option "keep-redundant" k
+#~~~~~~~~~~~~~~~~~~~~~~~~
+"Prune by disk space only"
+flag off
+details="
+       If this flag is not given dss removes redundant and outdated
+       snapshots automatically.
+
+       Otherwise, this feature is deactivated so that snapshots
+       are only being removed in case disk space or inode ratio
+       becomes low. Use this flag if the file system containing the
+       destination directory is used for snapshots only.
+"