Sunset Snapshot
Takes a copy of one folder each evening, when the sun sets where you are.
Unchanged files are linked, not copied. Nothing is ever deleted.
A backup set for 02:00 runs only if the machine is awake at 02:00.
uv run sunset.py when --lat 52.52 --lon 13.40 --days 3
Sunset Snapshot is one Python file, standard library only, for macOS and Linux. It keeps a complete copy of one folder of yours, once per evening, at the first quarter hour after the sun sets at your latitude and longitude. Each copy is an ordinary folder named for the minute it began (2026-10-13T18-30); files that did not change since the last copy are hard links to it and take no new space, and every copy carries a SUNSET.sha256 manifest. Its real input is your folder (--src), an existing destination folder (--dest), your own latitude and longitude (--lat, --lon, north and east positive; 52.52 and 13.40 above are Berlin, use yours) and this machine's clock. Run every command from this folder with uv run sunset.py ...; there is nothing to install.
Use
uv run sunset.py when --lat 52.52 --lon 13.40 --days 3
uv run sunset.py snap --src ~/Documents --dest /Volumes/Backup/sunset --lat 52.52 --lon 13.40
uv run sunset.py install --src ~/Documents --dest /Volumes/Backup/sunset --lat 52.52 --lon 13.40
uv run sunset.py verify --dest /Volumes/Backup/sunset
The destination folder must already exist; the tool never makes one. Run snap once by hand before install: the first snap writes the register (sunset.log, first line Register of <src>. Latitude 52.52. Longitude 13.40.), and the scheduled tick only writes into a destination that holds the register for the same source. An unmounted drive is therefore refused, not filled.
install writes a launchd agent (~/Library/LaunchAgents/mom.normalisdead.sunset-snapshot.plist) on macOS or a systemd user timer (~/.config/systemd/user/sunset-snapshot.timer and .service) on Linux, firing at minutes 00, 15, 30 and 45. Each firing runs tick, which does nothing before sunset and nothing once today has its evening copy. install --print shows the unit and writes nothing. uninstall removes the unit and touches no snapshot.
install prints the Python it wrote into the unit (Python <path>.). Run install again after removing or upgrading that Python.
verify copies a snapshot to a scratch folder by plain reads and writes, hashes every file and compares with the manifest, then deletes the scratch folder. Without the tool, sha256sum -c SUNSET.sha256 (or shasum -a 256 -c SUNSET.sha256) inside any snapshot does the same check in place.
Notes
- Times are printed in this machine's time zone. The latitude and longitude set the sun; the machine's clock sets the zone.
- The sunset is the geometric one, on a flat horizon at sea level. Hills and buildings are not known.
- Where the sun does not set (polar day or polar night), the copy is taken at the first firing after 00:00, and the log says
No sunset. - macOS extended attributes and ACLs are not preserved.
- On macOS, a launchd job that reads
~/Documentsor writes to an external drive may need Full Disk Access for the Python named byinstall. A denial is written tosunset.logas a datedNo snapshot. Operation not permitted.line, never as silence. - The destination must support hard links: APFS, HFS+, ext4, XFS, Btrfs. exFAT and FAT are refused (
Destination cannot hard link. Nothing was copied.). - Symbolic links are copied as links, never followed. FIFOs, sockets and device files are skipped.
- To delete an old snapshot, delete its folder (
rm -rf /Volumes/Backup/sunset/2026-10-13T18-30, or move it to the Trash). Files are stored read-only; the folders are not, and the other snapshots keep their own links. - The tool never deletes anything except its own unfinished
.partial-and.restore-folders.
The log
<dest>/sunset.log is the only report, one line per evening. Its shape, as an illustration (not a real register):
Register of /Volumes/Docs. Latitude 52.52. Longitude 13.40.
2026-10-13 Sunset 18:16. Snapshot 18:30. 214 files.
2026-10-14 Sunset 18:14. No snapshot.
2026-10-15 Sunset 18:12. Snapshot 21:05. 214 files.
A day the machine was off is written once, when the next copy succeeds. A day the machine woke late shows a later second time.
Checking catch-up
The catch-up after sleep cannot be tested on a machine that does not sleep, so check it once on yours. On macOS: after install, before sunset, run pmset sleepnow (or close the lid) and leave it asleep past sunset. Wake it. Within a minute or two sunset.log has a new line whose second time is the minute you woke it. On Linux: systemctl suspend, then the same. Persistent=true on the timer and launchd's calendar interval both run a missed firing at wake.
Tests
uv run python -m unittest test_sunset
bash qa/accept.sh
The unit tests make their own temporary folders and inject the clock. qa/accept.sh runs the end to end checks of BUILD.md on Linux, using a copy of the Python standard library's email package as a real source folder, and needs sudo for one FAT mount. qa/scenes.sh and qa/shots.py make the terminal screenshots in shots/.
Colophon
Set in the reader's own terminal font. The sunset follows the NOAA Global Monitoring Laboratory solar calculator. The hard-link rotation follows rsync --link-dest and Mike Rubel's 2001 note on snapshot-style backups.
normal is dead
Files
- README.md
- out/accept-run.txt
- out/panes/help-48x40.txt
- out/panes/help-80x24.txt
- out/panes/install-48x40.txt
- out/panes/install-80x24.txt
- out/panes/refusals-48x40.txt
- out/panes/refusals-80x24.txt
- out/panes/snap-48x40.txt
- out/panes/snap-80x24.txt
- out/panes/verify-48x40.txt
- out/panes/verify-80x24.txt
- out/panes/when-48x40.txt
- out/panes/when-80x24.txt
- sunset.py
- test_sunset.py