Merge branch 'refs/heads/t/doc-improvements'
[adu.git] / adu.ggo
diff --git a/adu.ggo b/adu.ggo
index 55e5c5a..643bbbf 100644 (file)
--- a/adu.ggo
+++ b/adu.ggo
@@ -1,9 +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"
-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
@@ -14,52 +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"
+option "loglevel" l
+#~~~~~~~~~~~~~~~~~~
+"Set loglevel (0-6)"
+int typestr="level"
+default="4"
 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.
+       Log messages are always written to stderr while normal output
+       goes to stdout. Lower values mean more verbose logging.
+"
 
+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.
 "
 
-option "database-dir" d
-#~~~~~~~~~~~~~~~~~~~~~~
+groupoption "database-dir" d
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~
 "directory containing the osl tables"
+group="database"
 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"
-optional
-details="
-       Log messages are always written to stderr while normal output
-       goes to stdout. Lower values mean more verbose logging.
+       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.
 "
 
 ###############
@@ -69,10 +72,9 @@ section "Modes"
 defgroup "mode"
 #==============
 groupdesc="
-       adu may be 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
 
@@ -81,10 +83,10 @@ 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
@@ -92,7 +94,12 @@ groupoption "interactive" I
 "activate interactive mode"
 group="mode"
 details="
-       In this mode, adu reads commands from stdin.
+       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
@@ -100,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.
 "
 
 ##############################
@@ -112,14 +121,12 @@ option "base-dir" b
 #~~~~~~~~~~~~~~~~~~
 "directory to traverse"
 string typestr="path"
-dependon="create"
 optional
 details="
-       The base directory to be traversed recursively. Must be
-       given if --create mode was selected. A warning message is
-       printed for each subdirectory that could not be read because
-       of insufficient permission. These directories will be ignored
-       when computing statistics.
+       The base directory to be traversed recursively. A warning
+       message is printed for each subdirectory that could not be
+       read because of insufficient permissions. These directories
+       will be ignored when computing statistics.
 "
 
 option "one-file-system" x
@@ -128,7 +135,7 @@ option "one-file-system" x
 flag off
 dependon="create"
 details="
-       Skip directories that are on different filesystems from the
+       Skip directories that are on different file systems from the
        one that the argument being processed is on.
 "
 
@@ -146,91 +153,50 @@ details="
        users. Decreasing the value causes adu to use slightly less memory.
 "
 
-##############################
-section "Options for --select"
-##############################
-
-option "select-options" s
-#~~~~~~~~~~~~~~~~~~~~~~~~~
-"options for select mode"
-string typestr="<options>"
+option "bloom-filter-order" B
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"use bloom filters for hard link detection"
+int typestr="order"
+dependon="create"
+default="23"
 optional
-dependon="select"
 details="
-       Try --select-options \"-h\"
-"
+       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.
 
-option "print-base-dir" -
-#~~~~~~~~~~~~~~~~~~~~~~~~
-"whether to include the base-dir in the output"
-flag off
-details="
-       If this flag is given, all directories printed are prefixed
-       with the base directory. The default is to print paths relative
-       to the base dir.
-"
-
-option "no-headers" -
-#~~~~~~~~~~~~~~~~~~~~
-"supress descriptions for listings/tables"
-flag off
-dependon="select"
-details="
-       This is mostly useful to feed the output of adu to scripts.
+       Values less than 10 deactivate this feature so that no hard
+       links are being detected.
 "
 
-option "global-list" -
-#~~~~~~~~~~~~~~~~~~~~~
-"how to print global directory listings"
-enum typestr="which"
-values="size","file_count","both","none"
-default="both"
-optional
-dependon="select"
-details="
-       By default adu prints two global directory listings: The
-       first prints the directory names ordered by the sum of the
-       sizes of the contained files while the second listing prints
-       them sorted by the number of files. This option can be used
-       to print only one or neither of these two listings.
-"
-
-option "no-global-summary" -
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"do not print the summary line"
-flag off
-dependon="select"
-
-option "user-list" -
-#~~~~~~~~~~~~~~~~~~~
-"how to print per-user directory listings"
-enum typestr="which"
-values="size","file_count","both","none"
-default="both"
+option "num-bloom-filter-hash-functions" N
+#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+"number of hash functions for the bloom filters"
+int typestr="num"
+dependon="create"
+default="10"
 optional
-dependon="select"
 details="
-       Similar to the global directory listings mentioned above,
-       adu can print two directory listings per user. This option
-       controls which of the these should be printed.
+       Cause each entry which is added to the bloom filter to set
+       \"num\" bits of the bloom filter.
 "
 
-option "no-user-summary" -
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"do not print the user summary table"
-flag off
-dependon="select"
-
+##############################
+section "Options for --select"
+##############################
 
-option "user-summary-sort" -
-#~~~~~~~~~~~~~~~~~~~~~~~~~~~
-"how to sort the user-summary"
-enum typestr="col_spec"
-values="name","uid","dir_count","file_count","size"
-default="size"
+option "select-options" s
+#~~~~~~~~~~~~~~~~~~~~~~~~~
+"Options for select mode"
+string typestr="<options>"
 optional
 dependon="select"
 details="
-       It is enough to specify the first letter of the column specifier,
-       e.g. \"--user-summary-sort f\" sorts by file count.
+       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.
 "