{"id":13863067,"url":"https://github.com/emcrisostomo/Time-Machine-Cleanup","last_synced_at":"2025-07-14T13:33:25.938Z","repository":{"id":31382203,"uuid":"34945269","full_name":"emcrisostomo/Time-Machine-Cleanup","owner":"emcrisostomo","description":"Zsh script to clean up Time Machine backups and reduce its size","archived":false,"fork":false,"pushed_at":"2024-04-12T18:40:42.000Z","size":291,"stargazers_count":140,"open_issues_count":5,"forks_count":12,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-11-15T09:05:50.204Z","etag":null,"topics":["time-machine"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emcrisostomo.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-02T11:28:27.000Z","updated_at":"2024-11-06T10:01:38.000Z","dependencies_parsed_at":"2024-08-05T06:06:07.410Z","dependency_job_id":null,"html_url":"https://github.com/emcrisostomo/Time-Machine-Cleanup","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emcrisostomo%2FTime-Machine-Cleanup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emcrisostomo%2FTime-Machine-Cleanup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emcrisostomo%2FTime-Machine-Cleanup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emcrisostomo%2FTime-Machine-Cleanup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emcrisostomo","download_url":"https://codeload.github.com/emcrisostomo/Time-Machine-Cleanup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225980898,"owners_count":17554919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["time-machine"],"created_at":"2024-08-05T06:02:01.173Z","updated_at":"2025-07-14T13:33:25.904Z","avatar_url":"https://github.com/emcrisostomo.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"Time Machine Cleanup\n====================\n\n`tm-cleanup.sh` is a Zsh script to clean up Time Machine backups and reduce its\nsize.  `tm-cleanup.sh` provides two interfaces:\n\n  * A command-line interface.\n\n  * An interactive, dialog-based interface.\n\n`tm-cleanup.sh` requires super-user privileges, so it's normally executed using\n`sudo`.\n\nWhat's new in 2.1.0\n-------------------\n\n  * Updated to support APFS Time Machine targets and new `tmutil` syntax.\n\n  * Tested on macOS Sequoia 15.2.\n\ntm-cleanup.sh\n-------------\n\n`tm-cleanup.sh` is a Zsh script that lists the completed Time Machine snapshots\nand deletes those that satisfy the specified criteria.  Two types of deletion\ncriteria exist:\n\n  * By date: snapshots that are older than a specified number of days are\n    deleted.  The default threshold is 30 days.\n\n  * By number: a maximum number of snapshots is retained and oldest snapshots\n  are deleted.\n\nOnly one deletion criteria can be specified.\n\nThe syntax of `tm-cleanup.sh` is the following:\n\n    $ tm-cleanup.sh (-d days | -n number) [-f] [-x]\n    $ tm-cleanup.sh [-h]\n\nwhere\n\n  * If `-d` is specified, backups older than the specified number of days will\n    be deleted.  `days` is a positive integer number.\n\n  * `-n` specifies the number of backups to retain.  `number` is a positive\n    integer number.\n\n  * By default, `tm-cleanup.sh` exits and prints an error message if a Time\n    Machine backup is currently in progress.  `-f` forces the backup deletion\n    concurrently.\n\n  * `-h` prints the help message and exits the program.\n\n  * `-x` performs a dry clean: it will print the list of operations that will\n    be performed without actually performing any.\n\nThis script *never* deletes the latest snapshot, no matter the value of the `-d`\nor `-n` options.\n\nInteractive Interface\n---------------------\n\n`tm-cleanup.sh` also provides an interactive interface which is useful if the\nuser wishes to pick which backups to delete using a dialog-based interface.  The\ninteractive interface can be launched by passing no arguments to the script:\n\n    $ tm-cleanup.sh\n\nThe interactive interface starts with a menu showing the available operations a\nuser can perform:\n\n![tm-cleanup.sh - Start](https://raw.githubusercontent.com/emcrisostomo/Time-Machine-Cleanup/assets/images/tm-start.png)\n\nThe _Delete backups_ operation brings the user to a dialog where the backups to\ndelete can be selected.  By default, backups are shown in reverse chronological\norder (i.e.: latest first) and all except the first are selected.\n\n![tm-cleanup.sh - Choose backups](https://raw.githubusercontent.com/emcrisostomo/Time-Machine-Cleanup/assets/images/tm-delete.png)\n\nThe backups deletion may take a long time to complete, during which a progress\ndialog is shown.\n\n![tm-cleanup.sh - Backup deletion progress](https://raw.githubusercontent.com/emcrisostomo/Time-Machine-Cleanup/assets/images/tm-progress.png)\n\nAt the end of the deletion, a confirmation is shown to the user.\n\n![tm-cleanup.sh - Backup deletion done](https://raw.githubusercontent.com/emcrisostomo/Time-Machine-Cleanup/assets/images/tm-delete-done.png)\n\nThe script prevents users to delete all the backups.  If all the backups are\nselected, an error message is shown.\n\n![tm-cleanup.sh - Invalid backup choice](https://raw.githubusercontent.com/emcrisostomo/Time-Machine-Cleanup/assets/images/tm-delete-invalid-choice.png)\n\nInstallation\n------------\n\nThis package is configured using the GNU Autotools.  For this reason, users who\njust wish to use this software have to download a release tarball.  Release\ntarball are attached to each release.  The [latest] release of this package can\nalways be found using the [latest] tag.\n\n[latest]: https://github.com/emcrisostomo/Time-Machine-Cleanup/releases/latest\n\nOnce a release tarball has been downloaded and uncompressed, this package can be\ninstalled using the following commands:\n\n    $ ./configure\n    $ sudo make install\n\nPlease, refer to the Autotools documentation if you'd like to customise the\ninstallation procedure.\n\nThe package can then be uninstalled using the following command:\n\n    $ sudo make uninstall\n\nTo make path changes visibile in an existing Zsh session, execute the `rehash`\ncommand:\n\n    $ rehash\n\nRequirements\n------------\n\nSince a compatible version of Zsh is bundled with OS X, the command-line\ninterface of this script has no other requirements.  To use the dialog-based\ninterface, `dialog` is required.\n\nTesting locally\n---------------\n\nTo create an HFS+ disk image:\n\n    $ hdiutil create -size 100g \\\n        -fs HFS+J -type SPARSEBUNDLE \\\n        -volname \"TimeMachineBackup-HFSplus\" \\\n        ~/TimeMachineBackup-HFSplus\n\nTo create an APFS disk image:\n\n    $ hdiutil create -size 100g \\\n        -fs APFS -type SPARSEBUNDLE \\\n        -volname \"TimeMachineBackup-APFS\" \\\n        ~/TimeMachineBackup-APFS\n\nCheck whether the disk is mounted:\n\n    $ diskutil list\n\nIf it's not mounted, attach it to the system:\n\n    $ hdiutil attach ~/TimeMachineBackup-APFS\n\nVerify it's mounted:\n\n    $ ls /Volumes\n\nSet it as the destination of a Time Machine backup.  It might be necessary to\ngrant _Full Disk Access_ permissions to the terminal application used to launch\nthe following command, or use the _Preferences_ application.\n\n*Note:* make sure to use the `-a` flag in order not to clobber the current set\nof destinations.\n\n    $ sudo tmutil -a setdestination /Volumes/TimeMachineBackup-APFS\n\nVerify the configuration:\n\n    $ tmutil destinationinfo\n\nBug Reports\n-----------\n\nBug reports can be sent directly to the authors.\n\n-----\n\nCopyright (C) 2015-2025 Enrico M. Crisostomo\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 3, or (at your option)\nany later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License\nalong with this program.  If not, see \u003chttp://www.gnu.org/licenses/\u003e.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femcrisostomo%2FTime-Machine-Cleanup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femcrisostomo%2FTime-Machine-Cleanup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femcrisostomo%2FTime-Machine-Cleanup/lists"}