{
"schema_version": "1.0",
"command": "ls",
"variant": "gnu",
"match": {
"probe": {
"args": ["--version"],
"expect": "success",
"output_contains": "GNU coreutils"
}
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "linux",
"tool_version": "9.7",
"package": "coreutils",
"source": "help",
"checked_on": "2026-07-27",
"command": "docker run --rm debian@sha256:328d16499860ae6cb9b345e2e4cebca08c2a36e4f7278482c7bd1f39d71e5bfd ls --help",
"environment": "debian@sha256:328d16499860ae6cb9b345e2e4cebca08c2a36e4f7278482c7bd1f39d71e5bfd",
"notes": "Debian slim images ship no man pages, so the flag list was read from GNU --help, which is complete by GNU convention. An earlier knowledge-written revision of this file omitted --zero (added in coreutils 8.25); it was found by diffing against this reference and is the reason provenance is now mandatory. 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. value_optional was added on 2026-08-24, read off the reference build recorded above. GNU --help spells an optional option argument as `--opt[=VAL]` and a required one as `--opt=VAL`; every flag marked here shows the bracketed form and was then run in BOTH spellings, because the notation alone is not evidence. `ls --color never .` is \"ls: cannot access 'never': No such file or directory\" (exit 2) while `ls --color=never .` succeeds; --classify and --hyperlink behave the same. Six flags of apparently the same shape were tested and deliberately NOT marked, because an enum-valued flag is not the same thing as an optional-valued one: --sort, --format, --time-style, --quoting-style and --indicator-style all spell a required value in --help (`--sort=WORD`) and all accept the separated form here, and --context is '-Z, --context', which takes no value at all."
},
"description": "List information about the FILEs (the current directory by default). Entries are sorted alphabetically unless one of -cftuvSUX or --sort is given.",
"flags": [
{ "short": "-a", "long": "--all", "type": "boolean", "description": "Do not ignore entries starting with a dot." },
{ "short": "-A", "long": "--almost-all", "type": "boolean", "description": "Do not list implied . and .." },
{ "long": "--author", "type": "boolean", "description": "With -l, print the author of each file." },
{ "short": "-b", "long": "--escape", "type": "boolean", "conflicts_with": ["-Q", "-N", "--quoting-style"], "description": "Print C-style escapes for non-graphic characters." },
{ "long": "--block-size", "type": "string", "value_name": "SIZE", "conflicts_with": ["-h", "--si"], "description": "With -l, scale sizes by SIZE before printing them." },
{ "short": "-B", "long": "--ignore-backups", "type": "boolean", "description": "Do not list entries ending with ~." },
{ "short": "-c", "type": "boolean", "conflicts_with": ["-u", "--time"], "description": "With -lt, sort by and show ctime (time of last change of file status information); with -l, show ctime and sort by name; otherwise sort by ctime, newest first." },
{ "short": "-C", "type": "boolean", "conflicts_with": ["-l", "-m", "-x", "-1", "--format"], "description": "List entries by columns." },
{ "long": "--color", "type": "enum", "value_name": "WHEN", "value_optional": true, "enum_values": ["always", "auto", "never"], "description": "Colorize the output. WHEN defaults to 'always'." },
{ "short": "-d", "long": "--directory", "type": "boolean", "description": "List directories themselves, not their contents." },
{ "short": "-D", "long": "--dired", "type": "boolean", "description": "Generate output designed for Emacs' dired mode." },
{ "short": "-f", "type": "boolean", "conflicts_with": ["-t", "-S", "-U", "-X", "-v", "--sort"], "description": "Do not sort, and list all files. Same as -a -U." },
{ "short": "-F", "long": "--classify", "type": "enum", "value_name": "WHEN", "value_optional": true, "enum_values": ["always", "auto", "never"], "conflicts_with": ["-p", "--file-type", "--indicator-style"], "description": "Append an indicator (one of */=>@|) to entries WHEN. The value is optional." },
{ "long": "--file-type", "type": "boolean", "conflicts_with": ["-F", "-p", "--indicator-style"], "description": "Like --classify, except do not append '*'." },
{ "long": "--format", "type": "enum", "value_name": "WORD", "enum_values": ["across", "commas", "horizontal", "long", "single-column", "verbose", "vertical"], "conflicts_with": ["-C", "-l", "-m", "-x", "-1"], "description": "Select an output format by name." },
{ "long": "--full-time", "type": "boolean", "description": "Like -l --time-style=full-iso." },
{ "short": "-g", "type": "boolean", "description": "Like -l, but do not list the owner." },
{ "long": "--group-directories-first", "type": "boolean", "description": "Group directories before files." },
{ "short": "-G", "long": "--no-group", "type": "boolean", "description": "In a long listing, do not print group names." },
{ "short": "-h", "long": "--human-readable", "type": "boolean", "conflicts_with": ["--si", "--block-size"], "description": "With -l and -s, print sizes like 1K 234M 2G." },
{ "long": "--si", "type": "boolean", "conflicts_with": ["-h", "--block-size"], "description": "Like --human-readable, but use powers of 1000 rather than 1024." },
{ "short": "-H", "long": "--dereference-command-line", "type": "boolean", "description": "Follow symbolic links listed on the command line." },
{ "long": "--dereference-command-line-symlink-to-dir", "type": "boolean", "description": "Follow each command line symbolic link that points to a directory." },
{ "long": "--hide", "type": "string", "value_name": "PATTERN", "description": "Do not list entries matching shell PATTERN; overridden by -a or -A." },
{ "long": "--hyperlink", "type": "enum", "value_name": "WHEN", "value_optional": true, "enum_values": ["always", "auto", "never"], "description": "Hyperlink file names WHEN. The value is optional." },
{ "long": "--indicator-style", "type": "enum", "value_name": "WORD", "enum_values": ["none", "slash", "file-type", "classify"], "conflicts_with": ["-F", "-p", "--file-type"], "description": "Append an indicator of the given style to entry names." },
{ "short": "-i", "long": "--inode", "type": "boolean", "description": "Print the index number of each file." },
{ "short": "-I", "long": "--ignore", "type": "string", "value_name": "PATTERN", "repeatable": true, "description": "Do not list entries matching shell PATTERN." },
{ "short": "-k", "long": "--kibibytes", "type": "boolean", "description": "Default to 1024-byte blocks for file system usage." },
{ "short": "-l", "type": "boolean", "conflicts_with": ["-C", "-m", "-x", "-1", "--format"], "description": "Use a long listing format." },
{ "short": "-L", "long": "--dereference", "type": "boolean", "description": "Show information for the file a symbolic link references, not the link itself." },
{ "short": "-m", "type": "boolean", "conflicts_with": ["-C", "-l", "-x", "-1", "--format"], "description": "Fill width with a comma separated list of entries." },
{ "short": "-n", "long": "--numeric-uid-gid", "type": "boolean", "description": "Like -l, but list numeric user and group IDs." },
{ "short": "-N", "long": "--literal", "type": "boolean", "conflicts_with": ["-Q", "-b", "--quoting-style"], "description": "Print entry names without quoting." },
{ "short": "-o", "type": "boolean", "description": "Like -l, but do not list group information." },
{ "short": "-p", "type": "boolean", "conflicts_with": ["-F", "--file-type", "--indicator-style"], "description": "Append / indicator to directories." },
{ "short": "-q", "long": "--hide-control-chars", "type": "boolean", "conflicts_with": ["--show-control-chars"], "description": "Print ? instead of non-graphic characters." },
{ "long": "--show-control-chars", "type": "boolean", "conflicts_with": ["-q"], "description": "Show non-graphic characters as-is." },
{ "short": "-Q", "long": "--quote-name", "type": "boolean", "conflicts_with": ["-N", "-b", "--quoting-style"], "description": "Enclose entry names in double quotes." },
{ "long": "--quoting-style", "type": "enum", "value_name": "WORD", "enum_values": ["literal", "locale", "shell", "shell-always", "shell-escape", "shell-escape-always", "c", "escape"], "conflicts_with": ["-Q", "-N", "-b"], "description": "Use the named quoting style for entry names." },
{ "short": "-r", "long": "--reverse", "type": "boolean", "description": "Reverse order while sorting." },
{ "short": "-R", "long": "--recursive", "type": "boolean", "description": "List subdirectories recursively." },
{ "short": "-s", "long": "--size", "type": "boolean", "description": "Print the allocated size of each file, in blocks." },
{ "short": "-S", "type": "boolean", "conflicts_with": ["-t", "-U", "-X", "-v", "--sort", "-f"], "description": "Sort by file size, largest first." },
{ "long": "--sort", "type": "enum", "value_name": "WORD", "enum_values": ["none", "size", "time", "version", "extension", "width"], "conflicts_with": ["-t", "-S", "-U", "-X", "-v", "-f"], "description": "Sort by the named key instead of by name." },
{ "long": "--time", "type": "enum", "value_name": "WORD", "enum_values": ["atime", "access", "use", "ctime", "status", "birth", "creation"], "conflicts_with": ["-c", "-u"], "description": "Select which timestamp is shown and used for sorting." },
{ "long": "--time-style", "type": "string", "value_name": "TIME_STYLE", "description": "Time/date format used with -l." },
{ "short": "-t", "type": "boolean", "conflicts_with": ["-S", "-U", "-X", "-v", "--sort", "-f"], "description": "Sort by time, newest first." },
{ "short": "-T", "long": "--tabsize", "type": "integer", "value_name": "COLS", "description": "Assume tab stops at each COLS instead of 8." },
{ "short": "-u", "type": "boolean", "conflicts_with": ["-c", "--time"], "description": "With -lt, sort by and show access time; with -l, show access time and sort by name; otherwise sort by access time, newest first." },
{ "short": "-U", "type": "boolean", "conflicts_with": ["-t", "-S", "-X", "-v", "--sort", "-f"], "description": "Do not sort; list entries in directory order." },
{ "short": "-v", "type": "boolean", "conflicts_with": ["-t", "-S", "-U", "-X", "--sort", "-f"], "description": "Natural sort of (version) numbers within text." },
{ "short": "-w", "long": "--width", "type": "integer", "value_name": "COLS", "description": "Set output width to COLS. 0 means no limit." },
{ "short": "-x", "type": "boolean", "conflicts_with": ["-C", "-l", "-m", "-1", "--format"], "description": "List entries by lines instead of by columns." },
{ "short": "-X", "type": "boolean", "conflicts_with": ["-t", "-S", "-U", "-v", "--sort", "-f"], "description": "Sort alphabetically by entry extension." },
{ "short": "-Z", "long": "--context", "type": "boolean", "description": "Print any security context of each file." },
{ "long": "--zero", "type": "boolean", "description": "End each output line with NUL, not newline." },
{ "short": "-1", "type": "boolean", "conflicts_with": ["-C", "-l", "-m", "-x", "--format"], "description": "List one file per line." },
{ "long": "--help", "type": "boolean", "description": "Display help and exit." },
{ "long": "--version", "type": "boolean", "description": "Output version information and exit." }
],
"positional_args": [
{ "name": "file", "type": "path", "variadic": true, "required": false, "description": "Files or directories to list. Defaults to the current directory." }
],
"annotations": {
"readonly": true,
"destructive": false,
"idempotent": true,
"requires_approval": false
}
}