Time Machine: 11 tmutil

The three tools which Apple provides to control Time Machine are its System Preferences pane, the Time Machine app itself, and the command tool tmutil. This article summarise the capabilities and use of the last of those, and is based on the current release, version 4.0.0 supplied in Catalina 10.15.2.

Although the tmutil man page is up to date and worth referring to when using this tool, it originated before APFS snapshots, and you may find its use of that term confusing: it refers to backups as both backups and snapshots, and you should be very careful to check whether the word snapshots refers to Time Machine backups, or to APFS local snapshots.

Making backups

These replicate the controls available in the Time Machine pane.

sudo tmutil enable – turns automatic backups on
sudo tmutil disable – turns automatic backups off
tmutil startbackup – starts making a backup if one is not already in progress, and can take options –auto –block –rotation –destination. Of these, –auto is recommended, as the backup is then scheduled using the normal mechanism, and most closely resembles a regular automatic backup.
tmutil stopbackup – cancels the current backup in progress

Restoring from backups

tmutil restore source dest – restores the item source from a backup to the path dest. May require sudo.

Examining backups

tmutil latestbackup – prints the path to the latest backup
tmutil listbackups – prints the paths to all backups for this Mac
tmutil uniquesize path – report the actual size of a backup, excluding any hard links
tmutil calculatedrift machine_directory – analyses the amount of change between backups. May require sudo.
tmutil compare -options path1 path2 – a complex command which compares the contents of any two backups, or the Mac against the latest backup. Options specify what to include in the comparison, and how deep to look in the directory tree. Refer to the man page for full details.

Maintaining backups

tmutil verifychecksums path – report any problems with checksums in backups (10.11 and later)
sudo tmutil delete backup_path – deletes the backup specified. Use with great caution. This can be exceedingly slow to delete a set of backups, where it starts with the earliest and steadily chugs through removing them one by one.

Controlling backup destinations

tmutil destinationinfo – details the current backup destination
tmutil machinedirectory – prints the path to the current machine directory for this Mac
sudo tmutil setdestination mount_point – sets the destination to the mount_point given; when used without any option, this replaces the existing destination; with the -a option the new destination is added to the list rather than replacing it.
sudo tmutil setdestination [-ap] protocol://user[:pass]@host/share – sets the destination to an AFP or SMB network share. The -p option brings an interactive prompt to enter the password.
sudo tmutil removedestination destination_id – removes the backup destination from the list; use the destination_id UUID given by destinationinfo.
sudo tmutil inheritbackup backup_set – claims an existing set of backups, which can be a sparsebundle, for the current Mac
sudo tmutil associatedisk [-a] mount_point volume_backup_directory – reconfigures backup history by binding a volume directory to the local disk. Read the man page carefully before using this.

Controlling exclusions

These largely replicate controls available in the Time Machine pane, but provide fine control over ‘sticky’ or fixed path exclusion which can be useful.

tmutil addexclusion [-p|-v] item – adds item to the exclusion list. Use -p for a fixed path exclusion, or -v for a whole volume.
tmutil removeexclusion [-p|-v] item – removes the given item from the exclusion list using the same options
tmutil isexcluded item – reveal whether a given item is in the current exclusion list

Snapshots

These commands should work with Mobile Time Machine snapshots in 10.12 and earlier, but are most useful with APFS snapshots made from 10.13 onwards.

tmutil localsnapshot – make a fresh snapshot of all backed up volumes
tmutil listlocalsnapshots mount_point – list local snapshots of the specified volume
tmutil listlocalsnapshotdates [mount_point] – list dates of all local snapshots, or for the specified volume
tmutil deletelocalsnapshots [mount_point | snapshot_date] – delete the specified local snapshots, or for a volume or date
tmutil thinlocalsnapshots mount_point [purgeamount] [urgency] – thin local snapshots for the specified volume. You can specify the purgeamount of space to reclaim, and the urgency on a scale of 1-4.

General

tmutil version – returns version information for tmutil but not Time Machine itself
tmutil – returns usage info, summarising the commands available.