diff Command on Mac: 16 of 80 Refused, 5 Silently Wrong

The diff command on a Mac stopped being GNU diff in macOS Ventura, and most of the time you won't notice. Run diff --version on this Mac mini (macOS 26.4.1) and it prints one line: Apple diff (based on FreeBSD diff). what /usr/bin/diff says PROJECT:patch_cmds-75. Nearly every diff line you copy from a Linux answer was written for GNU diffutils. So I wrote 80 diff commands, mostly GNU-style, and ran each one through Apple's /usr/bin/diff and through GNU diff 3.12, against the same files in /tmp.

Apple's diff refused 16 of the 80 with exit code 2. That part is easy, because you see the error. The worse part is five behaviors that fail silently. Two documented flags do nothing at all. One option makes diff -r report two different directories as identical, with exit 0. Another lists a file that exists on both sides as "Only in" each side. A dangling symlink prints an error and still exits 0.

This is the next post in my series on the command-line tools macOS bundles, after the du command on Mac, the find command on Mac and tar on Mac.

The test

The fixtures are small enough to check by hand: two 10-line text files with three changes, whitespace and CRLF variants, two C files for the function-label options, a pair of binary files, files without a trailing newline, and two directory trees. The trees hold a subdirectory, files that exist on one side only, a .log file for the exclude options, Name.txt on one side and name.txt on the other, a symlink that points to a file on one side and a directory on the other, and a dangling symlink. Every mtime is pinned so the headers can be compared. Each case ran under both binaries, and I recorded the exit code, stdout and stderr.

GNU diff came from the diffutils 3.12 source tarball, built into a scratch directory. Its SHA-256 matched the checksum in Homebrew's formula. Nothing was installed system-wide.

The 16 options Apple's diff refuses

These fail loudly, with diff: unrecognized option or invalid option and exit 2:

