{"id":13581449,"url":"https://github.com/tg44/heptapod","last_synced_at":"2025-12-26T11:27:11.914Z","repository":{"id":43094392,"uuid":"415938690","full_name":"tg44/heptapod","owner":"tg44","description":"This is a command line application to manage and fine-tune Time Machine exclude paths.","archived":false,"fork":false,"pushed_at":"2024-10-21T10:50:23.000Z","size":60,"stargazers_count":68,"open_issues_count":2,"forks_count":9,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-05T21:44:37.541Z","etag":null,"topics":["backup","hacktoberfest","hacktoberfest2021","macos","time-machine"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tg44.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-10-11T13:28:57.000Z","updated_at":"2024-10-26T23:33:42.000Z","dependencies_parsed_at":"2023-12-27T17:30:55.915Z","dependency_job_id":"7e9a2f2f-d0a7-4222-93b9-d594b8fbf86f","html_url":"https://github.com/tg44/heptapod","commit_stats":{"total_commits":31,"total_committers":6,"mean_commits":5.166666666666667,"dds":"0.32258064516129037","last_synced_commit":"2b74263a1c339a7d24bab4274b65bd89b2655052"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg44%2Fheptapod","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg44%2Fheptapod/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg44%2Fheptapod/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tg44%2Fheptapod/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tg44","download_url":"https://codeload.github.com/tg44/heptapod/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470346,"owners_count":20944146,"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":["backup","hacktoberfest","hacktoberfest2021","macos","time-machine"],"created_at":"2024-08-01T15:02:02.080Z","updated_at":"2025-12-26T11:27:06.863Z","avatar_url":"https://github.com/tg44.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# heptapod\n\nThis is a command line application to manage and fine-tune\n[Time Machine](https://support.apple.com/en-us/HT201250) exclude paths.\n\n\u003cdetails\u003e\n  \u003csummary\u003eWhy it is named after creatures from Arrival?\u003c/summary\u003e\nHeptapods are extraterrestrial species from the movie Arrival.\nThey are special because they have non-linear time perspective.\nTheir written language (Heptapod B) is basically describes \nthe future and the past in the same time. Hence the name of the tool.\n\u003c/details\u003e\n\n### Install\n\n```sh\nbrew tap tg44/heptapod\n```\n```sh\nbrew install heptapod\n```\n\n### Usage\n\nTo print help;\n```\nheptapod -h\nheptapod \u003caction\u003e -h\n```\n\nMove (and use) the default ruleset;\n```\nmkdir -p ~/.heptapod/rules\ncp -R $(brew --prefix heptapod)/rules ~/.heptapod\n```\n\nLists all the rules (you get 4 tables, enabled, disabled, parseable but unrunable and unparsable).\n```\nheptapod rules ls -a\n```\n\nEnable/disable rules (by name), or add/remove ignore folders;\n```\nheptapod rules disable node bower\nheptapod rules enable bower\nheptapod rules ignoreAdd ~/.Trash ~/.yarn/cache ~/Library\nheptapod rules ignoreRemove ~/.Trash\n```\n\nList all the currently excluded TM paths;\n```\nheptapod tm ls\n```\n\nDryrun the current rules, in verbose mode, also log speed and debug informations. (Potentially list nonexistent directories and files!)\n```\nheptapod -v 1 run -d\n```\n\nTo run the current rules, and add the dirs to the TM exclude list. Also writes exclude logs to `~/.heptapod/logs` (or the given `--logDir dir`) for easier revert.\n```\nheptapod run\n```\n\nTo revert all the previously added paths from the run-exclude-logs. (`prune -h` could tell you the other useful revert options).\n```\nheptapod prune -a\n```\n\n### Dictionary\n - **path** - a file or a folder\n - **search path** - a path that we want to process\n - **ignore path** - path that we don't process (further)\n - **exclude path** - path that we don't want in our TM saves\n - **include path** - path that we want in our TM saves\n - **ignore rule** - a rule that parse git/docker ignore file format\n\n### Notes from TM migrating to a new machine\nWhen you try to migrate your TM state to a new machine\n`xcode-select --install` may be needed. Somehow this is \nsometimes not migrated as you thought it would be.\n\n### Notes from TM in general\nThere are two ways to exclude a dir from backups;\n- exclude by path (`tmutil addexclusion -p`)\n  - needs sudo\n  - can be read back with `defaults read /Library/Preferences/com.apple.TimeMachine.plist SkipPaths`\n  - appears in TM preferences / options\n- exclude by flag (`tmutil addexclusion`)\n  - keeps the given flag when moved\n  - can not be reliably list them (`mdfind com_apple_backup_excludeItem = 'com.apple.backupd'` is a close call, but some folders are excluded by mdfind too)\n\nThis tool excludes by flag! You can check any folder manually with `tmutil isexcluded`. **If you delete a folder, it will be deleted with its flag. You don't need to clean up ever.**\nAlso, you can only exclude nonexcluded files with tmutil, so we only add them if they are exists and if they are not already added.\n\n### Rules\nEvery rule has a searchPaths, ignorePaths.\n - `name` for categorization\n - `enabled` for easier enable/disable\n - `searchPaths` are the root of the rule search like `~`\n - `ignorePaths` are subpaths that we want to ignore to make the run quicker\n   - like we want to parse dirs under `~`, but not `~/Downloads`\n - `type` is the ruletype\n   - `file-trigger`\n   - `regexp`\n   - `ignore-file`\n   - `global`\n   - `list`\n - `settings` other type setting see below\n\n#### Ignore file (not yet implemented)\nParses the `.gitignore` or `.dockerignore` files, and excludes its contents.\n - `forceIncludePaths` are files that we add even if they would be otherwise excluded\n   - like `.gitignore` ignores `.env` files but we forcefully want to add them back \n - `fileName`\n   - `.gitignore` or `.dockerignore`\n - devdocs:\n   - the problem with this, that you need to go into the whole subtree to do the parsings\n\n#### Regexp (not yet implemented)\nIgnores all files/folders with the given regexp. This can be slow!\n - `regexp`\n\n#### File trigger\nIgnores files/dirs based on other files existence, made for easy language dep ignores.\n - `fileTrigger` like `package.json` or `.git`\n - `excludePaths` like `node-modules` or `.`\n\n#### Global\nGlobally ignores or excludes path (overrides other rules walk ignores).\n - `path` the global path we want to evaluate (like `~/.npm`)\n - `handleWith` a string enum\n    - `ignore` - ignores globally\n    - `exclude` - ignores globally and excludes from backups\n    - any other value - do nothing\n\n#### List\nCan group multiple rules to a single file.\n - `subRules` the array of subRules (can be recursive with another `list`)\n\nNotes;\n - while `rules ls` works, `enable`, `disable` and the path commands not working for the subrules, you need to edit the file manually\n - if the list is disabled, all of it subs are handled as disables\n - the group `searchPaths` and `ignorePaths` are currently do nothing\n   - probably this will change for easier customisations \n\n### Credits\n - [asimov](https://github.com/stevegrunwell/asimov)\n - [tmignore](https://github.com/samuelmeuli/tmignore)\n - [various stack exchange responses](https://superuser.com/questions/1161038/exclude-folders-by-regex-from-time-machine-backup)\n - [tmutil](https://ss64.com/osx/tmutil.html)\n\n### Contribution\nIf you are interested in this repo, star it, and write an issue, and we can talk about future ideas there!\n\n\n### Repo/developement state\ndone:\n- architecture the protocol/configs\n- most of asimov's features are ported\n- example rules added\n- command line interface\n- option to dryrun, show inner states, write to file\n- purge option\n   - we should write down what paths excluded by us, and include them back\n- brew package\n- ghactions\n- rule manage commands (list/enable/disable/ignoreAdd/ignoreRemove)\n- global rule type\n- list rule type (for better rule grouping)\n\ntodos:\n- reorganise rules\n- fix the rule manage commands for lists\n- support tmignore functionality\n- support tmignore like funcionality with dockerignore\n- regexp pattern\n- hook to rerun periodically/before tmbackups\n- port asimov's issues (spotify, spotlight)\n- docker support (at least tell if docker vm is persisted or not)\n   - this is kinda easy with tmutil.GetExcludeList()\n- android vms?\n   - this should be also easy\n- preemptive search that tells you how many files with which size will be excluded/included\n   - nice to have, we can tell the sizes, but counting files need to actually count the files which could be slow AH\n- speedtest it\n- modify the backup intervals and frequencies\n   - not sure it can be done with tmutil, but there are applications for this\n- probably adding `.` and `..` will break the execution shortcuts and need to fix them\n- wildcards like `*.sh` not working right now, do we want to make them work?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg44%2Fheptapod","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftg44%2Fheptapod","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftg44%2Fheptapod/lists"}