{
"schema_version": "1.0",
"command": "ln",
"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 ln --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. '-d, -F, --directory' is one help entry carrying two short forms; it is split into a -d/--directory flag and a separate -F alias because the overlay format carries at most one short form per flag. Enum values for --backup come from the value table in the same --help output, not from outside knowledge. conflicts_with is derived from this help text only: -s against -L and -P from 'Using -s ignores -L and -P'; -L against -P from 'Otherwise, the last option specified controls behavior when a TARGET is a symbolic link, defaulting to -P'; -f against -i from the opposed descriptions 'remove existing destination files' and 'prompt whether to remove destinations'; -t against -T from the separate usage forms, confirmed against the reference build, which fails with 'ln: cannot combine --target-directory and --no-target-directory'. Only the -t/-T pair is diagnosed; the others were run and exited 0. annotations: destructive is true because -f unlinks an existing target before linking, discarding that file's directory entry irrecoverably -- the same overwrite behaviour for which cp and mv are marked destructive. --backup and -b exist precisely to mitigate it. 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. `ln --backup numbered g.txt d/l1` is \"ln: target 'd/l1': No such file or directory\" (exit 1) while `ln --backup=numbered g.txt d/l1` succeeds."
},
"description": "Create a link to TARGET with the name LINK_NAME, or create links to each TARGET in DIRECTORY. Create hard links by default, symbolic links with --symbolic. By default, each destination (name of new link) should not already exist. When creating hard links, each TARGET must exist. Symbolic links can hold arbitrary text; if later resolved, a relative link is interpreted in relation to its parent directory.",
"flags": [
{ "long": "--backup", "type": "enum", "value_name": "CONTROL", "value_optional": true, "enum_values": ["none", "off", "numbered", "t", "existing", "nil", "simple", "never"], "description": "Make a backup of each existing destination file. The version control method may also be selected through the VERSION_CONTROL environment variable. The value is optional." },
{ "short": "-b", "type": "boolean", "description": "Like --backup but does not accept an argument." },
{ "short": "-d", "long": "--directory", "type": "boolean", "description": "Allow the superuser to attempt to hard link directories (this will probably fail due to system restrictions, even for the superuser)." },
{ "short": "-F", "type": "boolean", "description": "Allow the superuser to attempt to hard link directories; listed by --help as an alias of -d and --directory." },
{ "short": "-f", "long": "--force", "type": "boolean", "conflicts_with": ["-i"], "description": "Remove existing destination files." },
{ "short": "-i", "long": "--interactive", "type": "boolean", "conflicts_with": ["-f"], "description": "Prompt whether to remove destinations." },
{ "short": "-L", "long": "--logical", "type": "boolean", "conflicts_with": ["-P", "-s"], "description": "Dereference TARGETs that are symbolic links." },
{ "short": "-n", "long": "--no-dereference", "type": "boolean", "description": "Treat LINK_NAME as a normal file if it is a symbolic link to a directory." },
{ "short": "-P", "long": "--physical", "type": "boolean", "conflicts_with": ["-L", "-s"], "description": "Make hard links directly to symbolic links. This is the default when neither -L nor -P is given." },
{ "short": "-r", "long": "--relative", "type": "boolean", "description": "With -s, create links relative to link location." },
{ "short": "-s", "long": "--symbolic", "type": "boolean", "conflicts_with": ["-L", "-P"], "description": "Make symbolic links instead of hard links. Using -s ignores -L and -P." },
{ "short": "-S", "long": "--suffix", "type": "string", "value_name": "SUFFIX", "description": "Override the usual backup suffix. The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX." },
{ "short": "-t", "long": "--target-directory", "type": "path", "value_name": "DIRECTORY", "conflicts_with": ["-T"], "description": "Specify the DIRECTORY in which to create the links." },
{ "short": "-T", "long": "--no-target-directory", "type": "boolean", "conflicts_with": ["-t"], "description": "Treat LINK_NAME as a normal file always." },
{ "short": "-v", "long": "--verbose", "type": "boolean", "description": "Print name of each linked file." },
{ "long": "--help", "type": "boolean", "description": "Display this help and exit." },
{ "long": "--version", "type": "boolean", "description": "Output version information and exit." }
],
"positional_args": [
{ "name": "target", "type": "path", "variadic": true, "required": true, "description": "File to link to. More than one TARGET requires a DIRECTORY operand or -t." },
{ "name": "link_name", "type": "path", "required": false, "description": "Name of the new link, or the DIRECTORY the links are created in. Omitted in the second usage form and when -t is used." }
],
"annotations": {
"readonly": false,
"destructive": true,
"idempotent": false,
"requires_approval": true
}
}