GNU option	What it does on Linux
--ignore-trailing-space, -Z	Ignore whitespace at line end
--ignore-tab-expansion, -E	Treat a tab and the spaces it expands to as equal
--line-format, --old-line-format, --new-line-format, --unchanged-line-format	Custom per-line output
--old-group-format, --new-group-format, --unchanged-group-format	Custom per-hunk output (only --changed-group-format exists on the Mac)
--from-file, --to-file	Compare one file against many
--left-column, --suppress-blank-empty	Side-by-side and blank-line tweaks
--palette	Colors for --color
-5, -v	Obsolete context count; version
-F '^[a-z].*('	Function-line regex. Apple compiles it as an extended regex, so the bare ( fails with "parentheses not balanced". GNU reads it as a basic regex, where ( is literal.

The group-format options are the ones that break real software. Midnight Commander's mcdiff builds its view with --old-group-format, and on Ventura it died with diff: unrecognized option `--old-group-format=...'. The mc issue #4487 was closed as wontfix. The fix landed in Homebrew instead, which made midnight-commander depend on GNU diff in July 2024. Review Board's client tools added a diff abstraction layer before Ventura shipped in 2022 for the same reason.

Five ways it fails silently

1 and 2. -T and -l are accepted and ignored

The man page says -T (--initial-tab) prints a tab instead of a space after the < or > marker, and -l (--paginate) pipes the output through pr. On this Mac neither does anything. The output is byte-for-byte what plain diff prints, with exit 1 and nothing on stderr.

The cause is in Apple's published source. Since FreeBSD imported libdiff from the Game of Trees project (review D36860), diff has three algorithms and defaults to Myers. Options that libdiff can't handle are supposed to fall back to the old Stone algorithm. The check that decides this, can_libdiff() in diffreg_new.c, looks at the flag bits, the output format and -I patterns. It never looks at Tflag or lflag, so those two take the Myers path and are dropped. Forcing the old algorithm brings them back:

$ diff -T a.txt b.txt | sed -n 2p | od -c | head -1
0000000    <       b   e   t   a  \n
$ diff -A stone -T a.txt b.txt | sed -n 2p | od -c | head -1
0000000    <  \t   b   e   t   a  \n

3. -S hides differences in subdirectories

-S name (--starting-file) is meant to resume a recursive diff at a given file name in the top directory. Apple's diffdir.c applies that skip again inside every subdirectory it descends into. With -S sub, the top level starts at sub/, and then inside sub/ every name that sorts before "sub" is skipped too, including the changed g.txt. The result is empty output and exit 0, which a script reads as "identical". GNU diff printed the difference and exited 1.

4. --ignore-file-name-case reports shared files as missing

Apple lists each directory in case-sensitive order, so Zeta.txt sorts before a.txt, and then merges the two lists with a case-insensitive compare. The merge gets out of step. A minimal repro: two directories that both hold the same a.txt, plus Zeta.txt on one side and zeta.txt on the other.

$ diff -r --ignore-file-name-case m1 m2
Only in m2: a.txt
Only in m1: a.txt
$ echo $?
1
$ gdiff -r --ignore-file-name-case m1 m2; echo $?
0

In my larger fixture tree Apple printed 11 "Only in" lines and GNU printed 3. -A stone doesn't help, because this is directory code, not the diff algorithm. There's also a typo in the same file: diffit() compares strcasecmp(dp2->d_name, dp2->d_name), a name against itself.

5. A dangling symlink is an error with exit 0

Both versions print diff: s1/l: No such file or directory when diff -r hits a symlink that points nowhere. GNU then exits 2, which means trouble. Apple exits 0 when the broken link is the only entry, and 1 when there are other differences. In none of my cases did it return 2. Across my fixture, 10 recursive cases differed only that way. Any script that tests [ $? -eq 2 ] will miss the error. With -rN Apple also prints File d1/broken is a unknown type while file d2/broken is a unknown type to stdout.

The smaller differences

• Unified headers have no nanoseconds or time zone. Eight of the 20 output differences were only this: 2026-10-12 12:00:00 against GNU's 2026-10-12 12:00:00.000000000 +0900. The man page documents it, and COMMAND_MODE=legacy brings the long format back. It matters if you compare patches byte-for-byte.
• -p labels differ. In my C file the hunk started at the function header. Apple put static int helper(int x) after the @@. GNU left it blank, because it only searches lines above the hunk.
• -w and -b anchor differently. For an extra blank line Apple printed 4a5 and GNU 3a4. Both are valid edits, but the patch text isn't identical.
• A wrong error message. diff -A patience -b says cannot use Myers algorithm with selected options.

Speed

On 200,000-line files with 800 changed lines, Apple's diff took a median 0.030 s over five runs, and GNU took 0.019 s. With 10% of the lines changed at random, Apple took 0.250 s and GNU 0.026 s, about ten times faster. Apple's Stone and Patience modes were no quicker. Both tools produced valid diffs of slightly different length (75,870 and 75,868 lines).

What to do

For scripts shared between Linux and macOS, stick to -u, -c, -q, -i, -B, -I, -N and -y. Those matched in my run apart from the timestamp. -w and -b work but can place hunks differently, and -r matches only on trees without broken symlinks. Don't use -S or --ignore-file-name-case on a Mac at all. Treat any stderr output from diff -r as a failure, whatever the exit code says.

If you need the GNU behavior, brew install diffutils. The formula has no g prefix, so it installs diff, cmp, sdiff and diff3 straight into /opt/homebrew/bin, and they shadow Apple's copies whenever Homebrew comes first in PATH. That's different from coreutils, which I covered in updating Bash on Mac and awk on Mac. Run type -a diff to see which one a shell will use. git diff isn't affected either way, because Git has its own diff code. The GNU diffutils manual is the reference for the Linux side.

FAQ

Is diff on Mac GNU diff?

No. Since macOS Ventura (13), /usr/bin/diff is Apple diff, based on FreeBSD diff. diff --version prints "Apple diff (based on FreeBSD diff)". In my test of 80 commands it refused 16 GNU options, including --ignore-trailing-space and the line and group format options. Install GNU diff with brew install diffutils.

Why does diff -T do nothing on Mac?

Apple's diff uses the Myers algorithm by default, and that code path ignores -T (--initial-tab) and -l (--paginate). The output is identical to plain diff. Adding -A stone switches to the older algorithm, which honors both flags. GNU diff from Homebrew's diffutils also works.

Does Apple diff return exit code 2 on errors?

For bad options and missing files, yes. For a dangling symlink inside diff -r it does not. It prints "No such file or directory" to stderr but exits 0 or 1, while GNU diff exits 2. Check stderr as well as the exit code when you run diff -r on macOS.

How this was checked: 80 diff invocations run on 2026-10-12 on a Mac mini with macOS 26.4.1 (25E253), under Apple's /usr/bin/diff (patch_cmds-75) and GNU diffutils 3.12 built from the release tarball into a scratch directory (SHA-256 matched Homebrew's formula). The fixtures sat in /tmp with pinned mtimes. Exit codes, stdout and stderr were recorded and compared by script, and the run was repeated once with the same classification. The -T, -l, -S and --ignore-file-name-case causes were traced in Apple's published patch_cmds-75 source (diff.c, diffdir.c, diffreg_new.c, diff.1) and confirmed with minimal repros. Timings are medians of five runs on generated 200,000-line files. The test harness was started by an earlier scheduled run that stopped before publishing. This run re-ran it from scratch, and the results matched apart from one case built from random bytes. I found no useful Stack Exchange threads on this switch, so the community evidence here is from project trackers.