Somebody says “something changed on that box last night.” You have snapshots. You have a pile of find -newer guesses. You also have zfs diff, which reads the difference straight out of the filesystem’s own bookkeeping and hands you a list. I see people recover from snapshots for years without knowing it exists.
The basic form
zfs diff tank/data@monday tank/data@tuesday
Output is one line per changed object, a single-character change type, then the path:
M /tank/data/
+ /tank/data/new-report.txt
- /tank/data/old-report.txt
M /tank/data/config.conf
R /tank/data/draft.txt -> /tank/data/final.txt
+ created, - removed, M modified, R renamed. A directory shows up as M when entries were added or removed inside it, so do not read that line as the directory’s own contents being edited.
Leave off the second argument and it compares the snapshot to the live filesystem, which is the form I use most:
zfs diff tank/data@before-upgrade
That is “what did I just do to this dataset”, answered precisely.
The flags worth knowing
zfs diff -FHt tank/data@before-upgrade
-Fadds a file type column (Fregular file,/directory,@symlink, and so on). Handy for filtering out the directory noise.-tputs a timestamp first, so you can sort by when something changed.-Hgives tab-separated output with no human decoration, which is the one to use in scripts.
Check zfs-diff(8) on your release for the exact column order and type codes before you parse it. I am not going to hand you a regex from memory.
Counting the damage
When the question is “how bad”, do not scroll:
zfs diff -H tank/data@before-upgrade | awk '{print $1}' | sort | uniq -c
Four numbers: created, removed, modified, renamed. If a nightly job that should touch twelve files reports forty thousand modifications, you have your answer before you open a single one. For more of this style of pipeline, see comm and set operations on files.
What it costs
zfs diff has to turn object numbers into paths. On a dataset with millions of changes that is real work, and it is not instant just because snapshots are cheap. Diffing adjacent snapshots is the fast case. Diffing a snapshot from six months ago to now on a busy dataset is not. Run it on a quiet moment, and narrow to the dataset you care about rather than the pool root.
Two other limits. You need the privileges to resolve paths, so expect to run it as root or with delegated permission. And it compares snapshots of one dataset: it will not cross dataset boundaries for you, so a child dataset’s changes belong to the child.
Where it earns its keep
- Before a rollback.
zfs rollbackthrows away everything after the snapshot. Run the diff first and see what you are about to throw away. A rollback cannot be un-done, and I have seen a rollback eat a file someone swore they had saved. - After an incident. Which config files changed between the last good snapshot and the broken one? That is a two-line investigation, and it pairs well with reading what a wedged process is actually doing.
- Replication sanity checks. If a source and a replica disagree, diff the same snapshot name on each side. This would have saved me in that mirror that was perfect and empty.
- Selective restore. The diff tells you which paths changed. The snapshot lives under
.zfs/snapshot/<name>/in the dataset root, so you can copy single files back without rolling anything.
I came to this one late, after years of mounting snapshots side by side and running diff -r over them like an animal. Slow, noisy, and it reads every byte. The filesystem already knew the answer. More in the ZFS and storage hub and the FreeBSD and OpenBSD hub.
