tmutil
Time Machine utility

tmutil verb [options]

Control and interact with Time Machine, as well as examining and manipulating backups, including restoring data from backups, editing exclusions, and comparing backups.

Verbs

verbs shown in brown require root privledge.
latestbackup displays the path to the most recent snapshot for this computer.
tmutil latestbackup
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-26-104514
listbackups displays paths for all of this computer's completed snapshots.
 tmutil listbackups
/Volumes/bakvol/Backups.backupdb/mymac/2011-07-04-120352
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-12-201512
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-13-000030
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-17-224109
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-25-190029
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-25-200021
/Volumes/bakvol/Backups.backupdb/mymac/2011-08-25-210025
machinedirectory Displays the path to the current machine directory for this computer.
tmutil machinedirectory
/Volumes/bakvol/Backups.backupdb/mymac
enable
disable
Turn on/off automatic backups.
enablelocal
disablelocal
Turn on local Time Machine snapshots.
Turn off local Time Machine snapshots and trigger automatic cleanup of accumulated local snapshot data.
restore [-v] src …   dst Restore src, inside a snapshot, to dst.
The dst argument uses the destination path semantics of cp.

When using restore, tmutil behaves like Finder.
Custom Time Machine metadata (extended security and other) will be removed from the restored data, and other metadata will be preserved.

Root privileges may be required to perform restores depending on dst.
cp or ditto.
When restoring as root, ownership of the restored items will match the state of the items in the backup.

snapshot Create new local Time Machine snapshot.
startbackup [-b | --block] equivalent to choosing "Back Up Now" from the Time Machine menu extra.
--block wait (block) until the backup is finished before exiting.
stopbackup Cancel a backup currently in progress.
addexclusion item … file, directory

location-independent exclusion(sticky) :
        Moved item is still excluded.
        Copy of item retains the exclusion.

addexclusion -p path … fixed-path exclusion:
Files within the path at the time of the backup are excluded.

Volume exclusions are implicitly fixed-path exclusions and are retained if the volume name or mount path changes.
Erasing the volume clears it's exclusions. (See associatedisk.)

removeexclusion [-p] item
isexcluded item … Determine if a file, directory, or volume are excluded from Time Machine backups.
tmutil isexcluded /Applications/Copland.app
[Included]    /Applications/Copland.app

tmutil isexcluded /Volumes/OtherSysSaves/kitchen
[Excluded]    /Volumes/OtherSysSaves/kitchen
delete snapshot_path … in an arbitrary machine directory.
Can delete snapshots from backups that were not made by, or are not claimed by, the current machine.
calculatedrift machine_directory Analyze the snapshots in a machine directory and determine the amount of change between each.
Averages are displayed after all snapshots have been analyzed.
Root privileges may be required, depending on the contents of the machine directory.
 tmutil calculatedrift /Volumes/bakvol/Backups.backupdb/mymac

2011-07-04-120352 - 2011-08-12-201512
-------------------------------------
Added:         2.2G
Removed:       32.5G
Changed:       969.8M

2011-08-12-201512 - 2011-08-13-000030
-------------------------------------
Added:         78.9K
Removed:       0B
Changed:       256.4K

...

2011-08-25-200021 - 2011-08-25-210025
-------------------------------------
Added:         1.7M
Removed:       0B
Changed:       79.1M


Drift Averages
-------------------------------------
Added:         1.8G
Removed:       3.2G
Changed:       157.9M
uniquesize path ... Analyze the specified path and determine its unique size.
Things that only exist in the specified path; things that are hard-linked in other places are not tallied.
tmutil uniquesize /Volumes/DGerman1a/Backups.backupdb/smackerPro/0 
compare [-@esmugtdrEX]
[-D depth] [-I name]
[
snapshot_path |
 path1 path2]
create a diff listing

