tmutil is a handy tool to control Time Machine backups from the command line. I think Apple added it in Lion, but I don’t have a pre-Lion system to verify that.
“man tmutil” and “tmutil” (with no arguments) print helpful usage information, but I was surprised that there were no commands to see what destination Time Machine was currently using. I also couldn’t find a command to tell me if Time Machine was currently running.
I figured tmutil must know that information, so I went looking for it.
The short version:
I found commands to do what I wanted:
tmutil destinationinfo
prints out where Time Machine will backup to.
And these two commands will print out different views of the Time Machine status:
tmutil status tmutil currentphase
Of course, those commands are NOT documented by Apple, so they may not always work, but they seemed to work for me. YMMV, and they may set your computer on fire. No guarantees, blah blah blah. Taking advice from strangers on the internet is always a possible hazard to your health and happiness.
The long version:
Here’s how I found these undocumented/hidden commands.
First I figured out where the tmutil file lived:
$ which tmutil /usr/bin/tmutil
Then I figured out what kind of file it was:
$ file /usr/bin/tmutil /usr/bin/tmutil: Mach-O universal binary with 2 architectures /usr/bin/tmutil (for architecture x86_64): Mach-O 64-bit executable x86_64 /usr/bin/tmutil (for architecture i386): Mach-O executable i386
This told me the tmutil file was an executable program, as opposed to a shell script. If tmutil was a shell script, I would have opened it in a text editor and looked through it for a list of commands. However, since tmutil is an executable program, it won’t yield its secrets to us quite as easily as a shell script.
To dig through executable programs and files you’ll need the “strings” command. It exists on every unix-y OS, including OS X. It describes itself in “man strings” like this:
find the printable strings in a object, or other binary, file
So I ran:
strings /usr/bin/tmutil > tmutil-strings.txt
I opened up tmutil-strings.txt in a text editor (MacVim is my editor of choice, thanks for asking) and looked for a command that I knew existed, “startbackup”, because usually all of the supported command line options for a program will be near each other in the strings output. Here’s what I saw near the “startbackup” text:
/SourceCache/TimeMachineTools/TimeMachineTools-41.3/tmutil/tmutil_common.m EnumerateModulesWithBlock processor != NULL help enable disable startbackup <<<--- this is what I was searching for stopbackup enablelocal disablelocal snapshot delete restore compare setdestination destinationinfo addexclusion removeexclusion isexcluded inheritbackup associatedisk latestbackup listbackups machinedirectory calculatedrift uniquesize verifybackups currentphase status verifyadditions quickcheckimage GetVerbForVerbProc proc != NULL
From this output I guessed that everything between “help” and “quickcheckimage” was a command line option. And it looks like perhaps the “destinationinfo” and “status” commands might be what I was looking for. I ran tmutil with those options and it looked good, case closed!
Here’s a complete list of commands that appeared in the “strings /usr/bin/tmutil” output that aren’t described in “man tmutil” or “tmutil”:
currentphase destinationinfo quickcheckimage status verifyadditions verifybackups
I only tried “currentphase”, “destinationinfo”, and “status”. I’ll leave the rest up to curious readers.
So there you go: a brief walkthough of how to discover hidden and undocumented commands in an executable file. Of course, they may be hidden or undocumented for a reason: they may be buggy, unsupported, and have unforeseen and disastrous side effects. Use them at your own risk.
Excellent tip. I wish I had thought of using strings.
I saw the destinationinfo argument documented in the tmutil man page. I’m running MacOS 10.15.5 . I’ve been having backup trouble and am using ‘tmutil status’ a lot, but I’d sure like to find out what exactly each item in the output is supposed to be. I see things changing during a backup that don’t make sense. For instance the raw percentage completed seems to go over 100% and sometimes the files and/or totalfiles fields change without any change in bytes or totalbytes.