- Haskell 99.5%
- C 0.3%
- Makefile 0.2%
The README says why tm exists, how to build it, and what it reads, and walks through a restore with placeholder paths. README, CLAUDE.md and the haddocks name the Mac, the file server and the board card generically instead of by name. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| cbits | ||
| src | ||
| test | ||
| TimeMachine | ||
| .gitignore | ||
| .hlint.yaml | ||
| CLAUDE.md | ||
| hie.yaml | ||
| LICENSE | ||
| Makefile | ||
| README.md | ||
| stack.yaml | ||
| stack.yaml.lock | ||
| timemachine.cabal | ||
tm
Gets files back out of a Mac's Time Machine backups without a Mac.
Time Machine on a network share writes its backups as a sparsebundle: a
directory of "band" files holding an APFS disk image, with one APFS snapshot
per backup. Off a Mac, nothing reads them well. libmodi reads zeros from v2
bundles, libfsapfs has no snapshots, and apfs-fuse doesn't support
sparsebundles. tm reads the bundle directly, on FreeBSD or macOS, including
the decmpfs compression APFS uses (zlib, LZVN, LZFSE, LZBITMAP), decoded in
pure Haskell.
It only ever reads the backup, and it never replaces anything at the destination.
tm snapshots BUNDLE
tm ls BUNDLE SNAPSHOT [PATH]
tm restore BUNDLE SNAPSHOT PATH DEST
Building
With Stack:
make release # optimized build, installed to ~/.local/bin/tm
Restoring a file
Time Machine rewrites the bundle every hour, and file data in APFS has no checksum, so read a snapshot of the bundle rather than the live copy. On ZFS:
zfs snapshot pool/timemachine@restore
b=/pool/timemachine/.zfs/snapshot/restore/MyMac.sparsebundle
Pick a backup. latest is the newest, or give any unique part of a name, such
as a date (2026-10-23):
tm snapshots "$b"
Find the file. A backup's files are under /<date>.backup/Data/, laid out
like the Mac's disk:
tm ls "$b" latest /
d=/2026-10-23-101500.backup/Data # the .backup name the line above printed
tm ls "$b" latest "$d/Users/alice"
Restore a file or a whole directory. DEST must not exist yet, and as root it
should be somewhere only root can write (not /tmp), since the path to it is
followed:
mkdir -m 700 /root/restore
tm restore "$b" latest "$d/Users/alice/notes.txt" /root/restore/notes.txt
When you're done, drop the snapshot:
zfs destroy pool/timemachine@restore
What comes back
- Files, directories, symlinks, modes and modification times. Sparse files stay sparse. A file with several names comes back hard linked between the names inside what you restored; names outside it aren't followed.
- Everything belongs to whoever ran
tm(often root). setuid and setgid bits are dropped, and so is the sticky bit on files.chown -Rit to whoever it's for. - Not restored: Finder tags and other extended attributes, ACLs, resource forks.
tm restorenames on stderr each file it couldn't restore, and then exits 1; the rest is still restored. A file compressed with a method newer than LZBITMAP (macOS 27 adds some) is skipped this way.- A name that couldn't be hard linked to the others is copied instead, with a
warning:line saying so; that alone still exits 0. - Interrupted (Ctrl-C, a dropped ssh session,
kill), it removes the file it was writing and exits nonzero; what it finished stays, its directories still mode 700. Restore again into a new DEST. Onlykill -9leaves a partial file, mode 0600. Undernohup, a dropped session doesn't stop it. - A name with accents has to be typed exactly as the Mac stored it. If it isn't
found, copy it from the
tm lsoutput, or restore its directory.
What it reads
v1 and v2 sparsebundles holding one unencrypted APFS volume, either bare (as
Time Machine writes them) or in a GPT partition map (as hdiutil does).
Encrypted backups, mounting, and writing to the bundle are deliberately out of
scope.
Development
make ready # format, lint, test
make fixture # macOS only: rebuild the test disk image from scratch
The tests run against a small APFS sparsebundle built on a Mac by
test/fixtures/make-fixture.sh. CLAUDE.md covers the on-disk
format as measured, and the invariants the code is held to.
License
BSD 3-Clause; see LICENSE.