{
"schema_version": "1.0",
"command": "touch",
"variant": "bsd",
"match": {
"platform": ["macos", "freebsd"],
"probe": { "args": ["--version"], "expect": "failure" },
"binary_globs": ["/bin/touch", "/usr/bin/touch"]
},
"mode": "authoritative",
"confidence": "verified",
"provenance": {
"platform": "macos",
"tool_version": "macOS 26.3",
"source": "man-page",
"checked_on": "2026-07-27",
"command": "man -P cat touch | col -b",
"environment": "macOS 26.3 (Darwin arm64), system /usr/bin/touch",
"notes": "Flags transcribed from the block after 'The following options are available:'. COMPATIBILITY and STANDARDS were read for flags documented outside the option block; COMPATIBILITY describes only the obsolescent leading time argument and documents no option. One flag is accepted by the binary but documented nowhere in the man page: -f. Its presence was established from the binary's getopt(3) option string 'A:acd:fhmr:t:' and confirmed by running '/usr/bin/touch -f FILE', which exits 0 and, on a missing file, still creates it (so -f does not imply -c). It is included because omitting it under mode authoritative would erase a flag the tool really accepts. Apart from -f the option set is closed by that same getopt string, so mode is authoritative. BSD touch has no long options: --date and --no-create are both rejected with 'illegal option -- -'. -a and -m are explicitly combinable ('Selecting both is equivalent to the default'). Every pairing of the time sources -A, -d, -r and -t exits 0, so unlike GNU touch this build does not DIAGNOSE them -- but -d, -r and -t are last-one-wins over each other and are recorded as conflicts on that basis. -A is different: it adjusts whatever time was set, so 'touch -t ... -A ...' applies both and is not declared. BSD touch rejects --version (exit 1, 'illegal option -- -'), which is why the probe matches on failure. 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 touch utility sets the modification and access times of files. If any file does not exist, it is created with default permissions. By default touch changes both modification and access times, and the timestamps are set to the current time.",
"flags": [
{ "short": "-A", "type": "string", "value_name": "adjustment", "description": "Adjust the access and modification time stamps for the file by the specified value. The argument is of the form \"[-][[hh]mm]SS\", where a leading dash makes the adjustment negative, hh is hours from 00 to 99, mm is minutes from 00 to 59 and SS is seconds from 00 to 59. The -A flag implies the -c flag: if any file specified does not exist, it will be silently ignored." },
{ "short": "-a", "type": "boolean", "description": "Change the access time of the file. The modification time of the file is not changed unless the -m flag is also specified." },
{ "short": "-c", "type": "boolean", "description": "Do not create the file if it does not exist. The touch utility does not treat this as an error. No error messages are displayed and the exit value is not affected." },
{ "short": "-d", "type": "string", "value_name": "date_time", "conflicts_with": ["-t", "-r"], "description": "Change the access and modification times to the specified date time instead of the current time of day. The argument is of the form \"YYYY-MM-DDThh:mm:SS[.frac][tz]\", where T or a space is the time designator, .frac is an optional fractional part and tz is an optional letter Z indicating UTC." },
{ "short": "-f", "type": "boolean", "description": "Accepted by the binary but not documented in the macOS touch(1) man page; it appears in the utility's getopt(3) option string and had no observable effect in testing." },
{ "short": "-h", "type": "boolean", "description": "If the file is a symbolic link, change the times of the link itself rather than the file that the link points to. Note that -h implies -c and thus will not create any new files." },
{ "short": "-m", "type": "boolean", "description": "Change the modification time of the file. The access time of the file is not changed unless the -a flag is also specified." },
{ "short": "-r", "type": "path", "value_name": "file", "conflicts_with": ["-d", "-t"], "description": "Use the access and modifications times from the specified file instead of the current time of day." },
{ "short": "-t", "type": "string", "value_name": "time", "conflicts_with": ["-d", "-r"], "description": "Change the access and modification times to the specified time instead of the current time of day. The argument is of the form \"[[CC]YY]MMDDhhmm[.SS]\". If the CC and YY letter pairs are not specified, the values default to the current year; if SS is not specified it defaults to 0." }
],
"positional_args": [
{ "name": "file", "type": "path", "variadic": true, "required": true, "description": "Files whose times are set. A file that does not exist is created with default permissions unless -c, -h or -A is given." }
],
"annotations": {
"readonly": false,
"destructive": false,
"idempotent": false,
"requires_approval": false
}
}