{"id":31853544,"url":"https://github.com/programie/borghelper","last_synced_at":"2025-10-12T13:29:58.764Z","repository":{"id":220510089,"uuid":"751827050","full_name":"Programie/BorgHelper","owner":"Programie","description":"Helper script to manage multiple repositories for BorgBackup","archived":false,"fork":false,"pushed_at":"2025-06-06T14:49:33.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-25T09:36:06.905Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/Programie.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}},"created_at":"2024-02-02T12:16:06.000Z","updated_at":"2025-06-06T14:49:34.000Z","dependencies_parsed_at":"2024-02-08T12:00:18.666Z","dependency_job_id":null,"html_url":"https://github.com/Programie/BorgHelper","commit_stats":null,"previous_names":["programie/borghelper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Programie/BorgHelper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programie%2FBorgHelper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programie%2FBorgHelper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programie%2FBorgHelper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programie%2FBorgHelper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Programie","download_url":"https://codeload.github.com/Programie/BorgHelper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Programie%2FBorgHelper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011444,"owners_count":26084947,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-10-12T13:29:57.669Z","updated_at":"2025-10-12T13:29:58.757Z","avatar_url":"https://github.com/Programie.png","language":"Python","readme":"# Borg Helper\n\nBorg Helper is a script which allows you to define a list of repositories for [BorgBackup](https://www.borgbackup.org) and execute borg commands on those repositories.\n\nThe script looks for configs at the following locations (merged in that order):\n\n* `borg-helper.json` in the directory containing the `borg-helper.py`\n* `/etc/borg-helper.json`\n* `~/.config/borg-helper.json`\n* `borg-helper.json` in the current directory\n\nAdditional paths can be specified using the `BORG_HELPER_CONFIGS` environment variable (separated by `:` just like the `PATH` environment variable).\n\nThe configuration is in JSON and expects at least a `repositories` property containing a map with all of your repositories. Each entry consists of a key (the repository name) and the configuration for this repository.\n\nThe repository configuration should have at least a `repository` property specifying the location of that repository. But you might also specify `passphrase` to define the passphrase of that repository as well as `ssh_key` to define the location of your SSH key if using SSH for the repository.\n\nIf your borg binary is not in the default search paths, you might specify the path to it using the `borg_binary` property.\n\n## Requirements\n\n* Python 3.10+\n* [BorgBackup](https://www.borgbackup.org) (tested with version 1.2 but any version of it should work)\n\n## Installation\n\nSimply download the [borg-helper.py](borg-helper.py) from this repository, store it somewhere and make it executable.\n\n## Aliases\n\nBorg Helper also allows you to define a list of aliases as known from your command line shell or git.\n\nThere are global and repository specific aliases. Each alias has a name which will be selected based on the first argument specified after the repository name.\n\nRepository specific aliases are resolved first. After that, the global aliases will be resolved and may also extend an alias which was already resolved by the repository specific aliases.\n\nAliases can be specified using the `aliases` property inside the repository configuration or at the root level (next to the `repositories` property). Each alias must contain the arguments which should be used instead of that alias.\n\nFor example, you might define an alias `create` which will resolve to `create --progress --stats --verbose`. Passing `create /path/to/source` will then resolve to `create --progress --stats --verbose /path/to/source`.\n\nIt is possible to use shell syntax like `$()` in aliases (as done with `$(date +%Y-%m-%d_%H:%M)` in the example configuration bellow). The full borg command is passed to your shell.\n\n## Additional commands\n\nBorg Helper has some additional commands which wrap around Borg.\n\n### list-archives\n\nThe `list-archives` command can be used to search for specific paths or pattern in all archives of a specific repository.\n\nThe usage of the command is quite simple: `borg-helper.py my-repository list-archives`\n\nThe command will list all files in all archives of the specified repository. You might specify any arguments also available in `borg list`, like the path to see which archives contain a specific path.\n\nExample: `borg-helper.py my-repository list-archives some/path/inside/the/backup`\n\n### list-removed-items\n\nThe `list-removed-items` command can be used to list all files and directories which have been removed in the last backup compared to the previous one.\n\nThis can be useful to detect accidental removed files while creating a backup.\n\nFor that, simply create a new backup which might removes some files and execute the `list-removed-items` command afterwards to see which files were removed. In case there are some files which were removed accidentally, you can restore them from the previous backup (i.e. by mounting the previous backup an copying the files).\n\nAvailable options:\n\n* `--fail`: Return with exit code 1 in case removed files or directories are found\n* `--color`: Use color to highlight removed items\n\nAdditionally to that, a path within the backup can be specified to limit the diff to that specific path. This also supports borg patterns (see the documentation for the path argument in `borg diff`).\n\n## Example configuration\n\n```json\n{\n  \"borg_binary\": \"/path/to/borg\",\n  \"aliases\": {\n    \"create\": \"create --progress --stats --verbose\",\n    \"prune\": \"prune --list --stats --verbose\"\n  },\n  \"repositories\": {\n    \"my-repository\": {\n      \"repository\": \"/path/to/your/repository\",\n      \"aliases\": {\n        \"create\": \"create ::$(date +%Y-%m-%d_%H:%M)\"\n      }\n    },\n    \"another-repository\": {\n      \"repository\": \"ssh://user@example.com/path/to/repository\",\n      \"passphrase\": \"YourBorgPassphrase\"\n    }\n  }\n}\n```\n\n## Usage\n\nTo list your configured repositories, execute `borg-helper.py list`.\n\nThe example from above will show the following output:\n```\nAvailable repositories:\n  another-repository (ssh://user@example.com/path/to/repository)\n  my-repository (/path/to/your/repository)\n```\n\nTo execute borg on a specific repository, execute `borg-helper.py \u003crepository\u003e \u003carguments\u003e`.\n\nBy using the example configuration from above, you might execute the following commands:\n\n```\nborg-helper.py my-repository info\n```\n\nThis command will execute `borg info` on the repository `my-repository` located at `/path/to/your/repository`. It is basically the same as executing `borg info /path/to/your/repository`.\n\n```\nborg-helper.py another-repository create ::my-backup /path/to/your/source\n```\n\nThis command will execute `borg create --progress --stats --verbose ::my-backup /path/to/your/source` as the global alias `create` matches the first argument next to the repository name.\n\n```\nborg-helper.py my-repository create /path/to/some/source\n```\n\nThis command will execute `borg create --progress --stats --verbose ::$(date +%Y-%m-%d_%H:%M) /path/to/some/source` as the repository specific alias `create` matches the first argument next to the repository name.\n\nAfter resolving the repository specific alias, the arguments resolve to `create ::$(date +%Y-%m-%d_%H:%M) /path/to/some/source` in which case the global alias `create` matches the first argument resulting in also using the global alias.\n\nThis results in the arguments finally being resolved to `create --progress --stats --verbose ::$(date +%Y-%m-%d_%H:%M) /path/to/some/source` and passed to borg.\n\nIf you are unsure whether the fully resolved command is the correct one, you might add `-i` before the repository name to interactively ask whether to execute that command. This is especially useful if you want to execute a destructive command like `prune`.\n\n## Troubleshooting\n\nIn case something does not work as expected (for example, the script does not know your configured repository), you might like to enable debug logging by adding `-d` before the repository argument:\n\n```\nborg-helper.py -d my-repository info\n```\n\nAdding this option will log more details like where Borg Helper looks for configuration files or which repositories are loaded.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramie%2Fborghelper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogramie%2Fborghelper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogramie%2Fborghelper/lists"}