git-backup

README

git-backup

Git 平台多仓库镜像备份与工作区同步工具，支持 GitHub、Gitee、Gitea。

功能

• 多平台支持 — GitHub、Gitee、Gitea（含自托管实例），单配置可同时配置多个平台
• 自动发现仓库 — 根据 Token 自动拉取账户下所有可见仓库（个人 + 组织），无需逐个配置
• 镜像备份 (mirror) — git clone --mirror 完整备份（所有分支与标签），增量更新时 git remote update --prune；同时保存 Release 列表为 JSON
• 工作区同步 (work) — git clone --depth 1 仅同步默认分支最新提交，无 Release 信息；后续 fetch + reset 增量更新
• 测试模式 (test) — 仅列出仓库名与 Release 数量，不实际克隆
• 清理模式 (clean) — 比对本地与云端仓库，交互式删除不再存在于云端的本地仓库
• 代理支持 — 每个平台独立配置 HTTP/HTTPS/SOCKS5 代理
• 优雅退出 — Ctrl+C 后完成当前仓库后退出，不跳过清理

安装

前置要求

• Go 1.26+
• 系统已安装 git 命令行工具

安装

go install gitee.com/xzsmtech/git-backup@latest

可执行文件位于 $GOPATH/bin（或 $GOBIN），确保该目录在 PATH 中。

配置

配置文件路径：~/.git-backup.toml（Windows 下为 %USERPROFILE%\.git-backup.toml）。

配置示例

mirror_folder = "/path/to/backups"
work_folder   = "/path/to/workspace"     # 可选，仅 work 模式需要
concurrency   = 3                        # 可选，每平台仓库并发数，默认 3，范围 1-32

[[platforms]]
type  = "github"
token = "ghp_xxxxxxxxxxxx"

[[platforms]]
type  = "gitee"
token = "xxxxxxxxxxxxxx"

[[platforms]]
type     = "gitea"
url      = "https://gitea.example.com"
token    = "xxxxxxxxxxxxxx"
username = "myuser"                  # 可选，Gitea 鉴权用 username:token
proxy    = "http://127.0.0.1:7890"   # 可选

[[platforms]]
type  = "github(proxy)"
name  = "work-account"               # 可选，平台显示名称（默认 type）
token = "ghp_yyyyyyyyyyyyyy"
proxy = "socks5://127.0.0.1:1080"

字段说明

字段	说明
mirror_folder	镜像备份根目录，相对路径基于用户目录解析（mirror 命令必填，test/clean 可选）
work_folder	工作区同步根目录（可选）
concurrency	每平台仓库并发数（可选，默认 3，范围 1-32，设为 1 即串行）
platforms	平台配置列表
platforms[].name	平台显示名称（可选，默认 type）
platforms[].type	平台类型：github / gitee / gitea
platforms[].token	平台访问令牌
platforms[].url	Gitea 实例基础 URL（仅 gitea 必填）
platforms[].username	可选，仅 Gitea；设置后 git 鉴权用 username:token
platforms[].proxy	可选代理 URL，支持 http://、https://、socks5://

程序启动后会调用平台 API 自动拉取当前账户下所有可见仓库（个人 + 组织），按 平台类型/owner/repo 结构存放。

Token 获取

平台	地址	权限
GitHub	Personal Access Token	repo
Gitee	私人令牌	projects
Gitea	设置 → 应用 → 管理 Access Token	读取仓库

使用

# 镜像备份（完整克隆 + Release 信息）
git-backup mirror

# 工作区同步（仅默认分支最新提交）
git-backup work

# 测试模式（仅列出仓库 + Release 数量）
git-backup test

# 清理模式（比对本地与云端，交互式删除）
git-backup clean

程序按配置顺序依次处理每个平台：拉取仓库列表 → 逐个备份/同步。单个仓库失败不影响其他仓库，全部完成后若有失败则退出码为 1。

备份目录结构

mirror 模式

{mirror_folder}/
└── {platform_type}/
    ├── {owner}/
    │   ├── {repo}/              # git 镜像仓库（git clone --mirror）
    │   │   ├── HEAD
    │   │   ├── config
    │   │   ├── objects/
    │   │   └── refs/
    │   ├── {repo}-release.json  # Release 信息（JSON 格式化）
    │   └── {another-repo}/
    └── {org}/
        └── {repo}/

work 模式

{work_folder}/
└── {platform_type}/
    └── {owner}/
        └── {repo}/              # 默认分支工作区（git clone --depth 1）
            ├── .git/
            ├── README.md
            └── ...

工程结构

git-backup/
├── main.go                     # 入口：加载配置 → 遍历平台 → 派发子命令
└── internal/
    ├── config/config.go         # 配置结构体与 TOML 加载校验
    ├── platform/
    │   ├── platform.go          # Platform 接口 + RepoInfo + 工厂函数
    │   ├── github.go            # GitHub 实现
    │   ├── gitee.go             # Gitee 实现
    │   └── gitea.go            # Gitea 实现（自托管实例）
    ├── git/git.go               # git 命令封装（mirror clone/update、work clone/update）
    └── backup/backup.go          # 备份编排（MirrorRepo / WorkRepo / TestRepo）

License

Apache 2.0