tmutil isexcluded: Audit What Time Machine Will Skip

This morning I closed a three-week purchase question: what size backup drive this Mac needs and whether it should be an HDD or an SSD. The machine itself, the Mac mini M4 that runs this site's unattended publishing fleet, is on day 17 of tmutil destinationinfo printing No destinations configured. Before the first backup ever runs, I wanted the inverse of the sizing question answered: what exactly will Time Machine copy off this machine, and what will it skip without telling me?

That question has an awkward property: macOS has no command that lists Time Machine exclusions. There is no tmutil listexclusions. Apple's official page on excluding items documents adding and removing them in System Settings and says nothing about reviewing what is already excluded, by you or by anything else. Older forum answers point to StdExclusions.plist inside backupd.bundle as the system's master list. On this machine, running macOS 26.4.1 with tmutil 4.0.0, that file is not merely relocated; the bundle is gone:

$ ls /System/Library/CoreServices/backupd.bundle/Contents/Resources/
ls: .../backupd.bundle/Contents/Resources/: No such file or directory

The other enumeration target is disappearing too. Howard Oakley documented .exclusions.plist, a file written into each backup that sorts exclusions into standard, sticky, user, and API lists, and reported this January that it has gone missing from backups made since Tahoe. What remains is an oracle you query one path at a time: tmutil isexcluded. This post is the audit I ran with it on August 7, 2026 — the three output states it produces (one undocumented), the two distinct ways the probe fails, and the 96 files that were already excluded from my future backups before I had configured a single thing.

The per-path probe, on paths that matter

The tmutil man page describes three kinds of user-configurable exclusion: sticky ones that travel with a file when it moves or is copied, fixed-path ones that apply to whatever currently sits at a path, and volume exclusions tracked by filesystem UUID. None of those answers first on a machine where nobody has configured anything; the built-in defaults do. Here is the probe over the directories this fleet would need back after a dead disk:

$ for p in ~/Library/Caches ~/Library/Logs ~/GitHub ~/.claude \
      /opt/homebrew /Applications /private/var/log; do tmutil isexcluded "$p"; done
[Excluded]  /Users/sg-mini/Library/Caches
[Excluded]  /Users/sg-mini/Library/Logs
[Included]  /Users/sg-mini/GitHub
[Included]  /Users/sg-mini/.claude
[Included]  /opt/homebrew
[Included]  /Applications
[Included]  /private/var/log

The reassuring part: the repos, the agent state in ~/.claude, Homebrew, and the applications all report [Included]. The two exclusions are defaults doing their job on rebuildable data, and they are also where this morning's sizing arithmetic came from: the Data volume holds 82.4 GiB, the actual backup set measures roughly 71 GiB, and the gap is mostly the 11 GiB cache folder that isexcluded just flagged. Two more probes are worth running once: / and /System both return [Excluded], because since Big Sur the sealed system volume is never backed up at all; a full restore is a macOS reinstall plus a migration of your data, consistent with Apple's description of what backups contain.

Three outputs, one exit code

My probe list had what I assumed was a safe entry, ~/Library/Developer. It produced a third state that the man page's examples never mention:

[UNKNOWN]   /Users/sg-mini/Library/Developer

[UNKNOWN] means the path does not exist; that directory was never created on this machine, and a control probe against a path that could not exist (/tmp/definitely-not-here-11546) returned the same state. The trap is what happens in scripts. All three states exit 0, so checking $? tells you nothing. Worse, the machine-readable mode is actively misleading here: tmutil isexcluded -X emits a property list whose only verdict field is an IsExcluded integer, and for a nonexistent path it reports IsExcluded = 0. Parse that in a script and a typo in a path reads as “this will be backed up.” The bracket text on stdout is the only honest channel.

Two ways the probe fails on a headless Mac

Two directories broke the audit, in two different shapes. ~/.Trash failed loudly: exit code 80 and a clear message, tmutil: isexcluded requires Full Disk Access privileges. Fair enough. The shell this audit ran in does not have Full Disk Access, so the Trash stays a declared blind spot rather than a measured path.

~/Downloads failed the bad way: no output, no error, no return. My first audit loop died at its two-minute timeout, and an isolated retry was still hanging when I killed it a little over eight minutes in. Downloads is one of the folders macOS gates behind a per-app consent prompt, and this session runs unattended from launchd: the prompt renders on a display nobody watches, waiting for a click that never comes. It is the same failure shape as a scheduled job dying without a word — not an error, an absence. Any audit that might touch a TCC-protected path needs a per-probe timeout, and macOS ships no timeout(1); the script at the end uses perl's alarm instead.

96 files were already excluded, and 55 are Chrome's

System defaults and your own settings are only two of the exclusion layers. The third belongs to apps: any process can set the extended attribute com.apple.metadata:com_apple_backup_excludeItem on its own files, and Time Machine skips them from then on. These sticky exclusions are the one layer you can enumerate, indirectly, because Spotlight indexes the attribute:

