X-Git-Url: http://git.tuebingen.mpg.de/?p=adu.git;a=blobdiff_plain;f=select.ggo;h=c4e1ec0319841322a189e643b04c578c862398c5;hp=d8f3ae3a37ad8b51ae9e8c3f03b106750af46117;hb=f638c88fad8a1350cf56d5f60ddef297ece92805;hpb=8033c743e9d07be7b79277e15b477e19f7e83d87 diff --git a/select.ggo b/select.ggo index d8f3ae3..c4e1ec0 100644 --- a/select.ggo +++ b/select.ggo @@ -1,86 +1,148 @@ +option "user" u +#~~~~~~~~~~~~~~ +"users to take into account" +string typestr="user_name" +optional +multiple +details=" + This option may be given multiple times in which case all given + user names are considered admissible. See also --uid below. +" -option "uid" u +option "uid" U #~~~~~~~~~~~~~ "user id(s) to take into account" string typestr="uid_spec" optional details=" - An uid specifier may be a single number, or a range of uids. + An uid specifier may be a single uid, a range of uids, + or a comma-separated list of single uids or ranges. Example: - --uid 42 # only consider uid 42 - --uid 42- # only consider uids greater or equal than 42 - --uid 23-42 # only consider uids between 23 and 42, inclusively. - --uid 23-42,666-777,88 # consider uids 23-42, 666-777 and 88. + Only consider uid 42: + --uid 42 + + Only consider uids greater or equal than 42: + --uid 42- + + Only consider uids between 23 and 42, inclusively: + --uid 23-42 + + Consider uids 23-42, 666-777 and 88: + --uid 23-42,666-777,88 + + If no --user option is given and also --uid option is not given + (the default), all users are taken into account. " -option "limit" L +option "limit" l #~~~~~~~~~~~~~~~ "Limit output" -int typestr="num" +int typestr="num" default="-1" optional details=" Only print num lines of output. If negative (the default), - print all lines. + print all lines. This option is honored in all select modes + except global_summary (which outputs only one single line). " -option "no-headers" - -#~~~~~~~~~~~~~~~~~~~~ -"supress descriptions for listings/tables" -flag off +option "pattern" p +#~~~~~~~~~~~~~~~~~ +"only consider matching directories" +string typestr="regex" +optional details=" - This is mostly useful to feed the output of adu to scripts. + Regular expression that must match the directory name for + the directory to be considered for the output of the query. + See regex(7) for details. + + Depending on whether --print-base-dir is given, the absolute + directory name or only the part of the directory name below + the base directory is matched against \"regex\". + + If this option is not given (the default) all directories + are taken into account. + + If \"regex\" starts with '!', directories are matched against + the remaining part of \"regex\" and the sense of matching is + reversed. " -option "sort" s -#~~~~~~~~~~~~~~~ -"how to sort the output" -enum typestr="" -values="sizes","files","unsorted" -default="sizes" +option "header" H +#~~~~~~~~~~~~~~~~ +"use a customized header for listings/summaries" +string typestr="string" optional details=" - Sort by file size, file count or unsorted. + This option can be used to print any string instead of the + default header line (which depends on the selected mode). + + In user_list mode the header is a format string which allows + to include the uid and the user name in the header. See the + --format option for more details. + + It is possible to set this to the empty string to suppress + the header completely. This is mostly useful to feed the + output to scripts. " -option "output" o -#~~~~~~~~~~~~~~~~ -"file to write output to" -string typestr="" +option "select-mode" m +#~~~~~~~~~~~~~~~~~~~~~ +"How to print the results of the query" +enum typestr="" +values="user_summary","user_list","global_summary","global_list" +default="user_summary" optional -default="-" details=" - If empty, or not given, use stdout. + user_summary: Print totals for each admissible uid. + user_list: Print a list for each admissible uid. + global_summary: Only print totals. + global_list: List of directories, regardless of owner. " -option "size-unit" - +option "list-sort" s #~~~~~~~~~~~~~~~~~~~ -"select output format for sizes" -enum typestr="format" -values="h","b","k","m","g","t" -default="h" +"how to sort the user list or the global list" +enum typestr="" +values="size","file_count" +default="size" optional details=" - Print sizes in the given unit: human-readable, bytes, - kilobytes (2^10), megabytes (2^20), gigabytes (2^30), terabytes - (2^40). The default is \"h\", i.e. human-readable. + This option is ignored if select-mode is neither \"user_list\", nor + \"global_list\". " -option "count-unit" - -#~~~~~~~~~~~~~~~~~~~~ -"select output format for counted values" -enum typestr="format" -values="h","n","k","m","g","t" -default="h" +option "output" o +#~~~~~~~~~~~~~~~~ +"file to write output to" +string typestr="path" optional +default="-" details=" - Print the number of files/directories in the given unit: - human-readable, number, number/10^3, number/10^6, number/10^12, - number/10^15. The default is to print numbers in human-readable - format. -" + If empty, or not given, use stdout. The following conventions + cause the output to be written differently: + + An output file name of \"-\" means stdout. + \"path\" may be prepended by '>' which instructs adu to + truncate the output file to length zero. If \"path\" does + not start with '>' and \"path\" already exists, the select + query is being aborted. Otherwise, \"path\" is created and + output is written to \"path\". + + If the first two characters of \"path\" are '>', the output + file (given by removing the leading \">>\" from \"path\") + is being opened in append mode. It is no error if the output + file does not exist but, as above, the output file name \">>\" + is considered invalid. + + If the first character of \"path\" is '|', a pipe is created + and the rest of \"path\" is being executed with its standard in + redirected to the reading end of the pipe. The output of adu + is written to the writing end of the pipe. Again, specifying + only \"|\" is considered invalid and causes an error. +" option "user-summary-sort" - #~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -94,43 +156,6 @@ details=" e.g. \"--user-summary-sort f\" sorts by file count. " -option "no-user-summary" - -#~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"do not print the user summary table" -flag off - - -option "user-list" - -#~~~~~~~~~~~~~~~~~~~ -"how to print per-user directory listings" -enum typestr="which" -values="size","file_count","both","none" -default="both" -optional -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. -" -option "no-global-summary" - -#~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"do not print the summary line" -flag off - -option "global-list" - -#~~~~~~~~~~~~~~~~~~~~~ -"how to print global directory listings" -enum typestr="which" -values="size","file_count","both","none" -default="both" -optional -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 "print-base-dir" - #~~~~~~~~~~~~~~~~~~~~~~~~ "whether to include the base-dir in the output" @@ -141,32 +166,104 @@ details=" to the base dir. " -######################## -section "Format strings" -######################## - -option "global-summary-format" - -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"How to format the global summary" -string typestr="" -default="#directories: %(dirs), #files: %(files), size: %(size)\n\n" -details=" - dirs: The number of directories - files: The number of files - size: Total size of all files -" +option "format" f +#~~~~~~~~~~~~~~~~ +"How to format the output" +string typestr="" optional - -option "user-summary-format" - -#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -"How to format the user summary" -string typestr="" -default="%(pw_name:l:16) %(uid:r:5) %(dirs:r:5) %(files:r:5) %(size:r:5)\n" details=" - pw_name: The user name - uid: The user id - dirs: The number of directories - files: The number of files - size: Total size of all files + + A string that specifies how the output of the select query is + going to be formated. Depending on the chosen select-mode, + several conversion specifiers are available and a different + default value for this option applies. + + adu knows four different types of directives: string, id, + count and size. These are explained in more detail below. + + The general syntax for string and id directives is %(name:a:w) + where \"name\" is the name of the directive, \"a\" specifies + the alignment and \"w\" is the width specifier which allows + to give a field width. + + The alignment specifier is a single character: Either \"l\", + \"r\", or \"c\" may be given to specify left, right and + centered alignment respectively. The with specifier is a + positive integer. Both \"a\" and \"w\" are optional. + + A string directive supported by adu is \"dirname\" which is + substituted by the name of the directory. It is available + if either user_list or global_list mode was selected via + --select-mode. + + Examples: + Print dirname without any padding: + + \"%(diname)\" + + Center dirname in a 20 chars wide field: + + \"%(dirname:c:20)\" + + The other two types of directives, count and size, are used + for numbers. The syntax for these is %(name:a:w:u). The \"a\" + and the \"w\" specifier have the same meaning as for the string + and id directives. The additional \"u\" specifier selects a unit + in which the number that corresponds to the directive should + be formated. All three specifiers are optional. + + Possible units are the characters of the set \" bkmgtBKMGT\" + specifying bytes, kilobytes, megabytes, gigabytes and + terabytes respectively. The difference between the lower and + the upper case variants is that the lower case specifiers + select 1024-based units while the upper case specifiers use + 1000 as the basis. + + The whitespace character is like \"b\", but a space character + is printed instead of a unit. + + Two more characters \"h\" and \"H\" (human-readable) are also + available that choose an appropriate unit depending on the + size of the number being printed. + + An asterisk prepended to the unit specifier prevents the + unit from being printed. This is useful mainly for feeding + the output of adu to scripts that do not expect units. + + In order to print a percent sign, use \"%%\". Moreover, adu + understands \"\\n\" and \"\\t\" and outputs a newline and a + tab character for these combinations respectively. + + Examples: + Print size in gigabytes right-aligned: + \"%(size:r::G)\" + + As before, but use 5 char wide field: + \"%(size:r5::G)\" + + As before, but suppress trailing \"G\": + \"%(size:r5::*G)\" + + + The following list contains all directives known to adu, + together with their types, and for which modes each of + them may be used. + + pw_name (string): user name. Available for user_list, + user_summary and for the header in user_list mode. + + uid (id): user id. Available for user_list, + user_summary and for the header in user_list mode. + + files (count): number of files. Available for all + modes. + + dirname (string): name of the directory. Available + for user_list and global_list. + + size (size): total size/ directory size. Available + for all modes. + + dirs (count): number of directories. Available + for user_summary and global_summary. " -optional