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] arg| Configure 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.
defaults read /Library/Preferences/com.apple.TimeMachine.plist Destinations edited
defaults read /Library/Preferences/com.apple.TimeMachine.plist
{
AlwaysShowDeletedBackupsWarning = 1;
AutoBackup = 1;
(
{
BackupAlias = <0 01260002 00010944 4765726d 616e3161 0 0 0 0 0000c8ac 6c1f482b 0 00010944 4765726d 616e3161 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0002c8ac 6c1f0000 0 0000ffff ffff0000 09000000 0 0 0 00094447 65726d61 6e316100 00100008 0000c8ac a45f0000 00110008 0000c8ac a45f0000 00010000 00020013 44476572 6d616e31 613a4447 65726d61 6e316100 000e0014 00090044 00470065 0072006d 0061006e 00310061 000f0014 00090044 00470065 0072006d 0061006e 00310061 00120000 00130012 2f566f6c 756d6573 2f444765 726d616e 3161ffff 0000>;
DateOfLatestWarning = "2019-06-25 16:24:45 +0000";
DestinationID = "AE9B1E0A-A1F1-408B-8118-E572456F0372";
DestinationUUIDs = ( "B2BA3CA8-984F-39F5-8A16-261BCBC2CE28");
LastKnownEncryptionState = NotEncrypted; RESULT = 18;
RootVolumeUUID = "D12613A2-FB47-3DF4-8035-9DB9DD6E5E01";
SnapshotDates = (
"2016-02-14 20:49:45 +0000", "2016-02-26 00:00:38 +0000", "2016-03-05 21:17:04 +0000",
…
"2017-03-26 16:13:42 +0000", "2017-04-16 01:52:10 +0000", "2017-04-16 02:36:05 +0000");
},
{
BackupAlias = <0 016e0002 00011273 6d616370 726f5469 6d654d61 6368696e 65000000 0 0000d571 c23a482b 0 00011273 6d616370 726f5469 6d654d61 6368696e 65000000 0 0 0 0 0 0 0 0 0 0 0 0002d571 c23a0000 0 0000ffff ffff0000 09000000 0 0 0 0012736d 61637072 6f54696d 654d6163 68696e65 00100008 0000d571 fa7a0000 00110008 0000d571 fa7a0000 00010000 00020025 736d6163 70726f54 696d654d 61636869 6e653a73 6d616370 726f5469 6d654d61 6368696e 6500000e 00260012 0073006d 00610063 00700072 006f0054 0069006d 0065004d 00610063 00680069 006e0065 000f0026 00120073 006d0061 00630070 0072006f 00540069 006d0065 004d0061 00630068 0069006e 00650012 00000013 001b2f56 6f6c756d 65732f73 6d616370 726f5469 6d654d61 6368696e 6500ffff 0000>;
BytesAvailable = 297727688704; BytesUsed = 368677650432;
DestinationID = "014FFD4C-0482-4517-9570-812CBF7FBAB3";
DestinationUUIDs = ( "6AC7B43D-0761-3820-8CB5-D8E59169F4EF");
LastKnownEncryptionState = NotEncrypted;
RESULT = 100;
RootVolumeUUID = "D12613A2-FB47-3DF4-8035-9DB9DD6E5E01";
}
)
ExcludeByPath = ( "/Users/Shared/adi");
HostUUIDs = ( "9205DB27-ADBE-5C67-B58F-AE743BF777D9");
LastConfigurationTraceDate = "2018-07-21 19:03:31 +0000";
LastDestinationID = "014FFD4C-0482-4517-9570-812CBF7FBAB3";
LocalizedDiskImageVolumeName = "Time Machine Backups";
MobileBackups = 1;
PreferencesVersion = 4;
RequiresACPower = 0;
SkipSystemFiles = 0;
}
No BACKUP_COMPLETED_DATE !
errors
Unable to locate machine directory for host.
sudo defaults write /System/Library/Launch Daemons/com.apple.backupd-auto StartInterval -int 1800
COmmand+Shift+G opens GoToFolder dropdown. see /privat/etc