Merge topic branch t/misc into pu

[dss.git] / dss.suite

diff --git a/dss.suite b/dss.suite
index 16c7e58542eff8750c8437dcea137f347a435950..6d1ed4ab0dd4f5a47eb10c720f5fff5869ac5914 100644 (file)
--- a/dss.suite
+++ b/dss.suite
@@ -450,19 +450,38 @@ caption = Subcommands
                snapshots.
        [/description]
 [subcommand prune]
-       purpose = remove redundant and outdated snapshots
+       purpose = remove snapshots
        [description]
-               A snapshot is considered outdated if its interval number is greater or
-               equal than the specified number of unit intervals. See --unit-interval
-               and --num-intervals above.
-
-               A snapshot is said to be redundant if the interval it belongs to
-               contains more than the configured number of snapshots.
-
-               The prune command gets rid of both outdated and redundant snapshots. At
-               most one snapshot is removed per invocation. If --dry-run is given, the
-               subcommand only prints the snapshot that would be removed.
+               A snapshot is said to be (a) outdated if its interval number is greater
+               or equal than the specified number of unit intervals, (b) redundant if
+               the interval it belongs to contains more than the configured number of
+               snapshots, and (c) orphaned if it is incomplete and not being created
+               or deleted. All other snapshots are called regular.
+
+               Unless --dry-run is given, which just prints the snapshot that would be
+               removed, this subcommand gets rid of non-regular snapshots.  At most
+               one snapshot is removed per invocation. If no such snapshot exists
+               and disk space is low, the subcommand also removes regular snapshots,
+               always picking the oldest one.
+
+               The subcommand fails if there is another dss "run" process.
        [/description]
+       [option disk-space]
+               summary = act as if free disk space was high/low
+               arg_info = required_arg
+               arg_type = string
+               typestr = mode
+               values = {
+                       FDS_CHECK = "check",
+                       FDS_HIGH = "high",
+                       FDS_LOW = "low"
+               }
+               default_val = check
+               [help]
+                       By default, free disk space is checked and even regular snapshots
+                       become candidates for removal if disk space is low. This option
+                       overrides the result of the check.
+               [/help]
 [subcommand ls]
        purpose = print the list of all snapshots
        [description]
@@ -521,6 +540,27 @@ caption = Subcommands
                exits successfully or prints information about the first syntax error
                detected and terminates with exit code 1.
        [/description]
+[subcommand help]
+       purpose = list available subcommands or print subcommand-specific help
+       non-opts-name = [subcommand]
+       [description]
+               Without any arguments, help prints the list of available
+               subcommands. When called with a subcommand name argument, it prints
+               the help text of the given subcommand.
+       [/description]
+       [option long]
+               short_opt = l
+               summary = show the long help text
+               [help]
+                       If the optional argument is supplied, the long help text contains the
+                       synopsis, the purpose and the description of the specified subcommand,
+                       followed by the option list including summary and help text of each
+                       option. Without --long, the short help is shown instead. This omits
+                       the description of the subcommand and the option help.
+
+                       If no subcommand is supplied but --long is given, the list contains the
+                       purpose of each subcommand.
+               [/help]
 
 [section copyright]
        Written by Andre Noll