Time Machine expects your trust. A lot of trust, as it’s one of the few widely used backup systems which doesn’t actually reveal what it has backed up each time. Recently, Jeff asked me how he could tell exactly what was backed up in the last Time Machine (TM) backup, and the simple answer is that you can’t. This article looks inside TM’s support files and reveals that you can, only it’s far from simple.

You will recall my previous diagram showing the structure of TM backups.

The information that we want is stored in files which are normally hidden within each backup folder, that’s named using a datestamp like 2020-01-16-145806, where you’ll find:

• .Backup.log,
• .com.apple.TMCheckpoint,
• .exclusions.plist,
• [UUID].eventdb, [UUID].clonedb, and .[UUID].eventdb files,
• [volname] a folder containing the backup for each volume which was backed up.

Here I’ll look through each of these to see what useful information they contain.

.Backup.log

This should be a short text file containing a summary of events which took place during that backup. Although it gives some details which don’t appear in the unified log, in other respects it is merely a summary of the more detailed account given there. As it contains volume names and UUIDs for each of those which were backed up, it is a useful means of establishing which volumes were backed up, and which of the other files refer to each volume.

.com.apple.TMCheckpoint

This is a binary Property List containing basic statistics for the snapshots within the backup, including the total size and the number of items within them.

.exclusions.plist

This is a very important Property List which states explicitly, for that backup, which paths were backed up, and which weren’t because they had been excluded. Although its name doesn’t mention it, it includes a dictionary sourcePaths, which is an array of paths which were on the list of items to be backed up. This typically includes

• / the root, which here represents the System volume. This apparently doesn’t traverse the firmlinks which connect it to the Data volume;
• /System/Volumes/Data the Data volume;
• /Volumes/Recovery the Recovery volume;
• and external volumes which you have opted to include, through the /Volumes path.

Lists of paths excluded from backups are categorised thus:

• apiExclusionPaths, which are set by specific apps, and might include their private log files and caches;
• standardExclusionPaths, which are those set by macOS, and are discussed below;
• stickyExclusionPaths, again set by macOS, and discussed below;
• systemFilesExcluded, a Boolean which states whether you opted to include the System volume;
• userExclusionPaths, the items which you added to the TM pane’s exclusion list.

standardExclusionPaths include Trashes, caches, temporary files, /Network, and some system databases. Although some of these might appear important, they are mostly ephemeral files which you wouldn’t want swelling your backups.

stickyExclusionPaths also includes a lot of ephemeral and similar items, but holds some surprises such as the database and thumbnails folders inside photoslibrary bundles, and iTunes Store album artwork.

clonedb files

Volumes for which snapshots have been made will normally have a clonedb file built for them. This is another binary Property List which is of limited help to the user, as all it contains are pairs and groups of integers, which appear to be inode numbers which will be used to make file and folder hard links in the backup.

eventdb files

Volumes for which the FSEvents database has been used to determine what to back up have an eventdb file written for them, and these are the richest and most useful of the support files in TM. They’re also often very large, and being binary Property Lists aren’t concise by any means. They consist of nested dictionaries, and are best viewed using a ‘folding’ editor such as BBEdit, which can collapse the leaves (files) and branches (folders) of their tree-structured data.

At the top level, these are normally declared as having no Consistency Scan, meaning they have been derived straight from FSEvents without performing a ‘deep traversal’ scan, contain only file events, and give volume UUID, which is used to name the file.

Details of items which were chosen for back up are given in the Events dictionary. At each level in this dictionary, the following data are given:

• Children (omitted in leaves), an array of branches leading to files;
• Flags, an integer which contains that item’s permissions;
• Name, that element in the path;
• SubtreeSize, the number of items within that branch.

To build the full path on that volume to any item, you concatenate the Name of each branch with the separator /. Thus, a parent of / with child Pictures, grandchild Nikon, great-grandchild (leaf) MyPhoto.jpeg is the file /Pictures/Nikon/MyPhoto.jpeg. Thus, to determine which files have been backed up, all you have to do is build the path to each of the leaves specified in the tree. Although this isn’t simple, it is feasible in an app, which could then generate a list of path and file names for all the items which were backed up from that volume. If you simply want to check whether a specific file was backed up, try searching the respective eventdb file for that filename.

Because these support files, like the whole of TM backups, are now protected, before examining any of them, it’s best to make a copy in a working folder, and open that copy.

I can feel an app coming on…