Merge branch 'refs/heads/t/doc-improvements'
[adu.git] / adu.ggo
diff --git a/adu.ggo b/adu.ggo
index ab6e025..643bbbf 100644 (file)
--- a/adu.ggo
+++ b/adu.ggo
@@ -1,10 +1,9 @@
-# Copyright (C) 2008 Andre Noll <maan@systemlinux.org>
+# Copyright (C) 2008 Andre Noll <maan@tuebingen.mpg.de>
 #
 # Licensed under the GPL v2. For licencing details see COPYING.
 
 package "adu"
-version "0.0.1"
-purpose "advanced disk usage
+purpose "
 
 adu creates a database containing disk usage statistics of a given
 directory. It allows to query that database to quickly retrieve
@@ -15,71 +14,55 @@ usage patterns of subdirectories and/or files owned by a given user id.
 section "General options"
 #########################
 
-option "config-file" c
-#~~~~~~~~~~~~~~~~~~~~~
-"(default='~/.adurc')"
-string typestr="filename"
-optional
-details="
-       Options may be given at the command line or in the
-       configuration file. As usual, if an option is given both at
-       the command line and in the configuration file, the command
-       line option takes precedence.
-
-"
-
-option "database-dir" d
-#~~~~~~~~~~~~~~~~~~~~~~
-"directory containing the osl tables"
-string typestr="path"
-required
-details="
-       Full path to the directory containing the osl tables. This
-       directory must exist. It must be writable for the user running
-       adu in --create mode and readable in --select mode.
-
-"
 option "loglevel" l
 #~~~~~~~~~~~~~~~~~~
 "Set loglevel (0-6)"
 int typestr="level"
-default="3"
+default="4"
 optional
 details="
        Log messages are always written to stderr while normal output
        goes to stdout. Lower values mean more verbose logging.
 "
 
-option "uid" u
-#~~~~~~~~~~~~~
-"user id(s) to take into account"
-string typestr="uid_spec"
-optional
-multiple
-details="
-       An uid specifier may be a single number, or a range of uids.
-       Example:
-
-       --uid 42    # only consider uid 42
-       --uid 42-   # only consider uids greater or equal than 42
-       --uid 23-42 # only consider uids between 23 and 42, inclusively.
-
-       This option may be given multiple times. An uid is taken into
-       account if it satisfies at least one --uid option.
+defgroup "database"
+#==================
+groupdesc="
+       There are two ways to specify a database directory. You can either
+       specify a full path using the database-dir option or a root path
+       using the database-root option. In the latter case, a directory
+       structure matching that of the base-dir argument is created
+       below the given full path.
+
+       The advantage of using database-root is that the base-dir is
+       used to find the relevant database both in create and select mode
+       and you do not have to care for setting the database-dir explicitly.
 "
 
+groupoption "database-dir" d
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"directory containing the osl tables"
+group="database"
+string typestr="path"
+details="
+       Full path to the directory containing the osl tables. This
+       directory is created if it does not exist. It must be writable for the
+       user running adu in --create mode and readable in --select mode.
+"
 
-option "paths" p
-#~~~~~~~~~~~~~~~
-"files to take into account"
-string typestr="pattern"
+groupoption "database-root" r
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"directory containing directories containing the osl tables"
+group="database"
+string typestr="path"
+default="/var/lib/adu"
+dependon="base-dir"
 optional
 details="
-       Shell wildcard pattern that must match a file in order to be
-       included in the database in --create mode or in the output
-       for --select mode. Only the part of the filename below the
-       base directory is matched against the pattern. The default
-       is to take all files into account. See fnmatch(3) for details.
+       Base path to the directory containing the osl tables. The real
+       database-dir is generated by appending base-dir. This
+       directory is created if it does not exist. When used in select
+       mode you have to specify the base-dir as well.
 "
 
 ###############
@@ -89,10 +72,9 @@ section "Modes"
 defgroup "mode"
 #==============
 groupdesc="
-       adu may started in one of two possible modes, each of which
-       corresponds to a different command line option. Exactly one
-       of these options must be given.
-
+       adu may be started in one of three possible modes, each of
+       which corresponds to a different command line option. Exactly
+       one of these options must be given.
 "
 required
 
@@ -101,10 +83,23 @@ groupoption "create" C
 "Create a new database"
 group="mode"
 details="
