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