Controlling Time Machine From Terminal

In a previous tutorial, I showed how to get started with Time Machine, OS X’s built in backup utility. Time Machine is very simple to set up and use, however, if you want more control over it, you’ll need to break out one of OS X’s oldest applications: Terminal.
Through the Time Machine utility Terminal command—abbreviated to tmutil—you can control any aspect of a Time Machine setup, and also find out more information about it.
This tutorial will introduce, and provide an overview of, controlling Time Machine from the Terminal. To cover every tmutil command in detail would require far more than just one article. Once you have got the basics down, however, the more complicated commands will be easy to understand.
Before starting this tutorial, it’s important to note that a Time Machine drive must be connected to the Mac you are using. The tmutil commands will not work otherwise.

Getting Started

Controlling a computer from the command line is notorious for having a steep learning curve. OS X’s tmutil is no exception. Luckily, there are a number of help features built in.
Although it is unlikely to make much sense at the moment, to get a complete list of all the available tmutil commands—along with what they do and how to use them—enter man tmutil into Terminal. The command man—short for manual—does the same for many other Terminal commands.

The tmutil command's manual.

To get more information on a single tmutil command, there is no need to root through the manual. Enter tmutil help [command] where [command] is the command you want more information on. Terminal will then provide detailed information about it. For example, entering tmutil help enable will describe what the enable command does and inform you that it needs root privileges to run.

Users and Super Users

When you are using the Terminal, you have access to many parts of OS X that are impossible to get to normally. It is possible to entirely break a Mac if you aren’t careful. To protect against accidental—and deliberate—damage, OS X uses the concept of users and super users. Users don’t have access to many of the root, or administrative, features of OS X that super users do.
Often when using Terminal, you will need to run commands as a super user for them to work. To do this, enter sudo—super user do—before the regular command. You will be prompted to enter your password. Do so and press Return. Note, as a security feature you won’t see anything as you type your password.

Simple Commands

Many of the simple tmutil commands can be done using the Time Machine menubar icon, or System Preferences pane. It can be quicker, however, to just use Terminal.

Enabling and Disabling Time Machine

Enabling and disabling Time Machine from Terminal requires super user powers. To enable Time Machine enter sudo tmutil enable followed by your password and Return.
To disable Time Machine instead, enter sudo tmutil disable, your password and then Return.

Starting and Stopping Backups

If you’ve just transferred some important files to a Mac, you may want to perform a Time Machine backup straight away. To do it, enter tmutil startbackup.
If, on the other hand, you are on the way out the door and need to stop a backup so you can disconnect the Time Machine drive, enter tmutil stopbackup.

Excluding Specific Files and Folders

Sometimes there can be a file or folder you don’t want to have backed up to Time Machine; perhaps your backup drive is low on space and you have a redundant 100GB folder filled with movies.
To add an exclusion you, once again, need super user access. Enter sudo tmutil addexclusion [path] where [path] is the path to the file or folder you want to exclude. For example, if I wanted to exclude my Mac’s Movies folder, I would enter sudo tmutil addexclusion /Users/harryguinness/Movies. As with any sudo command, you will need to enter your password.
To remove an exclusion you use the inverse command, removeexclusion. Enter sudo tmutil removeexclusion [path] where [path] is the path to the file or folder you want to re-include—sudo tmutil removeexclusion /Users/harryguinness/Movies to continue my example from above.

Checking to see if the Movies folder is excluded from Time Machine.

To check if a file or folder is excluded from the http://www.bbc.co.uk/news/entertainment-arts-29536370 backup, you can use the command tmutil isexcluded [path] where [path] is the path to the file or folder you want to check.

Getting Information About Backups

One of the most useful features of tmutil is its ability to provide you with information and statistics about a Time Machine drive that you can’t get using the menubar icon or System Preferences pane.

Finding Backup Locations

There are a few commands that will display information about where backups are located.
Using tmutil destinationinfo displays a list of all the Time Machine destinations associated with a Mac, there mount points, IDs and whether they are local or network backups.
To get the location of the latest backup, use tmutil latestbackup. Terminal will display the path to it. The final folder will be in YYYY-MM-DD-HHMMSS format so you can work out when it was made by comparing that information to the current time.
To get a list of all Time Machine backups, use tmutil listbackup. This will display a list of the paths to all the backups stored in Time Machine. Time Machine stores hourly backups for a day, daily backups for a month and weekly backups indefinitely; this list will reflect that.

The results of the tmutil listbackup command.

Some tmutil commands can only be run on the Machine Directory; the folder which stores all the individual backups. You can work it out by ignoring the date folder in the path to any backup but it is easier to use the command tmutil machinedirectory to display the path.

Comparing Backups

To compare the contents of two backups use the tmutil compare command. If you run tmutil compare without arguments, the current computer state will be compared with the most recent backup.
If you run tmutil compare “[path_1]” “[path_2]” where [path_1] and [path_2] are the locations of two different backups, the changes between the two will be compared. Terminal will display a list of all the files that have been added, removed or changed as well as the total size of all the changes.
For example, running tmutil compare “/Volumes/Storage/Backups.backupdb/Harry’s Mac Pro/2014–09–25–095831” “/Volumes/Storage/Backups.backupdb/Harry’s Mac Pro/2014–09–25–073640” compared the backups made at 10am and 7.30am this morning.

Comparing Backup Changes Over Time

The tmutil compare command can only handle two backups at once. To find the difference between all your backups over time, use the tmutil calculatedrift command. Enter tmutil calculatedrift “[machine_directory]” where [machine_directory] is the Machine Directory of the Time Machine volume. The drift—or change from one backup to the next—for every backup will be calculated and displayed in Terminal along with the averages.

The drift in my most recent three backups as well as the average over time.

The drift in your early backups will be larger than your more recent ones because of how Time Machine stores hourly and daily backups. You may need to run calculatedrift as a super user.
For example, I ran sudo tmutil calculatedrift “/Volumes/Storage/Backups.backupdb/Harry’s Mac Pro/”.

Conclusion

In this tutorial I’ve introduced you to some of the basic tmutil Terminal commands. There are many others that can be used to do things like change backup locations or move a Time Machine backup to another Mac.
To find out more about all the tmutil commands available, use man tmutil. If you’ve followed this tutorial, it should now make total sense to you.