tmexcludes - Manage Time Machine exclusions! 🚀

Fast, light macOS utility that shows, backups and restores the list of files and folders you have excluded from Time Machine. These can also be managed from the Time Machine pane of System Settings.

Catpuccin Mocha theme, Menlo font.

Motivation

tmexcludes allows extracting and manage Time Machine exclusions independently of other settings, making it easier to sync multiple workstations and add further processing in between the processes.

For example, one could automate certain tasks on specific folders, provided they are in present in the list. tmexcludes streamlines the overall workflow, making easier to maintain consistent settings across macOS installs.

These excluded paths are saved in /Library/Preferences/com.apple.TimeMachine.plist, stored inside the SkipPaths array. Running a basic cp, mv on the .plist file could take care of backing up and restoring these settings.

Additionally, macOS provides an alternative way of managing with defaults:

# Store the .plist path into a variable
$ plist="/Library/Preferences/com.apple.TimeMachine.plist"

# Export our Time Machine settings
$ defaults export $plist TimeMachineConfig.plist

# Load our saved settings
$ defaults import $plist TimeMachineConfig.plist

Highlights

• 🚀 Fast - minimal overhead, tmexcludes.sh only adds ~ 2.5 ms of overhead.¹
• 🎨 Intuitive - user-friendly, clear way to export and restore excluded Time Machine paths.
• 🔒 Robust - ensures that the format passed to defaults read is a proper array.
• 📦 Self-contained - no dependencies, lightweight, uses POSIX sh, awk (e.g. 1586 bytes, 91 lines).

Getting Started

Note

This utility is only intended to work in macOS.

If you have brew installed, just run:

$ brew install Neved4/tap/tmbackup

Otherwise, first clone the repo:

$ git clone https://github.com/Neved4/tmexcludes

Usage

The following options are available:

usage: tmexcludes <command> ...

Commands:
  list        List current exclusions
  dump        Write exclusions to output
  load <file> Load excludes from file
  system      List built-in system excludes

Examples

Warning

Always backup your settings first before modifying defaults.

List the exclusion settings:

$ ./tmexcludes.sh list
(
    "/opt/homebrew",
    "/usr/local/texlive"
)

Write all exclusion settings into output:

$ ./tmexcludes.sh dump > excludes.plist
(
    "/opt/homebrew",
    "/usr/local/texlive"
)

Restore the settings at a later point:

$ ./tmexcludes.sh load excludes.plist

Done!

Standards

This script is compatible with ISO 9945:2009, also known as POSIX.1-2017.²

License

This repository is licensed under the terms of the MIT License.

Footnotes

1. Measured with hyperfine. ↩

2. IEEE Std 1003.1-2017: Standard for Information Technology — Portable Operating System Interface (POSIX®), ISO/IEC/IEEE 9945:2009/COR 2:2017. URL: https://pubs.opengroup.org/onlinepubs/9699919799/ ↩