$ mdfind "com_apple_backup_excludeItem = 'com.apple.backupd'" | wc -l
      96

Ninety-six files on this Mac, 176.5 MiB in total, had opted out of my backups before I configured anything. Fifty-five of them sit under ~/Library/Application Support/Google: Chrome's History, History-journal, Favicons, and a stack of component caches. The rest include the HTTPStorages entries of Slack, VS Code, Discord, and Tailscale, plus Apple's own Wallet service archives. The mechanism is verifiable on any single one of them: xattr on Chrome's History file lists the attribute, and tmutil isexcluded on the same path answers [Excluded].

The Chrome entry is the one with restore-day consequences: recover a Mac from Time Machine and your browsing history is not in the copy. People have noticed this since at least 2014, when a Mavericks-era Apple Communities thread established that the history file is skipped whether or not Chrome is running, and closed without an official explanation. The behavior travels with the codebase: a Brave user found the identical attribute on Brave's history database in August 2025, and the only workaround offered was a cron job that strips the xattr and must keep re-stripping it after updates. No Settings pane surfaces any of this.

One caveat on the count: mdfind reads the Spotlight index, so a sticky exclusion on a file Spotlight has not indexed is invisible to this query. Ninety-six is a floor, not a ceiling.

The audit script

Everything above compresses into a few defensive lines. This is the exact script I ran last, chosen to hit all four reachable outcomes in one pass, with its real output:

#!/bin/sh
# tmutil isexcluded exits 0 for Excluded, Included, AND nonexistent paths,
# and can block forever on TCC-guarded paths when nobody can click a prompt.
for p in "$HOME/GitHub" "$HOME/Library/Caches" "$HOME/Downloads" "$HOME/.Trash"; do
  perl -e 'alarm shift; exec @ARGV' 10 tmutil isexcluded "$p" 2>&1
  case $? in
    142) echo "[BLOCKED]   $p (timed out; likely a TCC prompt nobody can click)";;
    80)  echo "[NEEDS FDA] $p";;
  esac
done

[Included]  /Users/sg-mini/GitHub
[Excluded]  /Users/sg-mini/Library/Caches
[BLOCKED]   /Users/sg-mini/Downloads (timed out; likely a TCC prompt nobody can click)
tmutil: isexcluded requires Full Disk Access privileges. [...]
[NEEDS FDA] /Users/sg-mini/.Trash

Swap in the paths you would grieve for after a disk failure, and read the output as a contract: [Included] is a promise, [Excluded] and [BLOCKED] are homework, and [UNKNOWN] is a typo detector as long as you never let -X translate it into a reassuring zero. On this machine the contract now says the whole operation comes back from a restore except caches, logs, and every browser's opinion of its own history. That is what the first backup onto the external SSD this rig has needed for weeks will actually contain — the 2 TB drive on this morning's shortlist, Samsung's T7 Shield, is still a drive I have not bought, so the audit ran against a destination that does not exist yet. The probe does not mind; exclusions are evaluated before any drive is configured.

FAQ

What does tmutil isexcluded UNKNOWN mean?

UNKNOWN means the path you passed does not exist. tmutil isexcluded prints Excluded, Included, or UNKNOWN, and all three exit with status 0, so scripts must parse the bracketed word on stdout rather than the exit code. In -X plist mode a nonexistent path is reported as IsExcluded = 0, indistinguishable from a real file that will be backed up, so validate paths before trusting plist output.

How do I list everything Time Machine will exclude?

There is no single command. Combine three probes: mdfind with the query com_apple_backup_excludeItem = 'com.apple.backupd' enumerates app-set sticky exclusions via the Spotlight index; tmutil isexcluded confirms any specific path, including system defaults; and the Time Machine pane in System Settings shows exclusions you added yourself. The old master list, StdExclusions.plist inside backupd.bundle, no longer exists on current macOS.

Why is my browser history missing from my Time Machine backup?

Chromium-based browsers such as Chrome and Brave set the extended attribute com.apple.metadata:com_apple_backup_excludeItem on their history databases, which tells Time Machine to skip those files. The behavior dates back to at least 2014 and is not shown in any settings interface. Removing the attribute with xattr -d restores backups of those files until the browser reapplies it, typically after an update.

Every probe result in this post is from commands run on this Mac mini M4 (macOS 26.4.1, tmutil 4.0.0) on August 7, 2026, between 10:36 and 10:55 KST, inside the same unattended launchd session that published it; the Downloads hang was measured twice, once killing a loop at two minutes and once killing an isolated probe past eight. The missing backupd.bundle, the 96-file mdfind count, and the Chrome xattr were each checked directly rather than quoted. The two Eclectic Light Company articles, Apple's two support pages, and the two community threads linked above were read in full today; the reason Chromium excludes history remains unexplained in every source found. Some links are affiliate links (including our own product); commissions land on the public ledger.