X-Git-Url: http://git.tuebingen.mpg.de/?p=dss.git;a=blobdiff_plain;f=dss.ggo;h=8dd7090b19c857aeb83c4ecd4cfda8d86f8f7a7b;hp=fe44aad9e78e94d1fce3bc63584910e5072d125b;hb=a31c35b86e485c6c1feeaf9e1957e3d3ab52c7e5;hpb=5690c1d32dd5de8419f2f0f37e4f075d7c2fb49d

diff --git a/dss.ggo b/dss.ggo
index fe44aad..8dd7090 100644
--- a/dss.ggo
+++ b/dss.ggo
@@ -1,33 +1,8 @@
-
-text "
-dss snapshot aging is implemented in terms of intervals. There are
-two command line options related to intervals: the duration of a
-'unit' interval and the number of those intervals.
-
-dss removes any snapshots older than the given number of intervals
-times the duration of an unit interval and tries to keep the following
-amount of snapshots per interval:
-
-	interval number		number of snapshots
-	===============================================
-	0	 		2 ^ (num_intervals - 1)
-	1			2 ^ (num_intervals - 2)
-	2			2 ^ (num_intervals - 3)
-	...
-	num_intervals - 2			2
-	num_intervals - 1			1
-	num_intervals				0
-
-In other words, the oldest snapshot will at most be unit_interval *
-num_intervala old (= 5 days * 4 = 20 days if default values are used).
-Moreover, there are at most 2^num_intervals - 1 snapshots in total
-(i.e. 31 by default).  Observe that you have to create at least
-num_intervals snapshots each interval for this to work out.  "
-
-
-
+#
 package "dss"
 version "0.0.1"
+purpose "the dyadic snapshot scheduler"
+
 
 option "config_file" c
 #~~~~~~~~~~~~~~~~~~~~~
@@ -48,14 +23,80 @@ option "loglevel" l
 	default="4"
 	optional
 
-option "logfile" L
-#~~~~~~~~~~~~~~~~~~
+option "logfile" -
+#~~~~~~~~~~~~~~~~~
 
 "logfile for the dss daemon process"
 
 	string typestr="filename"
 	optional
 
+option "daemon" d
+#~~~~~~~~~~~~~~~~
+"run as background daemon"
+flag off
+dependon="logfile"
+details="
+	Note that dsss refuses to start in daemon mode if no logfile
+	was specified.
+"
+
+option "dry_run" D
+#~~~~~~~~~~~~~~~~~
+"only print what would be done"
+flag off
+details="
+	This flag does not makes sense for all commands. The run
+	command refuses to start if this option was given. The ls
+	command silently ignores this flag.
+"
+
+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
+
+groupoption "create" C
+#~~~~~~~~~~~~~~~~~~~~~
+"create a new snapshot"
+group="command"
+details="
+	Execute the rsync command to create a new snapshot.Mote that this
+	command does not care about free disk space.
+"
+groupoption "prune" P
+#~~~~~~~~~~~~~~~~~~~~
+"remove a redundant snapshot"
+group="command"
+details="
+	A snapshot is considered redundant if it ether belongs to
+	an interval greater than the maximum nuber of intervals,
+	or if it belongs to an interval that already contains more
+	than the desired number of snapshots.
+"
+
+groupoption "ls" L
+#~~~~~~~~~~~~~~~~~
+"print a list of all snapshots"
+group="command"
+details="
+	The list will contain all snapshots not matter of their state,
+	i.e. incomplete snapshots and snapshots being deleted will
+	also be listed.
+"
+
+groupoption "run" R
+#~~~~~~~~~~~~~~~~~~
+"start creating and pruning snapshots"
+group="command"
+details="
+	This is the main mode of operation. Snapshots will be created
+	as needed and pruned automatically.
+"
+
 section "rsync-related options"
 #==============================
 
@@ -76,7 +117,7 @@ option "remote_host" H
 	default="localhost"
 	optional
 
-option "source_dir" S
+option "source_dir" -
 #~~~~~~~~~~~~~~~~~~~~
 
 "directory to backup on the remote host"
@@ -84,7 +125,7 @@ option "source_dir" S
 	string typestr="dirname"
 	optional
 
-option "dest_dir" D
+option "dest_dir" -
 #~~~~~~~~~~~~~~~~~~
 
 "snapshots dir on the local host"
@@ -115,6 +156,30 @@ option "exclude_patterns" e
 section "Intervals"
 #~~~~~~~~~~~~~~~~~~
 
+text "
+dss snapshot aging is implemented in terms of intervals. There are
+two command line options related to intervals: the duration of a
+'unit' interval and the number of those unit intervals.
+
+dss removes any snapshots older than the given number of intervals
+times the duration of an unit interval and tries to keep the following
+number of snapshots per interval:
+
+	interval number		number of snapshots
+	===============================================
+	0	 		2 ^ (num_intervals - 1)
+	1			2 ^ (num_intervals - 2)
+	2			2 ^ (num_intervals - 3)
+	...
+	num_intervals - 2			2
+	num_intervals - 1			1
+	num_intervals				0
+
+In other words, the oldest snapshot will at most be unit_interval *
+num_intervala old (= 5 days * 4 = 20 days if default values are used).
+Moreover, there are at most 2^num_intervals - 1 snapshots in total
+(i.e. 31 by default).  Observe that you have to create at least
+num_intervals snapshots each interval for this to work out.  "
 
 option "unit_interval" u
 #~~~~~~~~~~~~~~~~~~~~~~~
@@ -196,27 +261,3 @@ details="
 	dss will start to remove snapshots (starting from the oldest
 	snapshot) until the free disk space exeecds this value.
 "
-
-
-text "
-subcommands:
-
-ls:
-
-	Print list of existing snapshots.
-
-	Usage: ls
-
-free:
-
-	Remove old snapshots in order to free space.
-
-	Usage: free [size]
-
-	Without size parameter, print the amount of free space on the file system
-	in human-readable format.
-
-	Otherwise, remove snapshots (starting from the oldest one) until the number of
-	free space exceeds the given number of gigabytes.
-	Use with caution!
-"