mgit - 多仓库批量克隆工具

一个命令行工具，用于从 GitLab Group 批量克隆多个仓库。支持通过 TAPD ID 自动获取需求关联的服务分支，并支持批量切换分支。

安装

方式一：从 .tgz 文件安装

npm install -g mgit-1.0.2.tgz

方式二：从源码安装

cd mgit
npm install
npm link

快速开始

1. 初始化配置

首次使用需要配置 GitLab 连接信息：

mgit init

按提示输入：

• GitLab 域名：如 gitlab.zhuanspirit.com
• Personal Access Token：在 GitLab 设置中生成，需要 read_api 权限
• Groups：自动列出可访问的 Group，多选关联
• Clone 协议：HTTP 或 SSH

配置保存在 ~/.mgit/config.json。

2. 基本使用

查看所有项目

mgit list

交互式选择并克隆

mgit clone

显示项目列表，多选后克隆到指定目录。

克隆全部项目

mgit clone --all --target ./my-workspace

3. 通过 TAPD ID 克隆（推荐）

根据需求 ID 自动获取关联的服务分支：

# 交互式输入 TAPD ID
mgit tapd

# 直接指定 TAPD ID
mgit tapd 1120570781001787717

# 指定目标目录
mgit tapd 1120570781001787717 --target ./feature-123

功能特点：

• 自动从 Beetle 获取需求关联的所有分支
• 过滤已关闭的分支
• 按服务分组，多分支时交互选择
• 显示分支状态（开发中/已上线）
• 一键批量克隆

4. 批量切换分支（新功能）

已 clone 的服务目录，切换需求时无需重新 clone，直接切换分支：

# 交互式输入 TAPD ID
mgit switch

# 直接指定 TAPD ID
mgit switch 1120570781001787717

# 指定工作目录
mgit switch 1120570781001787717 --dir ./my-workspace

功能特点：

• 扫描当前目录下的 git 仓库
• 自动匹配 TAPD 关联的服务
• 检测未提交修改，有则报错终止
• 本地分支不存在时自动从远程创建
• 缺失的服务提示是否 clone

输出示例：

✔ 获取到 5 个分支
ℹ 扫描到 8 个本地仓库

将切换以下分支：
  ass_core_logic: master → ass_core_logic-feature-4616-430 (开发中)
  kfassrepairlogic: master → kfassrepairlogic-feature-2087-675 (开发中)
  ass_offline: master → ass_offline-feature-6113-18 (已上线)

⚠ 以下服务本地不存在: skill_respo

? 确认切换分支？ Yes

[1/3] ✔ ass_core_logic → ass_core_logic-feature-4616-430
[2/3] ✔ kfassrepairlogic → kfassrepairlogic-feature-2087-675
[3/3] ✔ ass_offline → ass_offline-feature-6113-18

切换完成:
  成功: 3  失败: 0

? 是否 clone 缺失的 1 个服务？ No

命令参考

mgit init              配置 GitLab 连接（域名、Token、Groups）
mgit clone             交互式选择并批量克隆仓库
mgit clone --all       克隆全部项目
mgit tapd [id]         通过 TAPD ID 克隆关联仓库
mgit switch [id]       通过 TAPD ID 批量切换分支（已 clone 的仓库）
mgit list              列出所有关联 Group 的项目
mgit config            查看当前配置
mgit config reset      重置配置

使用示例

场景：新需求开发

# 1. 首次 clone
mgit tapd 1120570781001787717 --target ./feature-123

# 2. 进入工作目录开始开发
cd ./feature-123

场景：切换需求（服务目录已存在）

# 直接切换分支，无需重新 clone
cd ./my-workspace
mgit switch 1120570781001787717

场景：批量拉取所有服务

# 克隆所有关联 Group 的项目到指定目录
mgit clone --all --target ./all-services

配置文件

配置保存在 ~/.mgit/config.json：

{
  "gitlabUrl": "gitlab.zhuanspirit.com",
  "token": "your-personal-access-token",
  "groups": [
    { "id": "277", "name": "zz-kf", "fullPath": "zz-kf" },
    { "id": "302", "name": "zz-order", "fullPath": "zz-order" }
  ],
  "protocol": "http"
}

常见问题

Token 权限不足

确保 Token 有 read_api 和 read_repository 权限。

切换分支时提示有未提交修改

先处理未提交的修改：

# 方式1：提交修改
git add .
git commit -m "xxx"

# 方式2：暂存修改
git stash

然后重新执行 mgit switch。

如何更新配置？

mgit config reset
mgit init

克隆失败怎么办？

1. 检查网络连接（是否需要 VPN）
2. 确认 Token 未过期
3. 确认 Group ID 正确
4. 检查目标目录是否有写入权限

依赖

• Node.js >= 18
• Git

License

MIT