new option database-root
[adu.git] / 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 "pattern" p
51 #~~~~~~~~~~~~~~~~~
52 "only consider matching directories"
53 string typestr="regex"
54 optional
55 details="
56 Regular expression that must match the directory name for
57 the directory to be considered for the output of the query.
58 See regex(7) for details.
59
60 Depending on whether --print-base-dir is given, the absolute
61 directory name or only the part of the directory name below
62 the base directory is matched against \"regex\".
63
64 If this option is not given (the default) all directories
65 are taken into account.
66
67 If \"regex\" starts with '!', directories are matched against
68 the remaining part of \"regex\" and the sense of matching is
69 reversed.
70 "
71
72 option "header" H
73 #~~~~~~~~~~~~~~~~
74 "use a customized header for listings/summaries"
75 string typestr="string"
76 optional
77 details="
78 This option can be used to print any string instead of the
79 default header line (which depends on the selected mode).
80
81 In user_list mode the header is a format string which allows
82 to include the uid and the user name in the header. See the
83 --format option for more details.
84
85 It is possible to set this to the empty string to suppress
86 the header completely. This is mostly useful to feed the
87 output to scripts.
88 "
89
90 option "select-mode" m
91 #~~~~~~~~~~~~~~~~~~~~~
92 "How to print the results of the query"
93 enum typestr="<key>"
94 values="user_summary","user_list","global_summary","global_list"
95 default="user_summary"
96 optional
97 details="
98 user_summary: Print totals for each admissible uid.
99 user_list: Print a list for each admissible uid.
100 global_summary: Only print totals.
101 global_list: List of directories, regardless of owner.
102 "
103
104 option "list-sort" s
105 #~~~~~~~~~~~~~~~~~~~
106 "how to sort the user list or the global list"
107 enum typestr="<key>"
108 values="size","file_count"
109 default="size"
110 optional
111 details="
112 This option is ignored if select-mode is neither \"user_list\", nor
113 \"global_list\".
114 "
115
116 option "output" o
117 #~~~~~~~~~~~~~~~~
118 "file to write output to"
119 string typestr="path"
120 optional
121 default="-"
122 details="
123 If empty, or not given, use stdout. The following conventions
124 cause the output to be written differently:
125
126 An output file name of \"-\" means stdout.
127
128 \"path\" may be prepended by '>' which instructs adu to
129 truncate the output file to length zero. If \"path\" does
130 not start with '>' and \"path\" already exists, the select
131 query is being aborted. Otherwise, \"path\" is created and
132 output is written to \"path\".
133
134 If the first two characters of \"path\" are '>', the output
135 file (given by removing the leading \">>\" from \"path\")
136 is being opened in append mode. It is no error if the output
137 file does not exist but, as above, the output file name \">>\"
138 is considered invalid.
139
140 If the first character of \"path\" is '|', a pipe is created
141 and the rest of \"path\" is being executed with its standard in
142 redirected to the reading end of the pipe. The output of adu
143 is written to the writing end of the pipe. Again, specifying
144 only \"|\" is considered invalid and causes an error.
145 "
146
147 option "user-summary-sort" -
148 #~~~~~~~~~~~~~~~~~~~~~~~~~~~
149 "how to sort the user-summary"
150 enum typestr="col_spec"
151 values="name","uid","dir_count","file_count","size"
152 default="size"
153 optional
154 details="
155 It is enough to specify the first letter of the column specifier,
156 e.g. \"--user-summary-sort f\" sorts by file count.
157 "
158
159 option "print-base-dir" -
160 #~~~~~~~~~~~~~~~~~~~~~~~~
161 "whether to include the base-dir in the output"
162 flag off
163 details="
164 If this flag is given, all directories printed are prefixed
165 with the base directory. The default is to print paths relative
166 to the base dir.
167 "
168
169 option "format" f
170 #~~~~~~~~~~~~~~~~
171 "How to format the output"
172 string typestr="<format_string>"
173 optional
174 details="
175
176 A string that specifies how the output of the select query is
177 going to be formated. Depending on the chosen select-mode,
178 several conversion specifiers are available and a different
179 default value for this option applies.
180
181 adu knows four different types of directives: string, id,
182 count and size. These are explained in more detail below.
183
184 The general syntax for string and id directives is %(name:a:w)
185 where \"name\" is the name of the directive, \"a\" specifies
186 the alignment and \"w\" is the width specifier which allows
187 to give a field width.
188
189 The alignment specifier is a single character: Either \"l\",
190 \"r\", or \"c\" may be given to specify left, right and
191 centered alignment respectively. The with specifier is a
192 positive integer. Both \"a\" and \"w\" are optional.
193
194 A string directive supported by adu is \"dirname\" which is
195 substituted by the name of the directory. It is available
196 if either user_list or global_list mode was selected via
197 --select-mode.
198
199 Examples:
200 Print dirname without any padding:
201
202 \"%(diname)\"
203
204 Center dirname in a 20 chars wide field:
205
206 \"%(dirname:c:20)\"
207
208 The other two types of directives, count and size, are used
209 for numbers. The syntax for these is %(name:a:w:u). The \"a\"
210 and the \"w\" specifier have the same meaning as for the string
211 and id directives. The additional \"u\" specifier selects a unit
212 in which the number that corresponds to the directive should
213 be formated. All three specifiers are optional.
214
215 Possible units are the characters of the set \" bkmgtBKMGT\"
216 specifying bytes, kilobytes, megabytes, gigabytes and
217 terabytes respectively. The difference between the lower and
218 the upper case variants is that the lower case specifiers
219 select 1024-based units while the upper case specifiers use
220 1000 as the basis.
221
222 The whitespace character is like \"b\", but a space character
223 is printed instead of a unit.
224
225 Two more characters \"h\" and \"H\" (human-readable) are also
226 available that choose an appropriate unit depending on the
227 size of the number being printed.
228
229 An asterisk prepended to the unit specifier prevents the
230 unit from being printed. This is useful mainly for feeding
231 the output of adu to scripts that do not expect units.
232
233 In order to print a percent sign, use \"%%\". Moreover, adu
234 understands \"\\n\" and \"\\t\" and outputs a newline and a
235 tab character for these combinations respectively.
236
237 Examples:
238 Print size in gigabytes right-aligned:
239 \"%(size:r::G)\"
240
241 As before, but use 5 char wide field:
242 \"%(size:r5::G)\"
243
244 As before, but suppress trailing \"G\":
245 \"%(size:r5::*G)\"
246
247
248 The following list contains all directives known to adu,
249 together with their types, and for which modes each of
250 them may be used.
251
252 pw_name (string): user name. Available for user_list,
253 user_summary and for the header in user_list mode.
254
255 uid (id): user id. Available for user_list,
256 user_summary and for the header in user_list mode.
257
258 files (count): number of files. Available for all
259 modes.
260
261 dirname (string): name of the directory. Available
262 for user_list and global_list.
263
264 size (size): total size/ directory size. Available
265 for all modes.
266
267 dirs (count): number of directories. Available
268 for user_summary and global_summary.
269 "