{"id":21482444,"url":"https://github.com/jonhadfield/githosts-utils","last_synced_at":"2025-09-19T23:09:41.473Z","repository":{"id":57494408,"uuid":"146198763","full_name":"jonhadfield/githosts-utils","owner":"jonhadfield","description":"a library for querying and backing up github, gitlab, gitea, and bitbucket repositories","archived":false,"fork":false,"pushed_at":"2024-10-28T11:35:42.000Z","size":278,"stargazers_count":3,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-10-28T14:55:40.949Z","etag":null,"topics":["bitbucket","git","gitlab","go","golang-library"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonhadfield.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-08-26T16:49:07.000Z","updated_at":"2024-10-28T11:35:45.000Z","dependencies_parsed_at":"2024-02-27T22:46:15.997Z","dependency_job_id":"79f82956-07fe-4f12-90f6-b05e6264cc46","html_url":"https://github.com/jonhadfield/githosts-utils","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonhadfield%2Fgithosts-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonhadfield%2Fgithosts-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonhadfield%2Fgithosts-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonhadfield%2Fgithosts-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonhadfield","download_url":"https://codeload.github.com/jonhadfield/githosts-utils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226044892,"owners_count":17564915,"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":["bitbucket","git","gitlab","go","golang-library"],"created_at":"2024-11-23T12:33:23.103Z","updated_at":"2025-09-19T23:09:36.449Z","avatar_url":"https://github.com/jonhadfield.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# githosts-utils\n\n`githosts-utils` is a Go library for backing up repositories from major hosting providers. It powers [soba](https://github.com/jonhadfield/soba) and can be embedded in your own tools.\n\n## Features\n\n- Minimal dependencies and portable code\n- Supports GitHub, GitLab, Bitbucket, Azure DevOps, and Gitea\n- Clones repositories using `git --mirror` and stores timestamped bundle files\n- Optional reference comparison to skip cloning when refs have not changed\n- Ability to keep a configurable number of previous bundles\n- Optional Git LFS archival alongside each bundle\n- Pluggable HTTP client and simple logging via the `GITHOSTS_LOG` environment variable\n\n## Installation\n\n```bash\ngo get github.com/jonhadfield/githosts-utils\n```\n\nRequires Go 1.22 or later.\n\n## Quick Start\n\nCreate a host for the provider you want to back up and call `Backup()` on it. Each provider has its own input struct with the required options. The example below backs up a set of GitHub repositories:\n\n```go\npackage main\n\nimport (\n    \"log\"\n    \"os\"\n\n    \"github.com/jonhadfield/githosts-utils\"\n)\n\nfunc main() {\n    backupDir := \"/path/to/backups\"\n\n    host, err := githosts.NewGitHubHost(githosts.NewGitHubHostInput{\n        Caller:    \"example\",\n        BackupDir: backupDir,\n        Token:     os.Getenv(\"GITHUB_TOKEN\"),\n        BackupLFS: true,\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    results := host.Backup()\n    for _, r := range results.BackupResults {\n        log.Printf(\"%s: %s\", r.Repo, r.Status)\n    }\n}\n```\n\n`Backup()` returns a `ProviderBackupResult` containing the status of each repository. Bundles are written beneath `\u003cbackupDir\u003e/\u003cprovider\u003e/\u003cowner\u003e/\u003crepo\u003e/`.\n\n### Diff Remote Method\n\nEach host accepts a `DiffRemoteMethod` value of either `\"clone\"` or `\"refs\"`:\n\n- `clone` (default) – always clone and create a new bundle\n- `refs` – fetch remote references first and skip cloning when the refs match the latest bundle\n\n### Retaining Bundles\n\nSet `BackupsToRetain` to keep only the most recent _n_ bundle files per repository. Older bundles are automatically deleted after a successful backup.\n\n## Environment Variables\n\nThe library reads the following variables where relevant:\n\n- `GITHOSTS_LOG` – set to `debug` to emit verbose logs\n- `GIT_BACKUP_DIR` – used by the tests to determine the backup location\n\nProvider-specific tests require credentials through environment variables such as `GITHUB_TOKEN`, `GITLAB_TOKEN`, `BITBUCKET_KEY`, `BITBUCKET_SECRET`, `AZURE_DEVOPS_USERNAME`, `AZURE_DEVOPS_PAT`, and `GITEA_TOKEN`.\n\n## Running Tests\n\n```bash\nexport GIT_BACKUP_DIR=$(mktemp -d)\ngo test ./...\n```\n\nIntegration tests are skipped unless the corresponding provider credentials are present.\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonhadfield%2Fgithosts-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonhadfield%2Fgithosts-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonhadfield%2Fgithosts-utils/lists"}