{
"schema_version": "1.0",
"command": "du",
"variant": "bsd",
"match": {
"platform": ["macos", "freebsd"],
"probe": { "args": ["--version"], "expect": "failure" },
"binary_globs": ["/usr/bin/du", "/bin/du"]
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "macos",
"tool_version": "macOS 26.3",
"source": "man-page",
"checked_on": "2026-07-27",
"command": "man -P cat du | col -b",
"environment": "macOS 26.3 (Darwin arm64), system /usr/bin/du",
"notes": "Flags transcribed from the block after 'The options are as follows:'. STANDARDS and HISTORY were read for options documented outside the option block; STANDARDS adds no option but records that -r is accepted and ignored, which is reflected in that flag's description. The option set is closed: every one of the 20 documented options was accepted by the binary, and 32 further single letters (-0 -b -D -e -f -G -j -N -o -p -q -R -S -T -u -v -w -X -y -z -C -E -F -J -K -M -O -Q -U -V -W -Y -Z -i) plus 22 GNU long forms (--help --version --apparent-size --files0-from --exclude --inodes --max-depth --total --summarize --human-readable --block-size --time --null --dereference --separate-dirs --one-file-system --threshold --exclude-from --count-links --bytes --all --dereference-args) were all rejected, so mode is authoritative. Note the checker trap: BSD du rejects with 'invalid option -- x', not 'illegal option', so a filter written for the latter reports every rejected letter as accepted; the scan above was re-run with a filter matching invalid/illegal/unrecognized before any of it was believed. --si is a genuine long option on BSD du; BSD's lack of long options is not a rule. BSD du rejects --version (exit 64, 'unrecognized option'), which is why the probe matches on failure. conflicts_with: only -a, -s and -d. The SYNOPSIS also alternates [-H | -L | -P] and [-g | -h | -k | -m], but the prose states those groups 'override each other and the command's actions are determined by the last one specified', and the binary accepts 'du -H -L -P' and 'du -h -k' with exit 0, so they are override groups rather than diagnosed errors. They are recorded as conflicts all the same: apexe's input is a JSON object, which has no ordering, so 'the last one specified' is decided by the order a caller happens to write the keys in -- sending both is unpredictable rather than merely redundant, which is the same advice as for a hard conflict. 'du -a -s', 'du -a -d 1' and 'du -s -d 1' all exit 64 with the usage line, in both orders. -I was confirmed repeatable and cumulative: 'du -I aa -I bb' excludes both. annotations: no option names an output file and none of the operands are written; du run with -a -c -h -A -l -n -r -x over a tree left it byte-identical under diff -r, so readonly is true. conflicts_with was extended in a later pass, after the field's definition widened to cover override groups as well as diagnosed errors: apexe's input is a JSON object, which carries no ordering, so for a last-one-wins group which flag actually wins is decided by the order the caller happened to write the keys in. Every pair added then was run in BOTH orders against the reference build recorded above, and only pairs whose outcome depends on that order, or where one side is silently discarded, were added."
},
"description": "The du utility displays the file system block usage for each file argument and for each directory in the file hierarchy rooted in each directory argument. If no file is specified, the block usage of the hierarchy rooted in the current directory is displayed.",
"flags": [
{ "short": "-A", "type": "boolean", "description": "Display the apparent size instead of the disk usage. This can be helpful when operating on compressed volumes or sparse files." },
{ "short": "-B", "type": "integer", "value_name": "blocksize", "description": "Calculate block counts in blocksize byte blocks. This is different from the -h, -k, -m, --si and -g options or setting BLOCKSIZE and gives an estimate of how much space the examined file hierarchy would require on a filesystem with the given blocksize. Unless in -A mode, blocksize is rounded up to the next multiple of 512." },
{ "short": "-H", "type": "boolean", "conflicts_with": ["-L", "-P"], "description": "Symbolic links on the command line are followed, symbolic links in file hierarchies are not followed. Overrides -L and -P; the last of the three specified wins." },
{ "short": "-I", "type": "string", "value_name": "mask", "repeatable": true, "description": "Ignore files and directories matching the specified mask. May be given more than once, and the masks accumulate." },
{ "short": "-L", "type": "boolean", "conflicts_with": ["-H", "-P"], "description": "Symbolic links on the command line and in file hierarchies are followed. Overrides -H and -P; the last of the three specified wins." },
{ "short": "-P", "type": "boolean", "conflicts_with": ["-H", "-L"], "description": "No symbolic links are followed. This is the default. Overrides -H and -L; the last of the three specified wins." },
{ "short": "-a", "type": "boolean", "conflicts_with": ["-s", "-d"], "description": "Display an entry for each file in a file hierarchy." },
{ "short": "-c", "type": "boolean", "description": "Display a grand total." },
{ "short": "-d", "type": "integer", "value_name": "depth", "conflicts_with": ["-a", "-s"], "description": "Display an entry for all files and directories depth directories deep." },
{ "short": "-g", "type": "boolean", "conflicts_with": ["-h", "-k", "-m"], "description": "Display block counts in 1073741824-byte (1 GiB) blocks." },
{ "short": "-h", "type": "boolean", "conflicts_with": ["-g", "-k", "-m"], "description": "\"Human-readable\" output. Use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte based on powers of 1024." },
{ "short": "-k", "type": "boolean", "conflicts_with": ["-g", "-h", "-m"], "description": "Display block counts in 1024-byte (1 kiB) blocks." },
{ "short": "-l", "type": "boolean", "description": "If a file has multiple hard links, count its size multiple times. The default behavior of du is to count files with multiple hard links only once. When the -l option is specified, the hard link checks are disabled, and these files are counted (and displayed) as many times as they are found." },
{ "short": "-m", "type": "boolean", "conflicts_with": ["-g", "-h", "-k"], "description": "Display block counts in 1048576-byte (1 MiB) blocks." },
{ "short": "-n", "type": "boolean", "description": "Ignore files and directories with user \"nodump\" flag (UF_NODUMP) set." },
{ "short": "-r", "type": "boolean", "description": "Generate messages about directories that cannot be read, files that cannot be opened, and so on. This is the default case. This option exists solely for conformance with X/Open Portability Guide Issue 4 (\"XPG4\"); STANDARDS records that it is accepted but ignored." },
{ "short": "-s", "type": "boolean", "conflicts_with": ["-a", "-d"], "description": "Display an entry for each specified file. (Equivalent to -d 0)" },
{ "long": "--si", "type": "boolean", "description": "\"Human-readable\" output. Use unit suffixes: Byte, Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte based on powers of 1000." },
{ "short": "-t", "type": "integer", "value_name": "threshold", "description": "Display only entries for which size exceeds threshold. If threshold is negative, display only entries for which size is less than the absolute value of threshold." },
{ "short": "-x", "type": "boolean", "description": "File system mount points are not traversed." }
],
"positional_args": [
{ "name": "file", "type": "path", "variadic": true, "required": false, "description": "Files and directories whose block usage is displayed. If none is specified, the hierarchy rooted in the current directory is used." }
],
"annotations": {
"readonly": true,
"destructive": false,
"idempotent": true,
"requires_approval": false
}
}