gitporter 1.0.1

GitPorter 是一个 Git 代码仓批量迁移工具

GitPorter

Git 代码仓批量迁移 & 持续同步工具

---

GitPorter 是一个 Git 代码仓批量迁移工具，支持在 GitHub、Gitee、GitLab、Gitea、Coding、Gogs、腾讯工蜂等平台之间迁移或持续同步仓库。首次运行全量克隆，后续自动增量同步，无需手动区分。

支持的平台

平台	迁移源	迁移目标
GitHub	✅	✅
Gitee	✅	✅
GitLab	✅	✅
Gitea	✅	✅
Gogs	✅	✅
腾讯工蜂	✅	✅
Coding	✅	❌
云效 Codeup	❌	❌
Bitbucket	❌	❌

迁移内容包括 commits、branches、tags，不包括 issues、PR、wiki。

安装

方式一：pip 安装

pip install gitporter

方式二：源码安装

git clone https://github.com/Adsryen/GitPorter.git
cd GitPorter
pip install -r requirements.txt
pip install -e .

方式三：uv 安装（推荐）

git clone https://github.com/Adsryen/GitPorter.git
cd GitPorter
uv sync

方式四：Docker

无需安装 Python 环境，只需挂载配置文件即可运行。

快速开始：

# 构建镜像
docker build -t gitporter -f deploy/docker/Dockerfile .

# 执行同步（挂载配置文件和缓存目录）
docker run --rm \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  -v $(pwd)/.gitporter:/app/.gitporter \
  gitporter sync -y

使用 Docker Compose（推荐）：

cd deploy/docker
# 将 config.yml.example 复制为配置文件并填入你的 token
cp config.yml.example ../../config.yml
# 执行同步
docker compose run --rm gitporter

常用命令变体：

# 列出源端仓库
docker run --rm -v $(pwd)/config.yml:/app/config.yml:ro gitporter list

# 预演模式
docker run --rm -v $(pwd)/config.yml:/app/config.yml:ro gitporter sync --dry-run

# 强制全量重新克隆
docker run --rm \
  -v $(pwd)/config.yml:/app/config.yml:ro \
  -v $(pwd)/.gitporter:/app/.gitporter \
  gitporter sync --force-reclone -y

定时同步（配合 crontab）：

0 2 * * * docker compose -f /path/to/deploy/docker/docker-compose.yml run --rm gitporter

快速开始

1. 生成配置文件

gitporter config

按照交互向导填写源平台和目标平台的认证信息，自动生成 config.yml。

也可以直接复制 config.yml 手动编辑。

2. 查看配置（可选，token 自动脱敏）

gitporter config --show

3. 预览将要同步的仓库

gitporter list
gitporter list --filter "my-*"       # 只看 my- 开头的仓库
gitporter list --exclude "archived-*" # 排除 archived- 开头的仓库

4. 预演一遍，不实际执行

gitporter sync --dry-run

5. 执行同步

gitporter sync           # 交互确认后执行
gitporter sync -y        # 跳过确认直接执行（适合脚本/CI）

首次运行全量克隆，后续自动切换为增量 fetch，无需手动区分。

配置文件说明

migrate:
  from: github        # 迁移源（对应下方的 provider 配置 key）
  to: gitee           # 迁移目标
  clone_dir: ""       # 本地缓存目录，默认 .gitporter/

  # 只迁移指定仓库（白名单）
  # repos:
  #   - my-repo-a
  #   - my-repo-b

  # 排除指定仓库（黑名单，支持通配符）
  # exclude_repos:
  #   - test_*          # 排除所有 test_ 开头的仓库
  #   - *_backup        # 排除所有 _backup 结尾的仓库
  #   - archived-*

  # 自定义 git clone / push 参数
  # clone_args:
  #   - "--depth"
  #   - "1"
  # push_args:
  #   - "--force"

github:
  provider: github
  base_api: https://api.github.com/graphql
  https_prefix: https://github.com
  username: "your-username"
  token: "ghp_xxxxxxxxxxxx"
  use_https: true

gitee:
  provider: gitee
  base_api: https://gitee.com/api/v5
  ssh_prefix: [e-mail]
  https_prefix: https://gitee.com
  username: "your-username"
  token: "your-token"

命令参考

gitporter config                    生成/查看配置文件
gitporter config --show             查看当前配置（token 脱敏显示）
gitporter config -o /path/to/cfg    指定输出路径

gitporter list                      列出源端所有仓库
gitporter list --filter "pattern"   只显示匹配的仓库
gitporter list --exclude "pattern"  排除匹配的仓库

gitporter sync                      执行同步（自动判断全量/增量）
gitporter sync --dry-run            预演，不实际执行
gitporter sync -y                   跳过确认
gitporter sync --force-reclone      强制全量重新克隆（忽略本地缓存）

所有命令均支持 -c 指定配置文件路径：
gitporter sync -c /path/to/config.yml

注意事项

• 迁移前请确认已在目标 Git 服务器上添加 SSH Key（使用 SSH 模式时）
• 只能迁移指定用户自己的仓库，不包括参与的或组织的仓库
• Coding 暂不支持通过 API 创建仓库，只能作为迁移源

扩展更多平台

继承 Git 基类并实现以下三个方法即可接入新平台：

from gitporter.git.base import Git

class MyGit(Git):
    def list_repos(self) -> list:
        # 返回 [{"name": "repo", "desc": "", "is_private": True}, ...]
        ...

    def create_repo(self, name: str, desc: str, is_private: bool) -> bool:
        ...

    def is_repo_existed(self, repo_name: str) -> bool:
        ...

相较原项目的改进

本项目 Fork 自 k8scat/Gigrator，在原项目基础上做了以下优化：

• 增量同步：本地缓存已存在时自动切换为 git fetch，首次全量、后续增量，无需手动区分
• 子命令架构：新增 config、list、sync 子命令，降低使用门槛
• 交互式配置：gitporter config 引导式生成配置文件，无需手写 YAML
• dry-run 预演：执行前可预览将要同步的仓库列表，安全可控
• 进度条：同步过程实时显示进度、当前仓库、耗时
• 仓库过滤：exclude_repos 支持通配符批量排除仓库
• 参数可配置：clone_args、push_args 支持自定义 git 参数
• 错误信息优化：失败时输出具体原因，单个失败不影响整体
• 项目结构重构：模块解耦，便于维护和扩展

致谢

感谢 k8scat 开发并开源了原项目 Gigrator，本项目在其基础上持续迭代。

贡献者

开源协议

MIT