select.ggo

   1 option "user" u
   2 #~~~~~~~~~~~~~~
   3 "users to take into account"
   4 string typestr="user_name"
   5 optional
   6 multiple
   7 details="
   8         This option may be given multiple times in which case all given
   9         user names are considered admissible. See also --uid below.
  10 "
  11
  12 option "uid" U
  13 #~~~~~~~~~~~~~
  14 "user id(s) to take into account"
  15 string typestr="uid_spec"
  16 optional
  17 details="
  18         An uid specifier may be a single uid, a range of uids,
  19         or a comma-separated list of single uids or ranges.
  20         Example:
  21
  22         Only consider uid 42:
  23                 --uid 42
  24
  25         Only consider uids greater or equal than 42:
  26                 --uid 42-
  27
  28         Only consider uids between 23 and 42, inclusively:
  29                 --uid 23-42
  30
  31         Consider uids 23-42, 666-777 and 88:
  32                 --uid 23-42,666-777,88
  33
  34         If no --user option is given and also --uid option is not given
  35         (the default), all users are taken into account.
  36 "
  37
  38 option "limit" l
  39 #~~~~~~~~~~~~~~~
  40 "Limit output"
  41 int  typestr="num"
  42 default="-1"
  43 optional
  44 details="
  45         Only print num lines of output. If negative (the default),
  46         print all lines. This option is honored in all select modes
  47         except global_summary (which outputs only one single line).
  48 "
  49
  50 option "no-headers" -
  51 #~~~~~~~~~~~~~~~~~~~~
  52 "suppress descriptions for listings/summaries"
  53 flag off
  54 details="
  55         This is mostly useful to feed the output of adu to scripts.
  56 "
  57
  58 option "select-mode" m
  59 #~~~~~~~~~~~~~~~~~~~~~
  60 "How to print the results of the query"
  61 enum typestr="<key>"
  62 values="user_summary","user_list","global_summary","global_list"
  63 default="user_summary"
  64 optional
  65 details="
  66         global_list: List of directories, regardless of owner.
  67         global_summary: Only print totals.
  68         user_list: Print a list for each admissible uid.
  69         user_summary Print totals for each admissible uid.
  70 "
  71
  72 option "list-sort" s
  73 #~~~~~~~~~~~~~~~~~~~
  74 "how to sort the user list or the global list"
  75 enum typestr="<key>"
  76 values="size","file_count"
  77 default="size"
  78 optional
  79 details="
  80         This option is ignored if select-mode is neither \"user_list\", nor
  81         \"global_list\".
  82 "
  83
  84 option "output" o
  85 #~~~~~~~~~~~~~~~~
  86 "file to write output to"
  87 string typestr="<path>"
  88 optional
  89 default="-"
  90 details="
  91         If empty, or not given, use stdout.
  92 "
  93
  94 option "user-summary-sort" -
  95 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
  96 "how to sort the user-summary"
  97 enum typestr="col_spec"
  98 values="name","uid","dir_count","file_count","size"
  99 default="size"
 100 optional
 101 details="
 102         It is enough to specify the first letter of the column specifier,
 103         e.g. \"--user-summary-sort f\" sorts by file count.
 104 "
 105
 106 option "print-base-dir" -
 107 #~~~~~~~~~~~~~~~~~~~~~~~~
 108 "whether to include the base-dir in the output"
 109 flag off
 110 details="
 111         If this flag is given, all directories printed are prefixed
 112         with the base directory. The default is to print paths relative
 113         to the base dir.
 114 "
 115
 116 option "format" f
 117 #~~~~~~~~~~~~~~~~
 118 "How to format the output"
 119 string typestr="<format_string>"
 120 optional
 121 details="
 122
 123         A string that specifies how the output of the select query is
 124         going to be formated.  Depending on the chosen select-mode,
 125         several conversion specifiers are available and a different
 126         default value for this option applies.
 127
 128         adu knows four different types of directives: string, id,
 129         count and size.  These are explained in more detail below.
 130
 131         The general syntax for string and id directives is %(name:a:w)
 132         where \"name\" is the name of the directive, \"a\" specifies
 133         the alignment and \"w\" is the width specifier which allows
 134         to give a field width.
 135
 136         The alignment specifier is a single character: Either \"l\",
 137         \"r\", or \"c\" may be given to specify left, right and
 138         centered alignment respectively. The with specifier is a
 139         positive integer.  Both \"a\" and \"w\" are optional.
 140
 141         A string directive supported by adu is \"dirname\" which is
 142         substituted by the name of the directory. It is available
 143         if either user_list or global_list mode was selected via
 144         --select-mode.
 145
 146         Examples:
 147                 Print dirname without any padding:
 148
 149                 \"%(diname)\"
 150
 151                 Center dirname in a 20 chars wide field:
 152
 153                 \"%(dirname:c:20)\"
 154
 155         The other two types of directives, count and size, are used
 156         for numbers. The syntax for these is %(name:a:w:u). The \"a\"
 157         and the \"w\" specifier have the same meaning as for the string
 158         and id directives. The additional \"u\" specifier selects a unit
 159         in which the number that corresponds to the directive should
 160         be formated. All three specifiers are optional.
 161
 162         Possible units are the characters of the set \" bkmgtBKMGT\"
 163         specifying bytes, kilobytes, megabytes, gigabytes and
 164         terabytes respectively. The difference between the lower and
 165         the upper case variants is that the lower case specifiers
 166         select 1024-based units while the upper case specifiers use
 167         1000 as the basis.
 168
 169         The whitespace character is like \"b\", but a space character
 170         is printed instead of a unit.
 171
 172         Two more characters \"h\" and \"H\" (human-readable) are also
 173         available that choose an appropriate unit depending on the
 174         size of the number being printed.
 175
 176         An asterisk prepended to the unit specifier prevents the
 177         unit from being printed. This is useful mainly for feeding
 178         the output of adu to scripts that do not expect units.
 179
 180         In order to print a percent sign, use \"%%\". Moreover, adu
 181         understands \"\\n\" and \"\\t\" and outputs a newline and a
 182         tab character for these combinations respectively.
 183
 184         Examples:
 185                 Print size in gigabytes right-aligned:
 186                         \"%(size:r::G)\"
 187
 188                 As before, but use 5 char wide field:
 189                         \"%(size:r5::G)\"
 190
 191                 As before, but suppress trailing \"G\":
 192                         \"%(size:r5::*G)\"
 193
 194
 195         The following list contains all directives known to adu,
 196         together with their types, and for which modes each of
 197         them may be used.
 198
 199                 pw_name (string): user name. Available for user_list
 200                 and user_summary
 201
 202                 uid (id): user id. Available for user_list and
 203                 user_summary.
 204
 205                 files (count): number of files. Available everywhere.
 206
 207                 dirname (string): name of the directory. Available
 208                 for user_list and global_list.
 209
 210                 size (size): total size/ directory size. Available
 211                 everywhere.
 212
 213                 dirs (count): number of directories. Available
 214                 for user_summary and global_summary.
 215 "