Repository navigation
feat(docs-tidy): quarterly plan-then-apply tidy of ~/Documents - #10
Merged
Merged
Conversation
added 4 commits
October 21, 2026 14:42
Repeats the 2026-10-21 manual cleanup on a schedule. A LaunchAgent runs `docs-tidy plan --notify` at 10:00 on Jan/Apr/Jul/Oct 1; nothing moves until Andrew runs `docs-tidy apply`. The plan covers four sections: archive (units untouched since Jan 1 of year-4) to My Drive/Documents Archive, old machine snapshots merged or stashed, cross-unit byte-identical dupes stashed to My Drive/probably-dupes/<date>, and credit-report renames plus Finder tags. Apply copies, re-hashes, then deletes; it refuses stale plans, a missing Drive root, or too little free disk, and prefetches dataless iCloud files with brctl (the manual run lost 9 files to ETIMEDOUT). Python rather than Bash: the job reads DriveFS SQLite, hashes files and writes binary plists.
- Credit retag keeps the user's own Finder tags (and colours); it only adds a missing canonical tag, and plans a retag only in that case. - The rename log row is written at rename time; a tag-write failure is a note on an OK result, not an ERR. - A snapshot file whose target unit is archived in the same plan is stashed, not merged back into the archived unit. - Notifications pass title and message to osascript as argv, so no AppleScript escaping, and a nonzero exit is logged. - apply writes its TSV before the pointer and cleanup steps. - Unreadable directories are reported, and their unit never archives. - A failed or unverified copy removes its partial destination.
- The credit rename log is written with the apply TSV, before the pointer and cleanup steps, so a failure there cannot lose it. - read_tags returns None (unknown) on a failed xattr read or a bad plist, so apply falls back to the planned tags instead of dropping the user's own tags. A missing xattr still means no tags. - unit_newest treats an archive unit that is already gone as moved, not unreadable; os.walk calls onerror for a missing top directory, which made a re-run skip finished units.
The keep-one rule (earliest mtime) picked the wrong copy on real data: it would have kept a write-up in a scratch Codex output folder and stashed the copy in Beacon Biosignals, and pulled 7 files out of a deliberately assembled HELOC packet. No rule can tell which copy is the one in use, so the plan now lists every copy in each cross-folder group and apply never moves them. `dupes` is no longer an apply section, so `--skip dupes` is rejected. Machine-snapshot de-duplication is unchanged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
docs-tidy.pyrepeats the 2026-10-21 manual cleanup of~/Documentsevery quarter, as plan, then approve:com.asiago.docs-tidy(LaunchAgent) runsdocs-tidy plan --notifyat 10:00 on Jan 1, Apr 1, Jul 1 and Oct 1. It writes a plan to~/.local/state/docs-tidy/and posts a notification with the counts. If the plan fails, it posts a FAILED notification.docs-tidy showprints the plan. Nothing moves untildocs-tidy apply. Pass--skip SECTIONto leave a section out; it can be repeated.Plan sections:
tax/<year>is its own unit. Items on a KEEP list never move.Documents - <HOST>folders, merges unique files back into Documents and stashes duplicate copies.node_modules, bundles, and files under 1 KiB.Apply copies each file, re-hashes the copy, then deletes the source. It refuses a plan older than 14 days, a missing Drive root, or too little free disk space. Before copying, it downloads cloud-only iCloud files with
brctland retries on ETIMEDOUT.Design:
docs/plans/2026-10-21-docs-tidy-design.md. The script is Python because it reads the DriveFS SQLite database, hashes files and writes binary plists.Verification
bats tests/docs-tidy.bats: 41/41 pass, on Python 3.15 and 3.9.bats tests/: 342/342 pass locally, measured at commit 15f0810.shellcheck -S info: clean.~/Documents, the Drive mount and the DriveFS database with no TCC prompt.~/Documentstook about 1 s and downloaded nothing. Result: archive 0, snapshot-merge 4, credit 0, and 18 dupe groups listed for review.Known gaps (from review, not fixed)
Not in this PR
docs-tidy.pyto~/.local/bin/docs-tidyand the plist into~/Library/LaunchAgents, then bootstrap the agent. Rename the Drive folderDocuments Archive (pre-2022)toDocuments Archive.