full example

  • No arguments: compare the computer to the latest snapshot.
  • One snapshot path: compare the computer to the specified snapshot.
  • Two path: compare two snapshots .

    Default property set: -smugt .

    compare vary operation
    -a all supported metadata -D limit traversal depth to depth levels from the beginning of iteration
    -@ extended attributes -I Ignore paths with a path component equal to name during iteration. May be specified multiple times
    -e ACLs
    -s sizes -X output in XML property list format
    -m file modes -E don't take exclusions into account when comparing items inside volumes
    -u UIDs
    -g GIDs -r ignore specified root paths and compare descendents instead
    -t modification times
    -d file data forks -v verbose depricated
  • setdestination [-p] argConfigure a local HFS+ volume or AFP share as the backup destination.

    To set an HFS+ volume as the backup destination, arg is the mount point of the volume.
    When setting an AFP destination arg takes the form: afp://user[:pass]@host/share

    -p password interactive prompt.

    inheritbackup {machine_directory |
                     sparsebundle}
    Claim a machine directory or sparsebundle for use by the current machine.

    Machine directories and sparsebundles are owned by one computer at a time,
    and are tracked by unique identifiers. inheritbackup reassigns the identity of the specified item, reconfiguring it so the current host recognizes it during backups.
    When inheriting a sparsebundle, the machine directory within will also be claimed.

    Inheriting is typically only one step in the process of configuring a backup for use by a machine.
    See setdestination and/or associatedisk

    One machine can own multiple machine directories and sparsebundles , but it is ill-advised for them to reside in the same place.

    inheritbackup attempts to detect identity collisions before making changes.

    1/1/13, The backup "oldMachine" can't be inherited because it would conflict with "machine 3".

    associatedisk [-a] mount_point          snapshot_volume Bind a snapshot volume directory to the specified local disk and configure the backup history.

    Time Machine uses the HFS+ volume persistent UUID assigned when the file system was created to associate a source volume and a snapshot volume.

    Erasing a volume creates a new file system on the disk and previous assocation to a time machine snapshot is broken.
    After restoring a volume's contents, use associatedisk to have Time Machine consider the volume backed up.

    sudo tmutil associatedisk -a /Volumes/MyNewStuffDisk
              /Volumes/Chronoton/Backups.backupdb/therm/Latest/MyStuff

    -a all snapshot volumes in the same machine directory that match the MyStuff will be associated .

    help [verb] Display usage for a verb.

    tmutil without verb reports:

    Usage: tmutil help  
    Usage: tmutil version 
    Usage: tmutil enable 
    Usage: tmutil disable 
    Usage: tmutil startbackup [-b | --block] [-r | --rotation] [-d | --destination dest_id] 
    Usage: tmutil stopbackup 
    Usage: tmutil enablelocal 
    Usage: tmutil disablelocal 
    Usage: tmutil snapshot 
    Usage: tmutil delete snapshot_path ...  
    Usage: tmutil restore [-v] src dst 
    Usage: tmutil compare [-a@esmugtdEX] [-D depth] [-I name]
           tmutil compare [-a@esmugtdEX] [-D depth] [-I name] snapshot_path
           tmutil compare [-a@esmugtdEX] [-D depth] [-I name] path1 path2
    
    Usage: tmutil setdestination [-a]  mount_point
           tmutil setdestination [-ap] afp://user[:pass]@host/share 
    Usage: tmutil removedestination destination_id 
    Usage: tmutil destinationinfo [-X] 
    Usage: tmutil addexclusion [-p] item ...  
    Usage: tmutil removeexclusion [-p] item ...  
    Usage: tmutil isexcluded item ...  
    Usage: tmutil inheritbackup machine_directory
           tmutil inheritbackup sparse_bundle 
    Usage: tmutil associatedisk [-a] mount_point volume_backup_directory 
    Usage: tmutil latestbackup 
    Usage: tmutil listbackups 
    Usage: tmutil machinedirectory 
    Usage: tmutil calculatedrift machine_directory 
    Usage: tmutil uniquesize path ...  
    Use `tmutil help ` for more information about a specific verb.

    Backup Structures

    "realms" associated with Time Machine backups, definitions:  
    backup source volume currently being backed up by Time Machine.
    backup disk HFS+ volume that contains Time Machine backups.
    backup destination In the case of a local destination, a synonym for backup disk.
    For network destinations, this is the AFP share on which the backup disk image resides.
    backup disk image
    backup image
    sparsebundle that, when mounted, is the backing store for a volume that is a backup disk.
    backup store top-level Backups.backupdb directory at the root of a backup disk.
    machine directorydirectory inside a backup store that contains all the backups for a particular computer.
    For local destinations, a backup store can contain multiple machine directories, all for separate computers.
    snapshotdirectory inside a machine directory that represents a single initial or incremental backup of one computer.
    "snapshot", in most contexts, is a generic term and is not to be confused with a "local Time Machine snapshot", which is simply a snapshot stored locally on the computer.
    snapshot volumedirectory inside a snapshot that represents a single initial or incremental backup of one backup source. Example:
    /Volumes/Chronoton/Backups.backupdb/thermopylae/2011-07-03-123456/Mac HD

    Files

     /System/Library/LaunchAgents/com.apple.TMLaunchAgent.plist:
    
    <key>Label</key> <string>com.apple.TMLaunchAgent</string>
        <key>ProgramArguments</key>
        <array> <string>/System/Library/CoreServices/backupd.bundle/
                                         Contents/Resources/TMLaunchAgent.app/Contents/MacOS/TMLaunchAgent</string> </array>
        <key>StartOnMount</key> <true/>
    
    /System/Library/LaunchDaemons/com.apple.mtmfs.plist: 
     <key>Disabled</key> <true/>
        <key>EnableTransactions</key> <false/>
        <key>KeepAlive</key> <true/>
        <key>Label</key> <string>com.apple.mtmfs</string>
        <key>MachServices</key> <dict> <key>com.apple.mtmfs</key> <true/> </dict>
        <key>ProgramArguments</key>
        <array>
            <string>/System/Library/CoreServices/backupd.bundle/Contents/Resources/mtmfs</string>
            <string>--tcp</string>
            <string>--resvport</string>
            <string>--listen</string>
            <string>localhost</string>
            <string>--oneshot</string>
            <string>--noportmap</string>
            <string>--nobrowse</string>
        </array>
        <key>RunAtLoad</key> <true/> 
    
    
    <key>Label</key> <string>com.apple.mtmd</string>
        <key>MachServices</key>
        <dict>
            <key>com.apple.mtmd.xpc.ondemand</key> <true/>
            <key>com.apple.mtmd.xpc</key> <dict> 
            <key>HideUntilCheckIn</key> <true/> </dict>
        </dict>
        <key>ProgramArguments</key> <array> <string>/System/Library/CoreServices/backupd.bundle/Contents/Resources/mtmd</string> </array>
        <key>KeepAlive</key> <dict> <key>Crashed</key> <true/> </dict>
        <key>POSIXSpawnType</key> <string>Interactive</string>
        <key>EnvironmentVariables</key> <dict>
            <!--Uncomment to enable various debugging options-->
            <!--<key>WaitForDebugger</key>--> <!--<true/>-->
            <!--<key>MallocScribble</key>--> <!--<string>1</string>-->
            <!--<key>MallocStackLogging</key>--> <!--<string>1</string>--> </dict>
        <key>CFBundleIdentifier</key> <string>com.apple.backup.launcher</string>
    
    
    

    TimeMachine writes messages like these to system.log and syslog with level = notice

    Feb 14 17:44:10 smackerpro com.apple.backupd[14355]: Copied 702 items (22.1 MB) from volume DATA. Linked 45215.
    Feb 14 17:44:24 smackerpro com.apple.backupd[14355]: Copied 2 items (14 bytes) from volume Photos. Linked 93.
    Feb 14 17:44:31 smackerpro com.apple.backupd[14355]: Copied 56 items (7.1 MB) from volume Macintosh HD. Linked 652.
    Feb 14 17:44:34 smackerpro com.apple.backupd[14355]: Created new backup: 2016-02-14-174434
    Feb 14 17:44:36 smackerpro com.apple.backupd[14355]: Starting post-backup thinning
    Feb 14 17:44:36 smackerpro com.apple.backupd[14355]: No post-backup thinning needed: no expired backups exist
    Feb 14 17:44:36 smackerpro com.apple.backupd[14355]: Backup completed successfully.
    
    sudo defaults write /System/Library/Launch Daemons/com.apple.backupd-auto StartInterval -int 1800