🔄 repo-cli - 批量本地与远程 Git 仓库管理工具箱

repo-cli 是一个基于 Typer + Rich 重新优化与设计的规范命令行工具。它支持本地 Git 仓库批量维护（递归初始化、清除远程关联），以及 Gitee 等平台远程仓库的自动备份同步、批量跨空间镜像迁移与物理高危删除。

---

✨ 功能特点

• 📂 顶级本地维护工具：
  • 批量初始化 (init)：递归扫描指定目录，对非 Git 仓库的目录一键执行 git init（自动避开已有 Git 仓库的父目录及子孙目录，支持指定排除项）。
  • 远程配置维护 (remote rm)：批量清理本地一组 Git 仓库中的托管平台关联。
• 🚀 Gitee 平台工具组 (gitee)：
  • 批量同步 (sync)：一键将本地多仓库同步至 Gitee，若远程仓库不存在将自动请求 API 进行创建并关联。
  • 跨空间迁移 (migrate)：镜像克隆源空间的所有仓库并镜像推送至目标空间，完整保留分支、Tags 和 Commit 提交历史，支持 个人 ⇄ 组织 双向混合迁移。
  • 高危物理删除 (delete)：安全锁机制保护下的批量仓库物理删除（支持包含/排除过滤，需二次手动核对空间名防呆）。
• 🔒 极致安全设计：
  • 命令行彻底剔除 -t/--token 等明文敏感参数，防止令牌在 shell 历史及系统进程列表 (ps) 中泄密。
  • 采用交互式隐藏输入或 --env-file 环境文件绑定方式加载凭证。
• ⚙️ 灵活的参数优先级覆盖：
  • 所有子命令配置项均可通过 CLI 选项实时覆盖。参数优先级完全遵循：CLI 命令行参数 > YAML 配置文件 > 系统/Env 环境变量 > 内置默认值。
• 🧪 原生空运行支持 (--dry-run)：
  • 所有修改或写操作命令均支持 --dry-run 模式。空运行下将打印完整步骤并对敏感凭证 URL 自动进行掩码脱敏处理 (******)。

---

🚀 快速开始

1. 安装项目

确保本地已安装 uv 包装管理器：

# 克隆仓库
git clone <your-repo-url>/repo-cli.git
cd repo-cli

# 创建虚拟环境
uv venv
source .venv/bin/activate

# 可编辑模式安装
uv pip install -e .

2. 配置环境变量与参数

复制 .env.example 模版并配置您的私密令牌：

cp .env.example .env

在 .env 中填入凭证信息（仅建议存放敏感机密，如个人令牌）：

GITEE_ACCESS_TOKEN=gitee_pat_xxxxxx

在 config.yaml 中配置各子命令的默认行为（非机密信息建议存放于此）：

# 备份同步默认参数 (gitee sync)
sync:
  username: "your_username"
  organization: "" # 留空默认同步到个人空间，有值则优先同步到组织
  auto_create_repo: true
  repo_description: "由 repo-cli 自动同步备份的仓库"
  name_suffix: ""
  commit_message: "backup: 自动备份代码"
  local_remote_name: "origin"
  private: true

# 镜像迁移默认参数 (gitee migrate)
migrate:
  source: "source_org_path"
  source_type: "org" # org (组织) 或 user (用户)
  target: "target_org_path"
  target_type: "org"
  skip_existing: true

# 物理删除默认参数 (gitee delete)
delete:
  owner: "target_owner_path"
  owner_type: "org"
  force: false

# 本地扫描初始化配置 (init)
init:
  max_depth: 2
  exclude:
    - ".venv"
    - "node_modules"
    - "__pycache__"

---

📖 命令详解

1. 本地维护命令 (顶级命令)

📂 repo-cli init - 批量初始化 Git 仓库

递归扫描目标目录的子目录，对非 Git 仓库执行 git init：

repo-cli init [OPTIONS] [DIRECTORY]

• [DIRECTORY]：要扫描的目标目录（不填默认当前工作目录）。
• -c, --config PATH：指定使用的配置文件以读取排除目录（默认：config.yaml）。
• -e, --exclude TEXT：手动添加排除的目录名称（支持传入多个）。
• --no-default-exclude：不使用内置的默认排除目录（如 .venv, node_modules 等）。
• --show-default-exclude：打印内置默认排除列表。
• -d, --max-depth INTEGER：最大递归深度（0=当前目录自身，1=直接子目录，2=二级子目录，以此类推）[默认：2]。
• --dry-run：空运行模式，仅展示将要执行初始化的目录。

🧹 repo-cli remote rm - 批量清理远程关联

批量移除一组本地仓库中的托管平台远程关联配置：

repo-cli remote rm [OPTIONS] [DIRECTORIES]...

