{
"schema_version": "1.0",
"command": "df",
"variant": "bsd",
"match": {
"platform": ["macos", "freebsd"],
"probe": { "args": ["--version"], "expect": "failure" },
"binary_globs": ["/bin/df", "/usr/bin/df"]
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "macos",
"tool_version": "macOS 26.3",
"source": "man-page",
"checked_on": "2026-07-27",
"command": "man -P cat df | col -b",
"environment": "macOS 26.3 (Darwin arm64), system /bin/df",
"notes": "Flags transcribed from the block after 'The following options are available:'. LEGACY SYNOPSIS, LEGACY DESCRIPTION, STANDARDS and BUGS were read for options documented outside the option block: they add no option, but LEGACY DESCRIPTION is where -t's argument-taking form and the -P/-k interaction are explained, and that is reflected in those descriptions. The option set is closed: all 18 documented options were accepted, and 37 further single letters (-A -B -C -d -D -e -E -f -F -G -j -J -K -L -M -N -o -O -p -q -Q -r -R -s -S -u -U -v -V -w -W -x -X -y -z -Z -0 -1) plus 15 GNU long forms (--help --version --all --human-readable --inodes --local --portability --print-type --total --sync --no-sync --output --block-size --type --exclude-type) were all rejected, so mode is authoritative. -, is a real option name: the JSON Schema's ^-[^-] pattern admits it and the binary accepts it. --libxo and --si are genuine long options on BSD df; BSD's lack of long options is not a rule. --libxo requires a value and accepts both 'df --libxo json' and 'df --libxo=json'. BSD df rejects --version (exit 64, 'unrecognized option'), which is why the probe matches on failure. conflicts_with: only -t and -T. The SYNOPSIS also alternates [-b | -g | -H | -h | -k | -m | -P], but the prose says those override each other ('The -k option overrides this option', 'The -g and -k options override this option') and the binary accepts 'df -h -k' and 'df -b -P' with exit 0, so that group is an override group rather than a diagnosed error; likewise 'df -i -I' and 'df -I -i' both exit 0 with the last one winning. Both are recorded as conflicts on the basis given at the end of these notes. -t against -T is different: 'df -T apfs -t apfs' and 'df -t apfs -T apfs' both fail, because once one of them has taken its argument the other option token is consumed as a file operand ('df: -T: No such file or directory'). Bare -t after -T is harmless, since -t without an argument is a no-op, but the conflict is recorded because the argument-taking form is the one the man page documents and calls deprecated. annotations: no option names an output file; df run with -a -c -i -Y -, left a test tree 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 df utility displays statistics about the amount of free disk space on the specified mounted file system or on the file system of which file is a part. By default block counts are displayed with an assumed block size of 512 bytes. If neither a file or a file system operand is specified, statistics for all mounted file systems are displayed.",
"flags": [
{ "long": "--libxo", "type": "string", "value_name": "options", "description": "Generate output via libxo(3) in a selection of different human and machine readable formats. See xo_parse_args(3) for details on command line arguments. The value is required and may be given as '--libxo json' or '--libxo=json'." },
{ "short": "-a", "type": "boolean", "description": "Show all mount points, including those that were mounted with the MNT_IGNORE flag. This is implied for file systems specified on the command line." },
{ "short": "-b", "type": "boolean", "conflicts_with": ["-g", "-H", "-h", "-k", "-m", "-P"], "description": "Explicitly use 512 byte blocks, overriding any BLOCKSIZE specification from the environment. This is the same as the -P option. The -k option overrides this option." },
{ "short": "-c", "type": "boolean", "description": "Display a grand total." },
{ "short": "-g", "type": "boolean", "conflicts_with": ["-b", "-H", "-h", "-k", "-m", "-P"], "description": "Use 1073741824 byte (1 Gibibyte) blocks rather than the default. This overrides any BLOCKSIZE specification from the environment." },
{ "short": "-h", "type": "boolean", "conflicts_with": ["-b", "-g", "-H", "-k", "-m", "-P"], "description": "\"Human-readable\" output. Use unit suffixes: Byte, Kibibyte, Mebibyte, Gibibyte, Tebibyte and Pebibyte (based on powers of 1024) in order to reduce the number of digits to four or fewer. This applies to the Size, Used, and Avail columns only; the iused and ifree columns will be displayed in powers of 1000." },
{ "short": "-H", "long": "--si", "type": "boolean", "conflicts_with": ["-b", "-g", "-h", "-k", "-m", "-P"], "description": "Same as -h but based on powers of 1000." },
{ "short": "-I", "type": "boolean", "conflicts_with": ["-i"], "description": "Suppress inode counts. See -i below." },
{ "short": "-i", "type": "boolean", "conflicts_with": ["-I"], "description": "Include statistics on the number of free and used inodes. In conjunction with the -h or -H options, the number of inodes is scaled by powers of 1000. In case the filesystem has no inodes then `-' is displayed instead of the usage percentage. This option is now the default to conform to Version 3 of the Single UNIX Specification (\"SUSv3\"); use -I to suppress this output." },
{ "short": "-k", "type": "boolean", "conflicts_with": ["-b", "-g", "-H", "-h", "-m", "-P"], "description": "Use 1024 byte (1 Kibibyte) blocks rather than the default. This overrides the -P option and any BLOCKSIZE specification from the environment." },
{ "short": "-l", "type": "boolean", "description": "Select locally-mounted file system for display. If used in combination with the -T type option, file system types will be added or excluded according to the parameters of that option." },
{ "short": "-m", "type": "boolean", "conflicts_with": ["-b", "-g", "-H", "-h", "-k", "-P"], "description": "Use 1048576 byte (1 Mebibyte) blocks rather than the default. This overrides any BLOCKSIZE specification from the environment." },
{ "short": "-n", "type": "boolean", "description": "Print out the previously obtained statistics from the file systems. This option should be used if it is possible that one or more file systems are in a state such that they will not be able to provide statistics without a long delay. When this option is specified, df will not request new statistics from the file systems, but will respond with the possibly stale statistics that were previously obtained. BUGS notes the flag is ignored if a file or file system is specified." },
{ "short": "-P", "type": "boolean", "conflicts_with": ["-b", "-g", "-H", "-h", "-k", "-m"], "description": "Explicitly use 512 byte blocks, overriding any BLOCKSIZE specification from the environment. This is the same as the -b option. The -g and -k options override this option. In compatibility mode, this also suppresses inode counts." },
{ "short": "-T", "type": "string", "value_name": "type", "conflicts_with": ["-t"], "description": "Select file systems to display. More than one type may be specified in a comma separated list. The list of file system types can be prefixed with \"no\" to specify the file system types for which action should not be taken, so 'df -T nonfs,mfs' lists all file systems except those of type NFS and MFS. If used in combination with the -l option, the parameters of this option will modify the list of locally-mounted file systems selected by the -l option." },
{ "short": "-t", "type": "string", "value_name": "type", "conflicts_with": ["-T"], "description": "If used with no arguments, this option is a no-op (macOS already prints the total allocated-space figures). If used with an argument, it acts like -T, but this usage is deprecated and should not be relied upon. It can be specified only once." },
{ "short": "-Y", "type": "boolean", "description": "Include file system type." },
{ "short": "-,", "type": "boolean", "description": "(Comma) Print sizes grouped and separated by thousands using the non-monetary separator returned by localeconv(3), typically a comma or period. If no locale is set, or the locale does not have a non-monetary separator, this option has no effect." }
],
"positional_args": [
{ "name": "file", "type": "path", "variadic": true, "required": false, "description": "Files or file systems to report on. If none is specified, statistics for all mounted file systems are displayed." }
],
"annotations": {
"readonly": true,
"destructive": false,
"idempotent": true,
"requires_approval": false
}
}