-       Traverse the given directory and track disk user on a per-user
-       basis. Results are stored in N + 1 osl tables where N is
-       the number of uids that own at least one regular file in
-       that directory.
+       Traverse the given directory and track disk usage on a
+       per-user basis. Results are stored in N + 1 osl tables where
+       N is the number of uids that own at least one regular file
+       in that directory.
+"
+
+groupoption "interactive" I
+#~~~~~~~~~~~~~~~~~~~~~~~~~~
+"activate interactive mode"
+group="mode"
+details="
+       In this mode, adu reads commands from stdin. This makes it
+       possible to run different select queries without opening the
+       underlying osl database for each query (which is expensive).
+
+       In interactive mode, several subcommands are available, see
+       the end of this document.
 "
 
 groupoption "select" S
@@ -112,8 +107,10 @@ groupoption "select" S
 "query a database previously created with --create"
 group="mode"
 details="
-       This option prints statistics about matching subdirectories to
-       stdout. The output depends on the other options, see below.
+       This option prints statistics about matching subdirectories
+       to stdout, to an output file or pipes the output to a given
+       command, depending on the --output option. The output format
+       can be customized by specifying select options, see below.
 "
 
 ##############################
@@ -124,40 +121,82 @@ option "base-dir" b
 #~~~~~~~~~~~~~~~~~~
 "directory to traverse"
 string typestr="path"
-dependon="create"
-required
+optional
 details="
        The base directory to be traversed recursively. A warning
        message is printed for each subdirectory that could not be
-       read because of insufficient permission. These directories
+       read because of insufficient permissions. These directories
        will be ignored when computing statistics.
 "
 
+option "one-file-system" x
+#~~~~~~~~~~~~~~~~~~~~~~~~~
+"do not dive into other file systems"
+flag off
+dependon="create"
+details="
+       Skip directories that are on different file systems from the
+       one that the argument being processed is on.
+"
 
-##############################
-section "Options for --select"
-##############################
+option "hash-table-bits" -
+#~~~~~~~~~~~~~~~~~~~~~~~~~
+"specify the size of the uid hash table"
+int typestr="num"
+dependon="create"
+default="10"
+optional
+details="
+       Use a hash table of size 2^num for the uid entries. If more than
+       2^num different uids own at least one regular file under base-dir,
+       the command fails. Increase this value if you have more than 1024
+       users. Decreasing the value causes adu to use slightly less memory.
+"
 
-option "limit" L
-#~~~~~~~~~~~~~~~
-"Limit output"
-int  typestr="num"
-required
-dependon="select"
+option "bloom-filter-order" B
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"use bloom filters for hard link detection"
+int typestr="order"
+dependon="create"
+default="23"
+optional
+details="
+       Allocate bloom filters of size 2^order bits. Each regular
+       file with hard link count greater than one is added to these
+       filters which allows to detect hard links on a per-user basis.
+       Greater values reduce the probability of false positives but
+       require more memory.
+
+       Values less than 10 deactivate this feature so that no hard
+       links are being detected.
+"
+
+option "num-bloom-filter-hash-functions" N
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"number of hash functions for the bloom filters"
+int typestr="num"
+dependon="create"
+default="10"
+optional
 details="
-       Only print num lines of output.
+       Cause each entry which is added to the bloom filter to set
+       \"num\" bits of the bloom filter.
 "
 
-option "units" U
-#~~~~~~~~~~~~~~~
-"select numerical output format"
-string typestr="format"
+##############################
+section "Options for --select"
+##############################
+
+option "select-options" s
+#~~~~~~~~~~~~~~~~~~~~~~~~~
+"Options for select mode"
+string typestr="<options>"
 optional
+dependon="select"
 details="
-       Print the number of files/directories and the sizes in
-       the given format.  All  sizes  are output in these units:
-       (h)uman-readable, (b)ytes, (k)ilobytes, (m)egabytes,
-       (g)igabytes, (t)erabytes.  Capitalise to use multiples
-       of 1000 (S.I.) instead of 1024. The default is \"h\",
-       i.e. human-readable.
+       This option takes a string whose content is another set of
+       options as described below. Select options may be specified
+       either directly in select mode, in which case you have use
+       quotes to prevent the select options from being interpreted
+       as adu options, or via the \"set\" command in interactive mode.
 "