• -f, --from-file PATH：从文本文件读取目录路径列表（每行一个绝对路径）。
• --dry-run：空运行模式，仅展示将要清理的本地仓库目录。

---

2. Gitee 平台工具组 (gitee)

🔄 repo-cli gitee sync - 批量同步备份至 Gitee

一键同步本地多个代码仓至 Gitee，自带完整工作流判定（自动建库、添加 Remote 关联、自动 Commit、自动 Push）。

repo-cli gitee sync [OPTIONS] [DIRECTORIES]...

• --config -c PATH：项目配置文件路径（默认：config.yaml）。
• --env-file PATH：环境变量 .env 路径（默认：.env）。
• --dry-run：空运行模式。
• --username TEXT：指定用户名（注：若指定了 organization，将优先在组织空间下同步）。
• --organization TEXT：指定组织名（注：组织名优先级高于用户名，指定后将同步到组织空间而非个人空间）。
• --auto-create-repo/--no-auto-create-repo：远程仓库不存在时是否自动创建。
• --repo-description TEXT：自动建库时的描述信息。
• --name-suffix TEXT：同步到远程时为仓库名附加的后缀。
• --commit-message TEXT：自动提交未保存变更时的 Commit 备注。
• --local-remote-name TEXT：关联的远程 Remote 名称（默认 origin）。
• --private/--public：自动建库时的私有/公开属性。

🚚 repo-cli gitee migrate - 批量跨空间镜像迁移

批量克隆源空间名下的所有代码仓库，并完整镜像推送（Mirror Push）至目标空间，保留所有提交分支、Tags 和历史。

repo-cli gitee migrate [OPTIONS]

• --config -c PATH：项目配置文件路径（默认：config.yaml）。
• --env-file PATH：环境变量 .env 路径（默认：.env）。
• --dry-run：空运行，模拟接口创建和 Git 镜像操作（地址自动脱敏）。
• -s, --source TEXT：源空间名。
• --source-type TEXT：源空间所有者类型 (org 组织 或 user 用户)。
• -d, --target TEXT：目标空间名。
• --target-type TEXT：目标空间所有者类型 (org 组织 或 user 用户)。
• -i, --include TEXT：指定只迁移的仓库 path 列表，逗号分隔。
• -e, --exclude TEXT：指定排除迁移的仓库 path 列表，逗号分隔。
• --skip-existing/--no-skip-existing：目标库同名存在时，是否跳过代码同步。

⚠️ repo-cli gitee delete - 批量物理删除仓库 (高危)

批量删除指定所有者名下过滤出的仓库。该操作为物理删除且完全不可逆，请极其谨慎地使用。

repo-cli gitee delete [OPTIONS]

• --config -c PATH：项目配置文件路径（默认：config.yaml）。
• --env-file PATH：环境变量 .env 路径（默认：.env）。
• --dry-run：空运行，仅模拟删除结果汇报而不实际发起 API 物理删除请求。
• -o, --owner TEXT / --org TEXT：待删除的空间标识。
• --owner-type TEXT：空间所有者类型 (org 组织 或 user 用户)。
• -i, --include TEXT：指定只删除的仓库 path，逗号分隔。
• -e, --exclude TEXT：指定排除删除的仓库 path，逗号分隔。
• -f, --force / --no-force：强制删除。如果为 --no-force，必须在控制台中手动核对并输入空间名作为“密码锁”才能执行；指定 --force 将直接跳过安全锁。

⚙️ repo-cli config show - 查看当前生效配置

渲染显示当前配置文件和默认值合并后的生效配置表格：

repo-cli config show [-c, --config CONFIG_FILE_PATH]

---

🏗️ 项目架构

repo-cli/
├── src/repo_cli/
│   ├── __init__.py          # 包版本声明
│   ├── utils.py             # 通用文件与路径查找过滤工具
│   ├── cli/
│   │   ├── app.py           # Typer 主入口及命令树注册
│   │   ├── init_cmd.py      # 本地 init 初始化命令
│   │   ├── remote_cmd.py    # 本地 remote 维护命令
│   │   ├── sync_cmd.py      # 平台 sync 同步备份命令
│   │   ├── migrate_cmd.py   # 平台 migrate 仓库迁移命令
│   │   └── delete_cmd.py    # 平台 delete 批量物理删除命令
│   └── core/
│       ├── platform.py      # 平台 Client 接口定义与工厂
│       ├── gitee.py         # GiteeAPIClient 具体实现 (重试、去重、204处理)
│       ├── git.py           # Git 本地命令行交互接口
│       └── config.py        # 配置文件读取与深度深合并策略
├── config.yaml              # 默认参数配置文件
├── .env.example             # 凭证环境变量文件模版
├── pyproject.toml           # Hatch/Hatchling 构建声明
└── README.md

📄 许可证

MIT LicenseXT`：源空间标识。