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